# 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 类方案，按项目现状）。

## 三、执行步骤

```text
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 正常接管交互（无闪烁错乱）
- [ ] 构建时间增加在可接受范围（记录数据）

## 五、验收命令（参考）

```bash
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 覆盖数、构建耗时对照）。