五层错误地图：先决定打开哪个窗口
第一层：前端页面
前端就是运行在用户浏览器里的页面代码。React 组件、按钮事件、表单、CSS 和 state 都在这一层。
常见现象
- 按钮点了完全没反应。
- 页面白屏。
- 数据已经返回，但页面没有显示。
- 布局错乱、手机端溢出。
第一证据
打开浏览器 Console。
text
TypeError: Cannot read properties of undefined
at MessageForm.tsx:24如果 Network 没出现请求，而 Console 有前端文件行号，先查前端。
第二层：Network 和权限
Network 是浏览器和服务器之间的真实通信记录。
常见现象
- 401：没登录、Token 缺失或失效。
- 403：身份可能存在，但没有做这件事的权限。
- 404：请求地址没有对应路由。
- 请求一直 Pending：服务器没返回或连接有问题。
- Payload 和你以为发送的数据不同。
第一证据
打开 Network，点开失败请求，检查：
text
Request URL
Request Method
Status Code
Payload
Response不要只把“红色的一行”截图给 AI。Response 经常已经写了具体原因。
第三层：后端服务
后端运行在服务器上，负责 API 路由、权限、业务规则、数据库连接和秘密 Key。
常见现象
- Network 返回 500。
- 第三方 AI API 调用失败。
- 本地后端终端出现 Python 或 Node.js 调用栈。
- 部署平台显示服务崩溃或无法启动。
第一证据
查看运行后端的终端，或者 Railway、Cloudflare、Vercel 等平台日志。
text
Error: DATABASE_URL is not defined
at server/db.ts:8500 只是总结果；后端日志里的第一条具体错误才是入口。
第四层：数据库和存储
数据库保存结构化记录，文件存储保存图片、视频、PDF 等对象。
常见现象
- API 说保存成功，但刷新后数据消失。
- 数据库提示表不存在、列不存在。
- 权限策略拒绝读取或写入。
- 图片记录有了，但文件地址打不开。
- 本地内存里有数据，服务重启后消失。
第一证据
确认三件事：
- 后端到底有没有执行写入。
- 写入的是哪个环境、哪张表或哪个存储桶。
- 当前用户是否有权限读写。
第五层：构建和部署
开发服务器正常，不代表生产构建一定成功。
常见现象
- localhost 正常，线上还是旧版本。
- Build failed。
- 线上缺环境变量。
- 文件名大小写在 Mac 正常，Linux 构建失败。
- Node.js 版本不同导致依赖安装失败。
第一证据
查看构建日志最早出现的具体错误：
text
src/App.tsx:58:7
Type error: Property 'name' does not exist on type 'Project'最后的 Build failed 只是总结，不是根因。
用状态码快速缩小范围
text
没有请求 先查前端事件
200 请求成功，继续看返回数据和前端更新
400 前端发送的数据不符合后端要求
401 登录身份缺失或失效
403 没有权限
404 地址或路由不匹配
429 请求过快或额度限制
500 后端处理失败，查服务器日志状态码不是绝对真理，但能帮你决定下一扇门。
一张最短判断路线
text
点击后 Network 有请求吗？
├─ 没有 → 看 Console 和按钮 onClick
└─ 有
├─ 4xx → 看地址、Payload、登录和权限
├─ 5xx → 看后端日志
└─ 2xx
├─ 数据库没有结果 → 查后端写入和数据库
└─ 数据库有结果但页面没变 → 查前端 state 和渲染Network 返回 200，数据库也有新记录，但页面列表没更新。第一优先检查哪一层？
答案：前端页面。后端和数据库已有成功证据，应该检查前端是否解析 Response、更新 state，以及列表是否读取同一份 state。