522 lines
14 KiB
Markdown
522 lines
14 KiB
Markdown
# 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 对本次设计的约束影响
|
||
|
||
这些现状意味着：
|
||
|
||
1. Vite 必须按 **MPA（多页面应用）** 方式接入，而不是 SPA 模型。
|
||
2. 第一阶段必须尽量保守，不应强行把旧脚本收编成模块。
|
||
3. 目录层级和相对路径兼容性比“资源自动最优打包”更重要。
|
||
4. `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` 的策略
|
||
|
||
第一阶段保留现有运行时加载方式：
|
||
|
||
```js
|
||
$("#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 第一阶段接入将成为整站后续优化的基础设施，而不是一次性重构的起点。
|