调试与排错手册

新手 80% 的时间不是花在写代码，而是花在看不懂报错。 这一章给你一套固定流程：把“猜修复”变成“按证据定位”。

你将学会

• 读懂一条报错里的关键信息；
• 把问题缩到“最小可复现”；
• 用二分法快速定位是哪一步坏了；
• 收集证据，向 AI 提一个高质量的问题；
• 常见错误自己先能判断个大概。

前置知识

编程心智模型速成（尤其“终端与命令”“接口与 API”两节）。

一、报错怎么读

一条报错，重点看三样：

TypeError: Cannot read properties of undefined (reading 'map')
    at renderList (app.js:42:18)

看什么	在这条里	含义
错误类型	TypeError	哪一类问题（类型错）
消息	Cannot read properties of undefined (reading 'map')	具体现象：对“空”调用了 .map
位置	app.js:42:18	文件第 42 行、第 18 列

第一个动作：打开那个文件的那一行看一眼。 多数问题看一眼就明白了。

报错很长时，只看第一条（通常是根源）和最后一条（崩的地方），中间那一大串多半是调用过程。

二、最小复现

目标：找到一个尽量短、每次都能重现的步骤。

• 删掉无关代码 / 无关操作，只留下触发问题的最小集合；
• 把输入固定下来（就用那一条数据、那一次点击）；
• 记下是“必现”还是“偶发”——偶发问题要先找触发条件。

能最小复现，问题就解决了一半。

三、二分定位

不知道是哪一步坏的？砍一半试试：

• 代码：注释掉后半段，看还崩不崩——崩，问题在前半；不崩，在后半。
• 改动：一次改了很多时，用 git diff 逐个还原，看还原哪个就好了。
• 数据：把输入数据减半，看是否仍复现。

四、证据收集清单

问 AI 之前，先把这几样凑齐（缺一个都会被反问）：

• 完整报错文本（不要只截最后一行）；
• 复现步骤（从打开页面开始）；
• 期望结果 vs 实际结果；
• 最近一次正常是什么时候（git log 里的 commit）；
• 相关文件的当前内容或 git diff。

五、向 AI 求助的正确姿势

用这个模板（与入门教程的调试模板一致）：

# 现象
点击“导入”后页面没有变化。

# 预期
合法 JSON 导入后显示任务列表；非法 JSON 显示错误且保留旧数据。

# 复现步骤
1. 打开首页。
2. 新增一个任务。
3. 选择 sample.json。
4. 点击导入。

# 证据
- 控制台错误：（粘贴完整文本）
- 相关代码：app.js 的 handleImport
- 最近一次正常提交：ab12cd3

# 要求
先定位根因并给出证据，不要修改文件；确认原因后再提出最小修复。

关键在最后一句：先定位，别急着改。否则 AI 会东补一下西补一下，越修越乱。

六、常见错误速查表

现象	常见原因	先做什么
command not found / 不是内部或外部命令	工具没装，或不在正确的目录	确认装了、确认当前目录
端口被占用 EADDRINUSE	上次的服务没关	关掉旧进程，或换端口
页面空白、控制台一片红	JS 报错	F12 看 Console 第一条错误
请求 404	路径写错 / 后端没这个接口	看 Network 里的 URL
请求 500	后端出错了	看后端日志
改了代码没生效	缓存 / 没保存 / 没重启	硬刷新、确认保存、重启服务
Cannot find module	依赖没装	跑一次 npm install
中文乱码	文件编码不是 UTF-8	另存为 UTF-8

动手练习

1. 在浏览器控制台手动输入 undefined.map()，读一遍报错，指出类型、消息、位置。
2. 拿一段会报错的代码，用注释法二分定位到具体行。
3. 用上面的模板，把一次真实报错写成一份“求助包”。

检查点

• 拿到一条报错，能说出“哪一类、在哪一行、大概什么问题”；
• 能把一个问题缩到最小可复现；
• 能给 AI 一份含现象 / 预期 / 复现 / 证据的完整描述。

常见问题

Q：报错太长看不懂怎么办？ 只看第一条和最后一条。第一条通常是根源，最后一条是崩的地方。

Q：AI 改了几次还没好怎么办？ 停下来。用 git diff 看它一共改了什么，必要时 git restore 全部还原，重新按“先定位、再修”的流程来（见Git 与版本控制）。

小结与下一步

排错是练出来的，但流程是固定的：读报错 → 最小复现 → 二分定位 → 收集证据 → 让 AI 定位后再修。 下一步在从 0 到 1 用 Vibe Coding 写自己的项目 的验证环节里反复练。