fengjun/ag-index
1
0
Fork 0
Code Activity

up

Browse Source
This commit is contained in:
fengjun
2026-04-16 09:55:08 +08:00
parent 70de543ce9
commit 353a22badf
1 changed files with 0 additions and 521 deletions
Download Patch File Download Diff File Expand all files Collapse all files

521
docs/superpowers/specs/2026-04-16-vite-low-intrusion-mpa-design.md
View File

@@ -1,521 +0,0 @@
# 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 第一阶段接入将成为整站后续优化的基础设施，而不是一次性重构的起点。