vscode-workbench/PLANNING/tasks/C-05-SEO预渲染.md

C-05 · 工具页 SEO 预渲染

字段	值
项目	可乐工具 · chunyu_project_react（构建层）+ 部署配置
优先级	P1 · M3
建议模型	deepseek-v4.1-flash（主）/ kimi-k3（全页 meta 核查）
依赖	C-01（路由先稳定）
预估	2.5 天

一、背景（为什么做)

工具站的核心获客渠道是搜索引擎（"时间戳转换""JSON 格式化"都是大流量词），菜鸟工具/tool.lu 全部吃 SEO 流量。本项目 Vite SPA 纯客户端渲染，蜘蛛抓不到任何工具内容——SEO 基本为零（docs/产品问题分析与改造路线.md P0-4）。

二、目标（交付物）

1. 构建期预渲染：全部工具详情页（20+ 工具页路由）在 npm run build 时产出含完整正文的静态 HTML（推荐 vite-plugin-prerender 或独立 puppeteer 脚本，按项目现状选型；产出直接进 dist/）。
2. 每页独立 meta：<title>、<meta name="description">、OG 标签（og:title/og:description/og:image），内容从工具的 name/description 字段生成；不重复不空。
3. sitemap.xml + robots.txt：sitemap 覆盖全部工具 URL（含首页、工具列表、分类页），robots 放行蜘蛛、指向 sitemap。
4. 部署接线：nginx 对预渲染产物优先返回静态 HTML；不破坏 SPA 接管（首屏 HTML 后 React 正常 hydrate 交互）。
5. 工具页组件支持标题/描述注入（小型 hook 或 helmet 类方案，按项目现状）。

三、执行步骤

1. 盘点全部需预渲染的路由清单（工具页 + 分类页 + 首页）
2. 选型预渲染方案并接入构建流程（保持现有构建命令不变）
3. 每页 meta 注入
4. sitemap/robots 生成脚本（构建后自动产出）
5. 本地构建 → curl 验证产物 HTML 含正文
6. nginx 配置片段更新（预渲染优先），写明部署要点

四、验收标准

• npm run build 后 dist/ 内每个工具页 HTML 含完整正文（curl 静态文件可见关键内容，非空 #root）
• 每页 <title> 唯一且语义化；description 非空
• sitemap.xml 覆盖全部工具 URL（数量与路由清单一致）
• robots.txt 正确放行 + 指向 sitemap
• 浏览器访问预渲染页：内容先现、React 正常接管交互（无闪烁错乱）
• 构建时间增加在可接受范围（记录数据）

五、验收命令（参考）

cd chunyu_project_react && npm run build
node scripts/check_seo.mjs   # 本任务交付：扫描 dist 校验 title/description/sitemap 覆盖
curl -s http://localhost:8080/utility/json-formatter | grep -o "<title>.*</title>"

六、边界（不许做）

• 不引入 Next.js 全量迁移（成本不成比例；预渲染即可）
• 不改工具页业务逻辑
• 不预渲染登录态页面（profile/wallet 等一律排除，防信息泄露）

七、交接

写 PROGRESS_C-05.md（含构建产物校验输出、sitemap 覆盖数、构建耗时对照）。