用Claude Code做JavaScript SEO：修改模板前先建立证据文件夹

JavaScript SEO 真正危险的地方，不是运行检查清单，而是因为某项检查听起来合理，就直接修改多个页面共用的模板。分类页在你的浏览器里可能看起来完全正常，但链接实际上依赖点击事件、实用内容很晚才出现，或者 canonical 与 HTTP 响应传递了不同信号。错误的“SEO 修复”可能破坏导航、数据分析、无障碍体验，甚至影响所有使用该组件的页面。

Claude Code 最有价值的用法，是把一个真实的页面观察，连接到最小的相关代码路径、可供审查的 diff，以及一组测试。它不应该从重写框架或直接部署补丁开始。

完成这套流程后，你会得到： 一个存储库证据文件夹、一条本地调查规则、一份从单个页面症状连接到可能相关文件的地图、一份经负责人批准的实施说明，以及一条完成测试的变更记录。这里的“完成”不代表 Google 已重新抓取页面，也不代表排名已经提升。

第一部分：打开存储库之前，先理解JavaScript SEO

页面依赖JavaScript时，会有什么不同

Web 服务器会对 URL 返回响应。这份响应可能已经包含页面的主要内容，也可能只包含一个外壳，要求浏览器运行脚本并继续请求数据。之后，浏览器才构建最终的页面状态。

搜索系统也必须发现 URL、获取响应、处理允许访问的资源，并理解最终形成的页面。使用现代 JavaScript 本身不会自动造成 SEO 问题。问题通常出现在重要步骤不可靠，或者页面的不同层面传递不同信息时。

对新手来说，可以使用下面这个模型：

发现 URL
  -> 收到服务器响应
  -> 处理 HTML 和资源
  -> JavaScript 与数据请求完成
  -> 解读内容、链接与页面信号
  -> 搜索系统决定是否以及如何收录该 URL

每个箭头都可能失败，而存储库只包含部分证据。代码可以显示组件原本打算如何运行，却无法单独告诉你 Google 收录了哪个 URL、昨天某次线上请求是否失败，或者特定设备上的用户实际经历了什么。

不要把“JavaScript”当成一个问题，请检查六种页面行为

1. URL返回预期的状态

正常页面通常返回 200。已删除的页面应该传递有意义的 not found 或 gone 状态。重定向应该到达预期的最终 URL。客户端重定向可能更慢，也可能掩盖在 HTTP 层更容易发现的错误。

2. 主要内容可以获取

定义页面的文字和项目，应该出现在相关响应或渲染完成的状态中。请记录内容是否需要脚本、数据请求、滚动、点击、登录或其他条件才会出现。内容不在源 HTML 中是一项观察，并不等于页面一定无法被收录。

3. 重要目标是实际链接

搜索系统通常通过标准链接发现目标。只依靠 onClick、按钮或片段导航的卡片，在视觉上可能可以使用，却可能提供较弱的 URL 发现路径。合适的修复也许是加入真正的链接，但必须保留键盘操作、数据分析、样式和应用路由。

4. canonical、robots和站点地图信号一致

请确认请求 URL、canonical 目标、robots 指令、内部链接和站点地图条目都指向同一个首选页面。canonical 是提示，不能代替清晰的 URL 处理，也不应该指向无关页面。

5. 延迟加载和无限滚动具有可到达状态

延迟加载可以改善性能，但重要内容不应该依赖任意交互。无限滚动通常应该提供稳定的分页 URL，或者通往更深层项目的其他可抓取路径。具体实现取决于网站，因此提出变更之前要先检查现有路由和数据模型。

6. 元数据与结构化数据符合可见页面

title、canonical、robots 指令和结构化数据可能在 JavaScript 运行后才生成。它们应该准确且一致地描述可见内容。结构化数据有助于理解页面，但不保证富媒体搜索结果或排名。

分开四种证据

使用存储库智能体时，这种区分格外重要。Claude Code 很擅长追踪组件，但越接近代码调查，越容易把看似合理的机制误当成已确认原因。

写下一个以证据为基础的症状

不要从“Google 无法渲染我们的网站”开始。这句话包含了你可能尚未证明的结论。请使用更精确的表述：

在提供的分类页记录中，商品名称会在渲染后出现，但渲染后 DOM 的商品卡片不包含标准目标链接。搜索引擎收录状态未知。

这让 Claude Code 有一个具体对象可以追查，也把调查限制在负责分类卡片和导航的代码，而不是应用里的所有渲染决策。

第二部分：建立从证据走向已审查diff的Claude Code工作流

准备存储库证据文件夹

选择一个不属于应用源代码的位置。沿用存储库现有的生成产物或报告规则；如果没有规则，可以从以下结构开始：

reports/javascript-seo/
  collection-page-links/
    page-story.md
    response-notes.md
    rendered-notes.md
    search-evidence.md
    decision.md

文件夹应该回答四个问题：正在调查哪个页面、观察到了什么、哪些资料仍无法获取，以及负责人做了什么决定。如果页面记录和导出文件不应该进入版本控制，请把它们设为忽略项。

绝对不要在文件夹中放入 Cookie、API 令牌、密码、私密客户数据或不受限制的导出文件。把证据交给任何工具之前，都要先遮盖私密 URL 和用户信息。

在负责人批准实施说明之前，请让只读调查记录与源代码保持分离。

在第一个提示词之前添加存储库规则

把政策放进项目现有的 Claude Code 指引位置，例如相关的 CLAUDE.md 或现有 .claude 规则。如果项目已经有指令体系，就不要另建第二套。

## JavaScript SEO 调查政策

- JavaScript SEO 工作从只读证据收集开始。
- 调查记录只能存放在获批的证据目录。
- 分开观察事实、可能机制、未知事项和负责人决策。
- 在具名实施说明获得人工批准前，不得编辑源代码、路由、robots 规则、
  内容、CMS 数据、部署文件或 CI。
- 除非提供获得授权的导出资料，否则将 Search Console、抓取日志、
  线上指标和收录状态视为无法获取。
- 绝不暴露机密、Cookie、令牌、私密 URL 或客户数据。
- 批准后执行范围最小的变更、显示 diff、运行约定测试，并说明回滚条件。
  除非另行授权，否则不得部署。

这项规则能提供持续指引，但本身不是强制执行层。仍然需要结合项目适用的存储库权限、分支保护、命令批准和代码审查。

创建页面故事

添加简短的 page-story.md，让存储库调查始终连接到页面用途。

## 页面
https://example.com/collections/shoes

## 访客任务
比较现有鞋款并打开商品页面。

## 必要页面元素
- 分类标题
- 商品名称和价格
- 稳定的商品目标
- 一致的 title、canonical、robots 指令和状态

## 观察到的症状
提供的渲染 DOM 中有商品卡片，但没有标准商品链接。

## 可用证据
- 保存的响应记录
- 渲染后 DOM 摘录
- 存储库签出内容

## 无法获取的证据
- Google URL 检查
- 服务器日志
- 线上真实用户指标

## 禁止操作
调查期间不得编辑源代码、部署、修改 CMS、提交 URL 或发送外部消息。

页面故事可以防止调查偏离成一般代码审查。

请Claude Code绘制代码地图，而不是立即修复

第一个提示词请使用只读模式：

以只读模式调查一个 JavaScript SEO 症状。

页面故事：reports/javascript-seo/collection-page-links/page-story.md
证据文件夹：reports/javascript-seo/collection-page-links/

阅读存储库指引。只检查可能负责所述页面和症状的代码路径。请返回：
1. 已确认的证据摘要
2. 可能相关的路由、模板、组件和数据路径，以及判断理由
3. 不确定之处和缺少的数据
4. 最小的实施选项
5. 验收检查和回滚条件

不要编辑文件、安装软件包、部署、调用可写入 API，也不要声称 Google 已收录或
未收录该页面。完成调查说明后停止。

预期输出： 一份从页面路由连接到模板、组件、导航行为和相关测试的地图。质量检查： 每个候选文件都要连接到观察到的症状。恢复方式： 如果答案提出框架迁移，请改问可逆、模板级别的最小选项及其证据。

像开发人员一样审查代码地图

实用的代码地图会说明数据和标记如何到达页面。对于分类卡片问题，它可能找出：

• 路由或页面入口
• 分类模板
• 卡片组件
• 创建商品目标的函数
• 导航与数据分析事件处理器
• 现有组件、无障碍或端到端测试

它也应该列出未知事项。也许卡片组件支持 href，但模板没有传入；也许外层容器是为了避免嵌套链接；也许目标来自初始响应时还无法获取的数据。这些是不同机制，需要不同修复。

使用这张表审查：

把地图转成实施说明

开始任何编辑之前，负责人应该批准一份包含以下内容的文档：

Finding（发现）：[一个已观察条件]
Evidence（证据）：[文件或页面记录]
Affected page family（受影响页面组）：[已确认范围]
Candidate mechanism（候选机制）：[代码路径和不确定性]
Approved action（批准操作）：[一个边界明确的变更]
Behavior to preserve（要保留的行为）：[导航、无障碍、分析、样式、路由]
Acceptance checks（验收检查）：[清单]
Rollback condition（回滚条件）：[清单]
Owner（负责人）：[姓名或角色]
Status（状态）：APPROVED FOR LOCAL IMPLEMENTATION / NOT APPROVED

“添加可抓取链接”仍然太宽泛。更好的批准操作会说明组件和预期行为，同时允许代码负责人选择符合现有应用的有效标记。

执行一次受限制的编辑

批准后请开始新的提示词。不要把广泛调查的上下文当成已经授权变更。

只实施下列文档记录的批准操作：
reports/javascript-seo/collection-page-links/decision.md

编辑前，重述受影响文件、要保留的行为、验收检查、禁止操作和回滚条件。

执行最小且完整的变更。不要重构无关代码、修改依赖包、调整部署配置、
编辑 CMS 内容或部署。

编辑后：
- 显示完整 diff
- 只运行已批准的本地检查
- 报告失败但不要扩大范围
- 把结果更新到 decision.md

如果存储库证据与批准的机制矛盾，请停止并返回修订后的说明。

只有在受影响模板、审查关卡、预览检查和回滚路径都清楚时，交接才算完成。

相信说明之前，先检查diff

把 diff 当作主要变更记录来阅读。请确认它：

• 只改动预期文件
• 保留必要的事件处理和数据分析
• 没有加入无效的嵌套交互元素
• 保留键盘和屏幕阅读器行为
• 生成稳定、正确的目标
• 添加或更新相关测试
• 没有暗中修改 robots、canonical、重定向或无关元数据

再流畅的总结，也不能弥补范围过大的 diff。

按照访客和爬虫遇到页面的顺序进行验证

本地与功能行为

构建受影响区域并测试访客任务。使用鼠标和键盘都能打开目标吗？客户端路由仍然运行吗？数据分析要求得到保留了吗？缺少数据时组件是否仍能正确处理？

响应信号

检查预期响应或预览。确认状态、重定向行为、title、canonical、robots 指令，以及预期出现在响应里的主要内容。不要把“查看源代码”当成完整 SEO 结论。

渲染输出

确认最终 DOM 包含预期内容和普通目标链接。测试代表页面，也在适用时测试空白状态、错误状态或数据无法获取的状态。

获得授权的搜索证据

如果团队有 URL 检查、抓取、日志或 Search Console 证据，请单独记录并附上日期。本地预览无法证明 Google 已重新抓取或收录页面。搜索数据可能需要时间才会变化，而且任何实施都不保证排名。

回滚与记录

将批准说明、最终 diff、测试输出、预览引用、日期和负责人决定放在一起。如果应保留的行为失败、范围意外扩大，或者预览不再符合页面故事，请按约定方式回滚。

三个调查示例

没有稳定链接的可点击卡片

观察： 卡片文字可见，但渲染记录显示导航绑定在容器上，而不是普通目标链接。存储库问题： 哪个组件负责主要目标，并如何保留数据分析与无障碍行为？可能的最小变更： 为主要操作添加合适的标准链接。不要假设： 卡片内每个位置都应该变成嵌套链接。

没有深层URL路径的无限滚动

观察： 滚动后出现更多项目，但提供的证据没有通往后续组的稳定页面路径。存储库问题： 数据层是否已支持可映射到 URL 的页码或游标？可能的最小变更： 保留渐进增强，同时公开可抓取分页。不要假设： 必须替换整个界面。

客户端渲染的not found页面返回200

观察： 无法获取的商品在渲染后显示“not found”，但响应记录报告 200。存储库问题： 系统在哪里得知路由不可用，服务器或框架能否返回有意义的状态？可能的最小变更： 在合适的路由边界处理缺失状态。不要假设： 只修改可见文案就能解决响应问题。

常见错误

要求Claude Code审核整个网站

输出会变得宽泛而难以验证。从一个代表 URL 和一则页面故事开始；只有相同机制在更多页面得到确认后，才扩大范围。

把CLAUDE.md当作安全控制

它是指引，不是独立权限系统。请继续使用命令批准、存储库权限和人工审查。

把证据文件混入产品提交

页面记录和导出资料可能包含私密信息或制造杂乱 diff。把它们放在获批且被忽略的目录，只提交有意进行的代码和测试变更。

立即用排名衡量成功

先验证技术目标，之后再使用获得授权的抓取和搜索数据。排名也受到相关性、竞争、内容质量、链接及许多其他因素影响。

因为测试通过而忽略错误页面状态

组件测试可能通过，但线上路由仍会收到不同数据、元数据或状态处理。至少包含一项接近真实访客路径的路由级或预览检查。如果页面有筛选器、分页、无法获取的商品或多语言版本，请说明批准变更覆盖哪些状态，哪些状态不在本次范围。

未检查范围就编辑共享组件

分类卡片也可能出现在搜索、推荐、购物车或账户页面。变更前，请 Claude Code 找出组件的使用位置，并判断建议标记是否会影响这些场景。如果答案扩大了范围，就把新说明交回负责人，不要让小修复悄悄变成重新设计。

从头到尾完成第一个实际案例

假设页面故事说明访客要比较商品并打开详情。证据文件夹中有一段渲染后 DOM，显示商品名称，但没有普通目标链接。Claude Code 读取项目指引，把路由连接到分类模板，再连接到可复用卡片组件和导航事件处理器。它还报告该组件与推荐列表共用，因此范围仍不确定。

真正有用的结果不是立即打补丁。负责人现在可以在两个边界明确的下一步中选择：检查组件在两个场景中的使用方式，或者建立一个提供有效主要目标的分类专用包装组件。负责人做出选择后，实施提示词要指定受影响文件、必要测试、应保留的数据分析行为和回滚条件。

补丁完成后，团队检查渲染后的分类页面，使用键盘导航打开目标，查看路由响应和 canonical，并确认推荐列表仍按预期运行。最后，决策记录只写入实际测试的内容，不声称搜索引擎已经重新处理所有商品 URL。

常见问题

Claude Code可以同时检查线上网站和存储库吗？

只有在所需工具与访问权限可用并获得授权时才可以。请分别标记线上页面证据、存储库证据和搜索平台证据。

CLAUDE.md文件能阻止Claude Code编辑吗？

它提供持续的项目指引，但本身不是强制机制。请使用环境的实际权限和审查控制。

每个JavaScript SEO问题都需要服务端渲染吗？

不需要。稳定链接、正确状态、一致的元数据、可用的数据路径或小型组件变更，都可能是合适的解决方案。请先诊断。

应该让Claude Code部署批准的补丁吗？

除非部署是另一项已经授权的操作，并具有负责人、测试和回滚计划，否则不应该部署。本地实施批准不等于线上发布批准。

新手应该先调查什么？

选择一个高价值页面和一个可见症状，例如缺少标准链接或响应状态错误。要求修改代码之前，先建立证据文件夹。

作者：Julian Mercer，Auspia 拥有 14 年经验的技术 SEO 从业者，专注于可抓取性、渲染、网站架构，以及让 AI 易于读取内容的技术基础。