fengjun/ag-index

Fork 0

Files

fengjun 36ce5c07c5 docs: add vite low-intrusion MPA design spec

2026-04-16 09:40:28 +08:00

14 KiB

Raw Blame History

Vite 低侵入接入设计（多页面静态站）

日期： 2026-04-16
项目： AgWeb 静态企业站
目标： 在不重构现有站点架构的前提下，为当前多页面静态网站接入 Vite，提供稳定的开发、构建与可直接部署的生产产物。

1. 背景与目标

当前项目是一个传统多页面静态站：根目录下存在大量 .html 页面，公共资源位于 assets/，页面脚本以 jQuery 和全局脚本顺序加载为主，header.html / footer.html 通过运行时 .load() 拉取。项目目前没有任何包管理、构建流程或统一的生产输出目录。

本次接入的目标不是把站点现代化重写，而是先建立一层稳定的构建底座，使项目具备以下能力：

使用统一命令进行本地开发
使用统一命令输出生产构建产物
产出一个可直接静态部署的 dist/ 目录
保留当前多页面结构、相对路径部署模型和大部分旧代码行为
为后续首页性能优化和局部模块化收编提供基础设施

2. 非目标（明确不做）

以下内容不属于本次设计范围：

不把整站改造成 SPA / CSR 应用
不引入 Vue、React 或其他 UI 框架
不要求把所有 JS 改写为 ESM 模块
不立即替换 jQuery 及其插件体系
不立即把 header.html / footer.html 改成构建期注入
不立即重构整站 CSS 架构
不把“接入 Vite”与“首页性能彻底治理”绑定为同一阶段目标

这样划边界的原因很简单：当前项目的价值在于先低风险建立构建与部署流程，而不是一次性重做前端技术栈。

3. 项目现状理解

3.1 当前结构

项目当前是典型多页面静态站：

根目录：大量面向访问的 .html 页面
assets/：CSS、JS、图片、字体等公共资源
classiccase/：案例子目录页面
huace/：独立子目录页面
header.html / footer.html：公共片段

3.2 已知技术特点

HTML + Bootstrap 3.3.4 + jQuery
依赖脚本顺序与全局变量
大量相对路径资源引用
公共头尾通过运行时 .load() 获取
没有现成 package.json、vite.config、锁文件或前端工程化配置

3.3 对本次设计的约束影响

这些现状意味着：

Vite 必须按 MPA（多页面应用） 方式接入，而不是 SPA 模型。
第一阶段必须尽量保守，不应强行把旧脚本收编成模块。
目录层级和相对路径兼容性比“资源自动最优打包”更重要。
header.html / footer.html 必须被视为运行时依赖的静态片段，而不是普通入口页面。

4. 方案选型

4.1 被考虑的方案

方案 A：Vite 低侵入多页面接入（推荐）

保留现有 HTML 页面与资源目录，把 Vite 用作多页面静态站的开发服务器与生产构建器。第一阶段以“构建稳定”和“可部署”优先，不强行收编旧脚本体系。

方案 B：Vite + 同步结构整理

接入 Vite 的同时，顺便调整头尾复用方式、首页资源加载、重点页面 JS 入口组织。这能带来更大中期收益，但改动面明显增大，不符合本次“低侵入”目标。

方案 C：继续保持纯静态站，只增加零散压缩工具

可以做局部压缩，但不能形成统一开发/构建/输出体系，后续演进空间小，不能满足本次目标。

4.2 推荐方案

选择 方案 A：Vite 低侵入多页面接入。

4.3 选择理由

最匹配当前站点形态
最符合“原样可部署”的要求
风险最低
不会把“构建底座建设”和“站点重构”混成一件事
能为后续按页面优化资源加载提供稳定基础

5. 目标产物与使用方式

接入完成后，项目应具备以下使用方式：

5.1 开发命令

npm install
npm run dev

5.2 构建命令

npm run build
npm run preview

5.3 输出结果

构建后得到：

dist/index.html
dist/company.html
dist/contact.html
dist/product_*.html
dist/solution_*.html
dist/classiccase/*.html
dist/huace/huace.html
dist/assets/...
dist/header.html
dist/footer.html

5.4 部署要求

dist/ 应能作为普通静态目录整体部署：

可放在 Nginx 静态目录下
可部署到对象存储/CDN 静态站
不依赖服务端模板系统
不依赖 SPA 路由重写
仍按相对路径站点模型运行

6. 结构设计

6.1 新增文件

本次应新增最小工程化文件集：

package.json
vite.config.js
.gitignore
可选：开发说明文档补充

各文件职责

package.json 仅承担工具入口职责：

安装 vite
提供 dev / build / preview 命令

vite.config.js 是核心配置文件，负责：

多页面入口配置
输出目录配置
相对路径部署兼容
非入口静态文件保留策略

.gitignore 负责忽略：

node_modules/
dist/

6.2 保留现有目录结构

以下目录和结构在第一阶段保留不动：

根目录 HTML 页面
assets/css
assets/js
assets/images
assets/fonts
header.html
footer.html
classiccase/
huace/

设计上，Vite 接入应适配现有结构，而不是要求现有结构先重排后接入。

7. 多页面入口策略

7.1 入口页面的定义

入口页面必须满足：

用户会直接访问
页面是完整 HTML 文档
有独立 URL 语义

7.2 第一阶段纳入入口的页面

根目录页面

包括但不限于：

index.html
company.html
contact.html
culture.html
joinus.html
各类 product_*.html
各类 solution_*.html
其他实际对外页面

子目录页面

包括：

classiccase/*.html
huace/huace.html

7.3 不作为入口的文件

以下文件不应纳入多页面入口集合：

header.html
footer.html

原因

它们不是独立页面，而是运行时被 .load() 获取的片段。若错误地把它们当作入口页面处理，会混淆构建语义，也不利于后续逐步替换片段加载模式。

8. 静态资源与片段处理策略

8.1 `assets/` 的策略

第一阶段将 assets/ 视为兼容层，而不是重构对象。

也就是说：

现有页面继续使用 assets/... 相对引用
构建后仍保留 dist/assets/... 语义
尽量不要求页面把资源改写为模块导入

理由

如果第一阶段就要求所有图片、CSS、JS 都纳入现代模块导入体系，改动面会迅速扩大，和“低侵入接入”目标冲突。

8.2 `header.html` / `footer.html` 的策略

第一阶段保留现有运行时加载方式：

$("#header").load("header.html");
$("#footer").load("footer.html");

但设计上必须把这视为一个明确兼容要求：

构建后片段文件必须仍然存在于 dist/ 中
片段路径关系不能因构建被破坏
根目录页面和子目录页面都必须验证其加载行为

8.3 其他运行时静态依赖

若后续发现还有类似 header/footer 的运行时请求文件，也应归入“静态保留文件”，而不是强行纳入入口页面集合。

9. 路径与部署设计

9.1 核心约束

用户明确选择的是：

构建后产物应原样可部署
dist/ 应可作为静态站整体拷贝部署
不应要求服务端特殊模板或路由逻辑

9.2 路径策略

因此路径设计必须围绕以下原则：

采用适合相对路径部署的 Vite 配置
构建后不能假设站点一定部署在域名根路径
子目录页面构建后仍需能正确解析其资源路径与片段路径

9.3 兼容重点

这套设计中最需要重点看护的是：

根目录页面资源路径
子目录页面资源路径
子目录页面对 header/footer 的请求路径

因为相对路径在不同目录层级上的含义不同，这部分是第一阶段成功与否的关键风险点。

10. 实施边界与脚本策略

10.1 为什么不立即收编旧脚本

当前脚本体系强依赖：

<script> 加载顺序
jQuery 全局变量
插件注册顺序
页面初始化时机

如果在接入 Vite 的同时强行把这些脚本全部改成模块入口，就会把接入工作从“构建底座建设”升级成“脚本体系迁移”，风险显著增加。

10.2 第一阶段脚本原则

第一阶段应遵循：

保守保留现有脚本加载顺序
不主动改写脚本组织方式
不把“旧脚本模块化”作为接入完成条件

10.3 这意味着什么

这意味着第一阶段的收益重点在：

开发入口统一
构建入口统一
产物目录统一
部署方式更规范

而不是立刻实现最优的 JS 打包策略。

11. 实施步骤建议

步骤 1：建立工程化骨架

新增：

package.json
vite.config.js
.gitignore

目标：先让项目具备工程化外壳，而不是一次性吃下全站页面。

步骤 2：先接通根目录核心页面

建议第一轮先覆盖：

index.html
company.html
contact.html
一个产品页
一个方案页

目标：先验证根目录页面在构建后是否稳定。

步骤 3：再纳入子目录页面

包括：

classiccase/*.html
huace/huace.html

目标：验证相对路径与片段加载在子目录层级下的兼容性。

步骤 4：单独验证 `header/footer`

分别验证：

若这一步出问题，应先修路径兼容，不应继续扩大构建覆盖面。

步骤 5：扩展到剩余全部页面

在核心页面和子目录样本都稳定后，再把剩余页面完整纳入入口配置。

步骤 6：完成构建与静态部署验收

最终确认 dist/ 可以作为普通静态站整体托管运行。

12. 风险分析

风险 1：子目录页面相对路径失效

这是最大风险。classiccase/ 和 huace/ 下页面对 assets/ 及片段路径的解析可能与根目录页面不同。若构建后目录层级或路径处理不一致，会直接导致样式、脚本或片段加载失败。

风险 2：`header/footer` 运行时路径不一致

根目录页和子目录页若统一写死 header.html，其路径含义未必一致。必须把这部分作为单独验证项，而不是默认认为首页通过即可代表整站通过。

风险 3：脚本顺序依赖被无意破坏

当前页面依赖脚本顺序和全局变量，接入时若修改了注入位置、执行时机或引用顺序，可能出现 $ is not defined、插件未注册或初始化提早执行等问题。

风险 4：对 Vite 收益预期过高

第一阶段主要收益是“有构建体系”，不是“自动现代化站点”。若把首页资源治理、插件拆分、头尾构建期注入等都期待为接入后的立即结果，容易误判接入价值。

风险 5：本地预览通过但静态部署不一致

Vite preview 的成功不自动等于真实静态部署也成功。最终必须以“普通静态服务托管 dist/ 的结果”为准。

13. 验证策略

13.1 构建层验证

必须确认：

npm install 成功
npm run dev 成功
npm run build 成功
npm run preview 成功

13.2 页面覆盖验证

不能只看首页。至少需要覆盖：

首页
根目录普通页面
产品页
方案页
至少 2–3 个 classiccase 页面
huace/huace.html

通过标准：

页面能打开
样式正常
图片正常
JS 无致命错误

13.3 公共片段验证

必须单独确认：

根目录页 header/footer 正常
子目录页 header/footer 正常
无 404 请求

13.4 静态部署模拟验证

最终验证标准应是：

dist/ 被普通静态服务托管后仍能正常运行
不依赖 Vite 专属运行时
相对路径部署可行

14. 接入完成定义

以下全部成立，才能认为第一阶段接入完成：

构建命令层

npm install 成功
npm run dev 成功
npm run build 成功
npm run preview 成功

页面层

index.html 正常
company.html 正常
contact.html 正常
至少一个产品页正常
至少一个方案页正常
至少两个 classiccase 页面正常
huace/huace.html 正常

资源层

assets/css 正常加载
assets/js 正常执行
图片资源无大面积 404
字体资源正常

片段层

根目录页 header/footer 正常
子目录页 header/footer 正常

部署层

dist/ 可被普通静态服务直接托管
不要求额外模板系统
不要求额外路由重写

15. 第二阶段建议（接入后最值得做的事）

本次接入完成后，建议按以下顺序继续优化：

第二阶段 1：首页资源加载策略治理

优先处理：

首屏轮播图 preload 与实际资源不一致
重复 d3.min.js
首页多余 CSS preload
首页大图压缩

第二阶段 2：首页 JS 逐步收编

仅针对首页，把真正需要的逻辑逐步整理成更清晰的页面级入口，而不是一开始就收编全站。

第二阶段 3：`header/footer` 构建期复用

等路径兼容和构建稳定后，再考虑把头尾从运行时 .load() 迁移到构建期复用，减少请求和路径脆弱性。

第二阶段 4：旧插件包治理

重点评估并拆解 jquery-plugin-collection.js 这类大包，减少首页无关负担。

第二阶段 5：CSS 收编与裁剪

在构建底座和重点页面资源稳定后，再处理 style.css、animate.css 等样式冗余问题。

16. 最终结论

这次接入的本质不是“把站点改造成现代框架项目”，而是：

在不破坏现有站点结构与部署模型的前提下，为项目建立一个稳定的多页面开发、构建和部署底座。

这项工作的价值在于：

让项目从“纯手工静态文件管理”进入“可构建、可输出、可持续优化”的状态
后续首页性能优化、局部模块化、公共片段治理，都能在更稳定的基础上进行

如果后续演进顺利，Vite 第一阶段接入将成为整站后续优化的基础设施，而不是一次性重构的起点。

14 KiB Raw Blame History Unescape Escape