把 700 个工具塞进一个静态站：目录结构与构建管线

把 700 个工具塞进一个静态站：目录结构与构建管线 先说两个真实场景。第一个：某次下线了一个计算器工具，工具目录里的 HTML 文件删了，但首页「最近更新」和分类页的推荐位还挂着它的入口——用户点进去就是 404。排查了半天才发现，站点里渲染这个工具入口的入口有三处：首页、分类页、相关工具推荐块，它们各自持有从数据源里「拷贝」出来的快照，删文件不会同步删引用。第二个：某天给几十个内容页改了正文，本地看都是新的，发到线上搜索引擎却认为页面没更新——因为 sitemap 里的 lastmod 是各生成器各自写的，改了正文忘了跑对应的 lastmod 更新脚本，提交的 sitemap 还是旧日期。这两个坑的共同点很扎心：静态站没有运行时，所有「数据一致性」问题都会在构建期或者发版后才暴露，而且一旦暴露就是线上事故。页面从 100 个涨到 700 多个的过程中，我把整个站的组织方式推翻重来了两轮，最后沉淀出一套「单一数据源 + 模板生成 + 一致性闸门 + 一键发版回滚」的管线。这篇文章把这套结构讲清楚，代码示例都是简化版，思路可以直接搬到任何上千页的静态项目上。## 一、单一数据源：所有页面只认一个文件最初的版本里，每个工具页是手写的独立 HTML。300 个以内还能忍，超过 400 个之后，改一个公共导航就要动 400 个文件——显然不可持续。重构的第一刀，是把「工具是什么」收敛到一个 JS 数据文件里：js// tools-data.js —— 全站唯一的工具登记处module.exports = [ { slug: 'bmi-calculator', // 决定 URL 和文件名 title: 'BMI 计算器', cat: 'health', // 分类 key keywords: ['bmi', '体质指数'], updated: '2026-10-21', desc: '输入身高体重即刻计算 BMI，附中国标准分级。', js: ['bmi'], // 工具自身逻辑的分片 ui: ['slider-height'], // 交互组件分片 }, // ……700+ 条];目录结构随之固定下来，每个目录只回答一个问题：toolbox/├── tools-data.js # SSOT：工具登记（slug/分类/标题/更新时间）├── tools/ # 700+ 个工具页，全部由生成器产出├── hub/ # 分类页 / 主题聚合页，由生成器产出├── qa/ guides/ refs/ # 内容层：问答、指南、速查表├── _platform/ # 生成器、闸门脚本、发布脚本（不部署）└── sitemap.xml # 由生成器统一拼装，禁止手改这里有一条纪律比代码本身重要：tools-data.js 是唯一允许「登记工具」的地方。任何人（包括我自己）想加一个工具，第一步不是建 HTML 文件，而是往数据文件里加一条记录。HTML 文件是派生物，任何时候都可以 rm -rf tools/ 之后从数据源完整重建——这个性质是后面一切闸门的基础。## 二、模板生成：一类页面一个生成器数据源有了，接下来是「怎么变成页面」。我的原则是按页面类型分生成器，每个生成器只做一件事：| 页面类型 | 数量级 | 生成器职责 ||—|—|—|| 工具页 | 700+ | 读数据源一条记录 → 套模板 → 落盘 tools/<slug>.html || 分类/聚合页 | ~30 | 遍历数据源按 cat 分组 → 生成导航和网格 || 内容层页 | 400+ | 消费独立的问答/指南分片 → 套统一模板 || sitemap | 1 | 汇总前三类的 URL 和 lastmod → 拼装输出 |关键设计是模板与内容分离：模板里只放结构（导航、骨架、统计脚本位），内容全部来自数据分片。分片格式是纯 JSON，用数组强制表达「这里未来可能有多条」，避免后面出现「单条时是字符串、多条时是数组」的类型漂移。生成器天然带来一个好处：批量修 bug。有一次发现所有工具页的统计脚本少了 onload 判空，空引用在部分浏览器直接白屏。手写站的时代这就是 700 个文件的事故；在生成器架构下，改一行模板源码，重跑生成器，700 个文件全部修复。代价是生成器源码本身成了高危资产——我给 _platform/ 目录立了规矩：改任何生成器必须先跑全量构建对比 diff，确认只有预期中的变化。## 三、一致性闸门：让「数对不上」在构建期爆炸文章开头两个坑，本质都是「派生物和源头不一致」。这类问题靠人肉检查是不可能的，唯一出路是把一致性变成可执行断言，挂进构建流程：```js// check-consistency.js —— 三方一致性闸门（简化版）const data = require(‘./tools-data.js’);const files = fs.readdirSync(‘tools’).filter(f => f.endsWith(‘.html’));const sitemap = fs.readFileSync(‘sitemap.xml’, ‘utf8’);const locs = […sitemap.matchAll(/[<sup><]*/tools/([</sup><]+).html</loc>/g)] .map(m => m[1] + ‘.html’);const fromData = data.map(t => t.slug + ‘.html’).sort();const a = fromData, b = […new Set(files)].sort(), c = […new Set(locs)].sort();if (JSON.stringify(a) !== b || JSON.stringify(a) !== c) { console.error(‘三方不一致：’, ‘data 独有:’, a.filter(x => !b.includes(x)), ‘文件独有:’, b.filter(x => !a.includes(x)), ‘sitemap 独有:’, c.filter(x => !a.includes(x))); process.exit(1); // 直接炸掉构建，禁止带病发版}console.log(三方一致 ✓ 共 ${a.length} 个工具);```这个脚本就是当年那个「删了文件但首页还挂着入口」事故的直接产物。它检查的是三个集合严格相等：数据源登记数 = 磁盘 HTML 文件数 = sitemap 里的 tools URL 数。任何一环多一个少一个，构建直接失败，错误信息里直接列出差集——修起来是分钟级的事。同样的思路推广到了全站，陆续加了一排小闸门：内容层查重（防止两个页面讲同一件事，被判低质聚合）、分片格式校验（问句标题、表格最少行数、禁用某些引号——都是踩坑换来的规则）、版本号必 bump（Service Worker 缓存页面列表变了但版本没变，用户端永远拿旧缓存）。单看每一条都琐碎，合起来构成了一个事实：构建通过 = 站点自洽。## 四、发版管线：把 12 步操作压成一条命令闸门齐了之后，发版本身也该自动化。我最长的手动发版记录是 12 步：改数据 → bump 版本 → 重生成工具页 → 重生成分类页 → 同步计数 → 跑一致性检查 → 更新 sitemap lastmod → 冒烟测试 → 打包 → 上传 → 刷 CDN → 提交推送。每一步都可能忘，忘了哪步哪步就变成线上 bug（lastmod 那个坑就是这么来的）。现在的 package.json 长这样：```json{ “scripts”: { “check”: “node gate/health.js && node gate/smoke.js && node gate/audit.js”, “sync:sitemap”: “node _platform/gen-sitemap.js –apply”, “release”: “npm run check && node bump-sw-version.js && npm run sync:sitemap && node pack-release.js” }}````npm run release一条命令把检查、版本、sitemap、打包串起来，任何一环失败整条中断。它不能防住所有问题，但能保证**所有已知的问题都会在同一条流水线上被拦截**，而不是散落在某次「我印象里跑过了」。## 五、回滚：发版前先留后路静态站的优势是回滚天然便宜——旧的文件包还在，换回去就行。但前提是你真的留了。我的做法是双保险：1. **git tag**：任何结构性改版动手之前，先打rollback-before-<改动名>的 tag。改挂了git reset –hard 秒回。2. **完整 zip 快照**：每次发版打包出的 zip 就是当时站点的完整快照，按日期归档，永不删除。线上出问题时，解压旧包覆盖回源站，一分钟内恢复——哪怕本地工作区已经被后续改动污染了也不怕。这两招在实操里救过场：一次批量改版把导航样式改坏，线上用户已经在反馈，靠当天早上的 zip 快照五分钟回滚完毕，然后在本地慢慢排查。**回滚方案不是给「不会出 bug」的人准备的，是给一定会出 bug 的人准备的。**## 六、踩坑清单把这套管线里付出过学费的坑汇总成表，给后来者省点钱：| 坑 | 现象 | 修法 ||—|—|—|| 派生物残留引用 | 删了工具页，首页/推荐位还有入口，点了 404 | 三方一致性闸门 + 派生物永远由生成器重产出 || lastmod 忘记联动 | 改了正文但 sitemap 日期没变，搜索引擎不抓新内容 | lastmod 从数据分片统一取值，收进发版命令 || SW 版本没 bump | 页面列表变了，用户端缓存不更新 | bump 收进 release 脚本第一个执行 || 生成器临时补丁 | 为了赶某个页面直接改产物 HTML，下次重生成被覆盖 | 立规矩：产物永禁手改，需求进模板 || 手改 CDN 上的文件 | 线上和本地悄悄分叉，后续发版覆盖掉修复 | 线上只读，一切修复走本地 → 发版 |## 七、结论：三条可操作的判断最后给三条判断，都是从上千页规模的实际运维里反推出来的：1. **页面数量超过「一个文件一个文件数得过来」的程度，就必须有单一数据源**。粗略的界线在 50 页：50 页以内手写 HTML 是效率，50 页以上手写就是事故预备役。2. **一致性必须做成会爆炸的断言，而不是会遗漏的 checklist**。任何「上线前记得检查一下」类的规则，在三个月后必然被遗忘；process.exit(1)不会遗忘。3. **发版命令的长度决定线上事故率**。一条npm run release` 和一页 SOP 文档的区别是：前者不会跳步。回滚快照同理——它是发版动作的一部分，不是事后补救。这套管线目前支撑着一个收录了 700 多个纯前端工具的静态站点，从计算器、格式转换到文本处理都在跑，所有工具在浏览器本地完成计算、文件不上传服务器——这些工具我整理成了速查在线工具箱，感兴趣可以当作这套架构的实际样例去看。如果你的项目也在往几百页的规模长，希望这篇里的数据源、闸门和回滚三板斧能帮你少踩几个坑。