Free Preview

先试读:Claude Code 调试网页 Bug:复现、定位、验证

Claude Code 很擅长顺着线索找问题,但你要先把线索收窄。

调试网页 Bug 的第一步,不是立刻改代码,而是把问题写成可复现描述。比如模拟场景:某学习测试页在提交答案后,本应显示 16 种结果之一,但用户反馈“很多时候结果都变成同一个默认类型”。

这篇能解决什么问题

  • 把一句模糊需求改成 AI 能执行、你能验收的任务卡。
  • 知道执行前要先检查哪些文件、风险点和验证命令。
  • 避免 AI 顺手改无关内容,最后只交付可审、可回退的改动。

付费后能看到哪些内容

  • 如何把“页面有 bug”改成可执行任务卡
  • 读代码前怎样判断影响范围和高风险文件
  • 如何要求 Claude Code 做最小修改,不顺手重构
  • 脚本验证、浏览器验证和上线验收清单怎么配合

可以先照着试的一句话

这是我要改的功能:___。请先阅读项目结构,列出会动哪些文件、风险点和验证命令;等我确认范围后,再开始做最小改动。

试读到这里,你应该已经能判断这篇是否适合你的网页问题;完整内容会继续给出影响范围判断、失败案例、验证指令和可复制任务包。

01 · 复现

“页面有 bug”不是需求,“怎么复现”才是入口

Claude Code 很擅长顺着线索找问题,但你要先把线索收窄。

调试网页 Bug 的第一步,不是立刻改代码,而是把问题写成可复现描述。比如模拟场景:某学习测试页在提交答案后,本应显示 16 种结果之一,但用户反馈“很多时候结果都变成同一个默认类型”。

这句话仍然太粗。更好的描述是:在哪个页面、点了什么、输入什么、期望结果是什么、实际结果是什么、是否稳定复现。

给 Claude Code 的 Bug 描述模板
请排查一个模拟网页 Bug。
页面:/path/to/mock-quiz/index.html
复现步骤:
1. 打开页面
2. 按照答案组合 A 选择
3. 点击提交
期望:显示类型 A 的结果页
实际:回退成默认结果
限制:
- 先只读代码,不要改文件
- 找到结果计算、结果映射和兜底逻辑
- 输出影响范围和建议修复方案

这类描述能让 Claude Code 更快定位到“结果计算”和“结果数据映射”,而不是在样式、导航、动画里浪费时间。

反例:不要这样交给 AI

“这个页面提交后不对,帮我修一下。”这句话没有页面路径、操作步骤、期望结果、实际结果和限制条件。Claude Code 可能会猜问题,甚至顺手重写交互逻辑,最后你很难判断它到底修了什么。

02 · 影响范围

读代码前先问:这个 Bug 可能影响哪些用户

修网页不能只看当前报错,还要看是否会碰到会员、支付、登录、搜索和部署入口。

页面内逻辑

测试结果、交互状态、DOM 更新、路径跳转、数据映射。

全站共享逻辑

导航、登录状态、会员权限、付费墙、搜索索引、统计脚本。

资源路径

CSS、JS、图片、favicon、文章链接、目录路径。

线上环境

缓存、旧服务器、CDN、权限、文件同步、回滚路径。

一个专业的 Claude Code 调试流程,会先区分“只影响单页”还是“可能影响全站”。如果 Bug 在某个测试页的本地算法里,修复可以很集中;如果涉及 auth.jspaywall.js、登录态或支付权限,就必须格外谨慎。

不要随手改会员逻辑

如果用户只是说某个页面结果不对,不应该顺手改全站权限判断。会员、支付、登录、数据库、权限过期逻辑都属于高风险区域,必须明确原因和验证方法后再动。

影响范围提问
在动手修复前,请先回答:
1. 这个 Bug 只影响当前页面,还是会影响共享组件?
2. 可能涉及哪些文件?按风险从高到低列出。
3. 哪些文件不应该改?例如 auth、payment、paywall、数据库。
4. 如果只能做最小修改,你建议改哪 1-3 个位置?
5. 修完后应该用哪些命令或浏览器路径验证?
03 · 最小修改

修 Bug 的原则:改到刚好解决问题,不做顺手重构

Claude Code 有能力改很多,但越是能改,越要控制范围。

继续看模拟学习测试页。如果结果 key 生成逻辑和结果数据 key 不一致,正确修法通常是统一 key,而不是重写整套页面。比如把计算出的 XINTJ 修成结果表实际存在的 INTJ,或者反过来补全结果数据。哪种更合适,要看页面原始设计。

这里的关键不是“让 AI 找到一个能跑的版本”,而是让它解释为什么这个版本是最小修改。好的修复说明应该包含三句话:问题根因、实际改动、为什么没有动其他文件。

1
先定位唯一入口
找到提交、计算、映射、渲染四个位置,不要在全文件里盲改。
2
确认数据契约
看函数输出的 key、对象里的 key、兜底结果是否同一套规范。
3
只改必要行
优先修映射关系、路径或条件判断,不顺手改 UI、文案和无关结构。
4
补验证,而不是凭感觉
用脚本枚举所有结果,确认不会再落到错误兜底。
最小修改约束
请开始修复,但遵守这些限制:
- 只改和复现问题直接相关的文件
- 不做样式重构、不改文案、不整理无关代码
- 每改一个文件,说明为什么必须改
- 修完后输出:改动文件、关键 diff、验证命令、仍然存在的风险
04 · 验证

脚本验证和浏览器验证要一起做

脚本能证明逻辑对,浏览器能证明用户真的能用。

脚本验证适合检查什么

枚举所有答案组合、检查所有结果 key 是否存在、检查链接是否指向真实文件、检查搜索索引语法、检查 HTML 中的脚本是否能解析。

给 Claude Code 的验证指令
请为这个模拟测试页写一次只读验证:
1. 枚举所有可能结果 key
2. 确认每个 key 都能在 resultData 中找到
3. 检查结果页推荐链接是否存在
4. 不修改文件,只输出错误列表和对应代码位置

浏览器验证适合检查什么

移动端菜单能不能打开、按钮是否可点、结果页是否渲染、文字是否溢出、会员入口是否存在、付费墙是否没有被误挡。

如果页面有复杂交互,最好用两种视口:桌面和手机。很多 Bug 在桌面看不出来,但手机端会暴露按钮遮挡、菜单缺入口、长文字撑破卡片等问题。

脚本验收

结果 key 全覆盖、链接存在、JS 能解析、搜索索引无语法错误。

浏览器验收

桌面和手机都能完成完整路径,按钮可点,文字不溢出。

回归验收

原本正常的入口、推荐链接、会员框和导航没有被改坏。

上线验收

正式域名返回 200,新文案或交互确实出现,不只是本地可用。

05 · 部署边界

部署前检查:不要把“本地修好”当成“线上安全”

网页 Bug 修复最后一步,是确认线上用户不会因为修复受到新影响。

权限边界

确认没有改动登录、会员、支付、权限过期等共享逻辑。

链接边界

新链接、旧链接、入口页、搜索索引都要可访问。

回滚边界

知道本次改了哪些文件,出现问题能快速回退。

缓存边界

线上验证要避免只看到浏览器缓存或旧节点内容。

部署前交给 Claude Code 的检查清单
请在部署前检查本次网页 Bug 修复:
1. 列出实际改动文件
2. 确认是否触碰 auth/paywall/payment 等高风险文件
3. 运行可用的本地验证命令
4. 检查新增或修改链接是否存在
5. 给出线上验证路径和回滚提醒
06 · 任务包

可复制的 Bug 修复任务包

如果你不知道怎么把网页问题交给 Claude Code,可以直接从这个任务包开始改。

任务卡
任务:修复一个网页交互 Bug
页面路径:___
问题现象:___
复现步骤:
1. ___
2. ___
3. ___
期望结果:___
实际结果:___

执行要求:
1. 先只读代码,找到入口函数、状态变量、数据映射和渲染逻辑。
2. 输出影响范围,标出高风险文件和禁止修改文件。
3. 等我确认后,只做最小修改。
4. 修复后运行可用验证,并给出浏览器验收路径。
5. 最后输出:根因、改动文件、验证结果、剩余风险。

验收标准 1:能复现

AI 必须能说清问题怎么触发,而不是只说“我看了一下代码”。

验收标准 2:改动小

改动文件数量和修改位置要能解释,不允许顺手重构一大片。

验收标准 3:验证真

要有脚本验证或浏览器验证结果,不能只说“应该可以了”。

验收标准 4:能回退

必须知道本次改了哪些文件,线上出问题时可以快速回滚。

调试步骤
  • 先把 Bug 写成可复现步骤,再让 Claude Code 读代码。
  • 先判断影响范围,避免误改全站共享逻辑。
  • 修复坚持最小修改,不做无关重构。
  • 脚本验证逻辑,浏览器验证体验。
  • 部署前确认权限、链接、搜索索引、回滚和线上节点。
资料 · 时效核验

产品能力会变,使用前回到官方资料

官方资料与核验日期

本文于 2026-07-15 重新核验入口、流程与风险边界。功能名称、套餐和地区可用性仍可能变化。

Next Step

学完这篇,下一步这样走

先把刚学的内容用起来,再继续读两篇相关内容;如果想换主题,可以回到本系列目录重新选择。

现在就练一下

找一个真实网页问题,先别让 AI 改代码,只让它按“复现步骤、影响范围、禁止修改文件、验证命令”输出任务卡。