vscode-workbench/PLANNING/PROGRESS_C-05.md

PROGRESS — C-05 · 工具页 SEO 预渲染

• 状态：done

日期 2026-09-13 · 范围：chunyu_project_react（构建层脚本+nginx.conf）+ 校验脚本

现状 vs 差距（接手时）

• 已有：Vite SPA（dist/index.html 纯空 #root + 单一 <title>chunyu_project）、nginx SPA 回退、 scripts/check_routes.mjs（C-01 路由回归）。
• 缺口：蜘蛛抓不到任何工具页正文；无 sitemap/robots；无单页 meta。

选型

独立 Node 后处理脚本（scripts/seo_prerender.mjs，零新依赖），不引入 vite-plugin-prerender/puppeteer： 构建命令不变（build 链尾追加），失败即中断构建（&& 链），产出直接进 dist/。

改动（chunyu_project_react/）

1. scripts/seo_prerender.mjs（新建）：工具清单与后端 seed_tools.py 同源（16 启用工具， url_path/name/description 对齐）；每工具页直出 dist/<url>/index.html（独立 title/description/ keywords/canonical/OG + 静态正文 h1+说明+相关工具链 + #root 占位 + location.replace 跳转， React hydrate 后照常接管）；聚合页 /（dist/index.seo.html，不覆盖 SPA 外壳）、/utility、/top； sitemap.xml（19 URL）+ robots.txt（放行蜘蛛、屏蔽 profile/wallet/console/messages/chat、指向 sitemap）。
2. scripts/check_seo.mjs（新建，任务卡验收脚本）：工具页存在/唯一 title/非空 description/ 静态正文/OG、聚合页、sitemap 覆盖 19 URL、robots 口径、SPA 外壳完好、清单 16 条对齐。
3. package.json：build 链尾 && node scripts/seo_prerender.mjs；新增 seo / seo:check 快捷命令。
4. nginx.conf：location = / 优先 index.seo.html；工具页正则 location 优先 try_files 静态 HTML （1h 缓存）；登录态页（/post、/profile 等）不命中，落 SPA 回退。

边界遵守

• 无 Next.js 迁移；工具页业务零改；登录态页（profile/wallet/console/messages/chat）robots + nginx 双屏蔽。

验证

pnpm build
# ✓ built in ~12s（含 tsc -b）；[seo] prerender done: 19 html + sitemap(19 urls) + robots.txt in 15ms
node scripts/check_seo.mjs
# SEO CHECK ALL GREEN (16 tools + 3 pages) —— 逐页 PASS 明细见终端输出
curl 等价：dist/utility/json-formatter/index.html → <title>JSON格式化 - 免费在线工具 | 可乐开发工具箱</title>，含 <h1> 正文
nginx：本地无二进制/docker 未起，改用 location 自查——预渲染块在 SPA 回退前、
  16 工具+聚合命中 SEO、/post/1 与 /profile 走 SPA、大括号平衡（node 自查脚本全对）

构建耗时：C-06 轮 14.99s → 本轮 11.87s（机器波动范围内），SEO 脚本本身仅 +15ms。

状态

done。遗留：--base 当前为 https://tools.example.com 占位符——部署时带真实域名重跑 node scripts/seo_prerender.mjs --dist dist --base https://真实域名 刷新 sitemap/OG/canonical； 浏览器“首屏先现+React 接管”需线上 nginx 联调时录屏补证据。