Back to Details

debug

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Debug

调试

Debugging Workflow

调试工作流

Debug Process:
- [ ] Reproduce bug consistently
- [ ] Capture what's happening (screenshots, errors)
- [ ] Check what changed recently
- [ ] Gather diagnostic info
- [ ] Give info to AI to diagnose
- [ ] AI proposes fix
- [ ] Test fix works
- [ ] Verify didn't break anything else
See DEBUG-CHECKLIST.md for detailed steps.
Debug Process:
- [ ] Reproduce bug consistently
- [ ] Capture what's happening (screenshots, errors)
- [ ] Check what changed recently
- [ ] Gather diagnostic info
- [ ] Give info to AI to diagnose
- [ ] AI proposes fix
- [ ] Test fix works
- [ ] Verify didn't break anything else
查看DEBUG-CHECKLIST.md获取详细步骤。

The Golden Rule

黄金准则

NO GUESSING. GATHER INFO FIRST.
Bad approach:
  1. Something broke
  2. Try random fix
  3. Doesn't work
  4. Try another fix
  5. Still broken after 5 attempts
Good approach:
  1. Something broke
  2. Reproduce it consistently
  3. Gather diagnostic info
  4. Give to AI to diagnose
  5. AI fixes it (usually first try)
Diagnosis before fixes.
禁止盲目猜测，先收集信息。
错误做法：
  1. 功能出现故障
  2. 尝试随机修复方案
  3. 无效
  4. 尝试另一个方案
  5. 尝试5次后仍未解决
正确做法：
  1. 功能出现故障
  2. 稳定复现问题
  3. 收集诊断信息
  4. 将信息提供给AI进行诊断
  5. AI给出修复方案（通常一次即可解决）
先诊断，再修复。

Reproducing Bugs

复现Bug

Before asking AI to fix, reproduce it:
Can you reproduce it?
- [ ] Exact steps to trigger bug
- [ ] Happens every time
- [ ] Happens on specific browser/device
- [ ] Happens with specific data

If can't reproduce:
- Ask user for exact steps
- Try different browser/device
- Try with different data
- Check if intermittent (timing issue)
Tell AI:
Bug: [description]

Steps to reproduce:
1. [Step]
2. [Step]
3. [Bug happens]

Happens: [Always / Sometimes / Once]
Browser: [Chrome 120 on Mac]
Screenshot: [attach]
在请求AI修复前，先复现问题：
能否复现问题？
- [ ] 触发Bug的精确步骤
- [ ] 每次操作都会出现
- [ ] 仅在特定浏览器/设备上出现
- [ ] 仅在特定数据下出现

若无法复现：
- 向用户询问精确步骤
- 尝试不同浏览器/设备
- 尝试不同数据
- 检查是否为间歇性问题（时序问题）
告知AI的内容：
Bug: [描述]

复现步骤：
1. [步骤]
2. [步骤]
3. [出现Bug]

出现频率：[每次/有时/仅一次]
浏览器：[Mac系统上的Chrome 120]
截图：[附件]

Capturing Error Info

捕获错误信息

Browser Console Errors

浏览器控制台错误

Open console:
  1. Right-click page → Inspect
  2. Click "Console" tab
  3. Look for red errors
Screenshot errors and give to AI:
I see this error in console:
[paste error message]

When it happens:
[what you were doing]

Please:
1. Explain what this means
2. Identify the cause
3. Fix the issue
打开控制台：
  1. 右键页面 → 检查
  2. 点击「控制台」标签
  3. 查找红色错误信息
截图错误信息并提供给AI：
我在控制台看到以下错误：
[粘贴错误信息]

出现场景：
[当时正在执行的操作]

请：
1. 解释该错误的含义
2. 确定问题原因
3. 修复该问题

Network Errors

网络错误

Check network tab:
  1. Open DevTools → Network
  2. Reproduce bug
  3. Look for failed requests (red)
  4. Click failed request
  5. Check response
Tell AI:
API call failing:
URL: /api/endpoint
Status: 500 Internal Server Error
Response: [paste error response]

This happens when: [action]
检查网络标签：
  1. 打开开发者工具 → 网络
  2. 复现Bug
  3. 查找失败的请求（红色标识）
  4. 点击失败的请求
  5. 查看响应内容
告知AI的内容：
API调用失败：
URL: /api/endpoint
状态码：500 Internal Server Error
响应内容：[粘贴错误响应]

出现场景：[执行某操作时]

Visual Bugs

视觉Bug

Screenshot everything:
  • What you expected to see
  • What actually shows
  • Full page context
  • Error messages
Tell AI:
Visual bug: [description]
Expected: [screenshot or description]
Actual: [screenshot]
Device: [iPhone 14, Chrome on Mac, etc]
截图所有相关内容：
  • 预期显示效果
  • 实际显示效果
  • 完整页面上下文
  • 错误提示信息
告知AI的内容：
视觉Bug：[描述]
预期：[截图或描述]
实际：[截图]
设备：[iPhone 14、Mac系统上的Chrome等]

What Changed?

近期变更

Ask yourself:
  • Did this work yesterday?
  • What did AI change today?
  • Did you deploy recently?
  • Did you change any settings?
Tell AI:
This worked yesterday, broke today.
Changes made today:
- [Change 1]
- [Change 2]

Which could cause: [the bug]?
自问：
  • 昨天还能正常工作吗？
  • AI今天做了哪些修改？
  • 近期是否有部署操作？
  • 是否修改过任何设置？
告知AI的内容：
昨天还能正常工作，今天出现故障。
今日变更：
- [变更1]
- [变更2]

哪项变更可能导致：[该Bug]？

Common Bug Types

常见Bug类型

"Nothing happens when I click"

「点击后无反应」

Check:
  • Console errors?
  • Network request failing?
  • Button actually clickable?
Tell AI:
Button does nothing when clicked.
Button: [which button]
Expected: [what should happen]
Console errors: [paste any errors]
检查项：
  • 控制台是否有错误？
  • 网络请求是否失败？
  • 按钮是否真的可点击？
告知AI的内容：
按钮点击后无反应。
按钮：[具体哪个按钮]
预期：[应实现的功能]
控制台错误：[粘贴相关错误]

"Page won't load"

「页面无法加载」

Check:
  • Network errors?
  • JavaScript errors?
  • Infinite redirect?
Tell AI:
Page won't load: /page/url
Browser shows: [blank / error / loading forever]
Console errors: [paste]
Network errors: [paste]
检查项：
  • 是否存在网络错误？
  • 是否存在JavaScript错误？
  • 是否存在无限重定向？
告知AI的内容：
页面无法加载：/page/url
浏览器显示：[空白页/错误页/持续加载]
控制台错误：[粘贴]
网络错误：[粘贴]

"Wrong data showing"

「显示错误数据」

Check:
  • API returning wrong data?
  • Caching issue?
  • State management bug?
Tell AI:
Showing wrong data.
Expected: [User A's profile]
Showing: [User B's profile]
API response: [paste from Network tab]
检查项：
  • API是否返回错误数据？
  • 是否存在缓存问题？
  • 是否存在状态管理Bug？
告知AI的内容：
显示错误数据。
预期：[用户A的个人资料]
实际：[用户B的个人资料]
API响应：[从网络标签粘贴]

"Form doesn't submit"

「表单无法提交」

Check:
  • Validation errors?
  • Console errors?
  • Network request happening?
Tell AI:
Form won't submit.
Form: [which form]
Filled: [what data entered]
Validation errors: [any visible]
Console errors: [paste]
检查项：
  • 是否存在验证错误？
  • 控制台是否有错误？
  • 是否发起了网络请求？
告知AI的内容：
表单无法提交。
表单：[具体哪个表单]
已填写内容：[输入的数据]
验证错误：[可见的错误信息]
控制台错误：[粘贴]

Working with AI to Debug

借助AI进行调试

Step 1: Gather Info

步骤1：收集信息

Before asking AI to fix, provide:
- Exact steps to reproduce
- Expected vs actual behavior
- Screenshots/error messages
- Browser and device
- What changed recently (if known)
在请求AI修复前，请提供：
- 精确的复现步骤
- 预期与实际行为对比
- 截图/错误信息
- 浏览器与设备信息
- 近期变更（若已知）

Step 2: AI Diagnoses

步骤2：AI诊断

[Paste all info above]

Before proposing fixes:
1. What do you think is wrong?
2. Why is it happening?
3. What needs to change?

Explain in plain English first.
[粘贴以上所有信息]

在提出修复方案前：
1. 你认为问题出在哪里？
2. 问题产生的原因是什么？
3. 需要修改哪些内容？

请先用通俗易懂的语言解释。

Step 3: AI Fixes

步骤3：AI修复

Okay, now please fix it.

After fixing:
- Explain what you changed
- How to test the fix
- What to watch out for
好的，现在请修复该问题。

修复后请说明：
- 修改了哪些内容
- 如何测试修复效果
- 需要注意的事项

Step 4: Verify Fix

步骤4：验证修复

Test the fix:
- [ ] Original bug is gone
- [ ] Tested same steps, works now
- [ ] Related features still work
- [ ] No new console errors
See DEBUG-PROMPTS.md for more patterns.
测试修复效果：
- [ ] 原Bug已消失
- [ ] 执行相同步骤，功能正常
- [ ] 相关功能仍可正常使用
- [ ] 无新的控制台错误
查看DEBUG-PROMPTS.md获取更多提示模板。

When You're Stuck

陷入困境时的处理

After 2 failed fix attempts:
Stop. Don't try a 3rd fix.
Ask AI:
Tried 2 fixes, both didn't work.

Original bug: [description]
Fix 1: [what we tried] - didn't work
Fix 2: [what we tried] - still broken

Questions:
- Are we fixing the wrong thing?
- Is there a better approach?
- Should we start over?
If 3+ fixes failed: Probably need to rethink approach, not try more fixes.
两次修复尝试失败后：
停止操作，不要进行第三次尝试。
询问AI：
已尝试2种修复方案，均无效。

原Bug：[描述]
方案1：[尝试的内容] - 无效
方案2：[尝试的内容] - 仍未解决

问题：
- 我们是否在修复错误的问题？
- 是否有更好的解决思路？
- 我们是否应该重新开始？
若3次及以上修复失败： 可能需要重新思考解决思路，而非继续尝试更多方案。

Intermittent Bugs

间歇性Bug

"It works sometimes, breaks sometimes"
Likely causes:
  • Race condition (timing)
  • Caching issue
  • Network timing
  • External API flakiness
Tell AI:
Bug is intermittent.
Works: [X] out of 10 times
Fails: [Y] out of 10 times

Pattern noticed:
- Fails more often when [condition]
- Never fails when [condition]

Please add logging to capture when it fails.
「有时正常，有时故障」
可能原因：
  • 竞态条件（时序问题）
  • 缓存问题
  • 网络时序问题
  • 外部API不稳定
告知AI的内容：
Bug为间歇性问题。
正常次数：10次中有[X]次
故障次数：10次中有[Y]次

已发现的规律：
- 在[条件]下更容易故障
- 在[条件]下从未故障

请添加日志以捕获故障时的信息。

Bugs in Production

生产环境Bug

Users reporting bugs in live app:
Priority 1: Can users work around it?
  • Yes → Fix in next deployment
  • No → Emergency fix needed
For emergency fixes:
Production bug blocking users.
Bug: [description]
Impact: [how many users affected]

Need quick fix:
- Simplest solution that works
- Don't optimize, just unblock users
- Can improve later
For non-urgent:
Production bug reported by user.
Bug: [description]
Impact: [minor / major]
Can work around: [yes / no]

Reproduce in development:
[steps]

Then fix and test before deploying.
用户反馈线上应用出现Bug：
优先级1：用户是否有替代方案？
  • 是 → 在下一次部署时修复
  • 否 → 需要紧急修复
紧急修复模板：
生产环境Bug阻碍用户使用。
Bug：[描述]
影响范围：[受影响用户数量]

需要快速修复：
- 采用最简单的可行方案
- 无需优化，只需解除用户阻碍
- 后续可再完善
非紧急情况模板：
用户反馈生产环境Bug。
Bug：[描述]
影响程度：[轻微/严重]
是否有替代方案：[是/否]

在开发环境复现：
[步骤]

修复并测试后再部署。

Reading Error Messages

错误信息解读

Common error patterns:
"Cannot read property of undefined"
  • Trying to access something that doesn't exist
  • Check: Is data loaded before accessing it?
"Maximum call stack exceeded"
  • Infinite loop or recursion
  • Check: Function calling itself forever?
"Network request failed"
  • API call not working
  • Check: Network tab for status code
"Unauthorized" or "401"
  • Authentication issue
  • Check: Are you logged in? Token valid?
"Internal Server Error" or "500"
  • Backend problem
  • Check: Server logs for details
See ERROR-MESSAGES.md for more.
常见错误模式：
"Cannot read property of undefined"
  • 尝试访问不存在的对象属性
  • 检查：是否在数据加载完成前就访问了它？
"Maximum call stack exceeded"
  • 无限循环或递归
  • 检查：函数是否在无限调用自身？
"Network request failed"
  • API调用失败
  • 检查：查看网络标签的状态码
"Unauthorized" 或 "401"
  • 认证问题
  • 检查：是否已登录？Token是否有效？
"Internal Server Error" 或 "500"
  • 后端问题
  • 检查：查看服务器日志获取详情
查看ERROR-MESSAGES.md获取更多内容。

Debugging Tools

调试工具

Built into browser:
  • Console: See errors and logs
  • Network: See API calls and responses
  • Elements: Inspect HTML/CSS
  • Sources: Set breakpoints (advanced)
How to use:
  1. Open DevTools (F12 or right-click → Inspect)
  2. Click relevant tab
  3. Reproduce bug
  4. Look for errors/failed requests
Screenshot and give to AI - AI can interpret errors.
浏览器内置工具：
  • 控制台：查看错误与日志
  • 网络：查看API调用与响应
  • 元素：检查HTML/CSS
  • 源代码：设置断点（高级功能）
使用方法：
  1. 打开开发者工具（F12或右键→检查）
  2. 点击对应标签
  3. 复现Bug
  4. 查找错误/失败请求
截图并提供给AI - AI可以解读错误信息。

Common Mistakes

常见误区

MistakeFix
Trying fixes without infoGather diagnostic info first
"It doesn't work"Be specific: what doesn't work?
Not reproducing firstFind consistent steps to trigger bug
Random fixesDiagnose root cause first
Ignoring console errorsAlways check console
Not testing after fixVerify fix works, didn't break other things
误区解决方法
未收集信息就尝试修复先收集诊断信息
只说「功能无法使用」具体化：哪部分功能无法使用？
未先复现问题找到稳定触发Bug的步骤
随机尝试修复方案先诊断根本原因
忽略控制台错误务必检查控制台
修复后未测试验证修复有效且未影响其他功能

When to Get Help

何时寻求帮助

Consider hiring developer when:
  • Stuck after following this process
  • Critical bug can't figure out
  • Same bug keeps coming back
  • Bug in complex integration
  • Need production fixed urgently
For most bugs: Following this process with AI is sufficient.
考虑聘请开发者的场景：
  • 遵循本流程后仍陷入困境
  • 严重Bug无法解决
  • 同一Bug反复出现
  • 复杂集成中的Bug
  • 需要紧急修复生产环境问题
大多数Bug： 遵循本流程并借助AI即可解决。

Prevention

预防措施

After fixing, ask AI:
Bug is fixed. 

How could we have prevented this?
- Better validation?
- Better error handling?
- Testing we should add?
Build prevention into next features.
修复后，询问AI：
Bug已修复。

我们本可以如何预防该问题？
- 更完善的验证？
- 更优的错误处理？
- 应添加哪些测试？
将预防措施融入后续功能开发中。

Quick Debug Checklist

快速调试检查清单

When something breaks:
Quick Debug:
- [ ] Can I reproduce it?
- [ ] Any console errors?
- [ ] Any network errors?
- [ ] What changed recently?
- [ ] Screenshot the issue
- [ ] Gather all info
- [ ] Give to AI with context
- [ ] Test AI's fix
5 minutes of diagnosis > 2 hours of guessing
功能出现故障时：
快速调试：
- [ ] 能否复现问题？
- [ ] 是否存在控制台错误？
- [ ] 是否存在网络错误？
- [ ] 近期有哪些变更？
- [ ] 截图问题场景
- [ ] 收集所有信息
- [ ] 向AI提供完整上下文
- [ ] 测试AI的修复方案
5分钟的诊断 > 2小时的盲目猜测

Success Looks Like

成功的标准

✅ Bugs fixed on first or second try
✅ Can explain what was wrong
✅ Know how to reproduce bugs
✅ Gather complete info before asking for fixes
✅ Verify fixes work and don't break other things
✅ Bugs getting rarer over time (learning patterns)
✅ 首次或第二次尝试即可修复Bug
✅ 能够解释问题根源
✅ 掌握Bug复现方法
✅ 请求修复前收集完整信息
✅ 验证修复有效且未影响其他功能
✅ Bug出现频率逐渐降低（掌握规律）