# 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 为什么不立即收编旧脚本 当前脚本体系强依赖： - `