调试与排查

遇到问题时，按照 浏览器 -> 网络 -> 后端 -> 数据库 的顺序逐层排查，大部分情况在前两层就能定位原因。

快速定位你的问题类型：

症状	排查方向
按钮没反应、白屏、红色报错弹窗	浏览器调试
数据加载不出来、保存失败、Network Error	接口与网络调试
AI 任务卡住、容器启动失败、接口 500	后端与服务调试

浏览器调试

页面交互异常或显示错误时，首先打开浏览器开发者工具。

打开方式：F12 / Ctrl+Shift+I（macOS: Cmd+Option+I），或右键选择"检查"。

Console 面板 -- 查看报错

Console 面板显示前端运行日志，红色 Error 是排查重点。

常见错误：

• ReferenceError: xxx is not defined -- 使用了不存在的变量，检查拼写。
• TypeError: Cannot read properties of undefined -- 空指针异常，通常是数据还没加载完成就访问了字段。
• Vue warn -- Vue 框架警告，通常会指向具体组件。

Elements 面板 -- 样式与结构

元素不显示或样式异常时使用。点击左上角箭头图标选中页面元素，右侧查看样式。

• 样式被划掉：被更高优先级样式覆盖。
• 找不到元素：检查是否有 display: none 或 visibility: hidden。

Application 面板 -- 缓存与存储

登录状态异常（Token 丢失）或缓存数据未更新时，在 Application 面板查看 Local Storage 和 Cookies。右键域名可清除存储。

接口与网络调试

页面无报错但数据异常时，使用 Network 面板排查前后端通信。

打开 Network 面板后，刷新页面或重新操作以捕获请求记录。

状态码速查

状态码	含义	排查方向
200	成功	数据不对则查看 Response 内容
304	缓存命中	正常
400	请求参数错误	检查 Payload 中字段名和格式
401	未认证	重新登录
403	无权限	确认账号权限
404	地址不存在	检查 API 路径和资源 ID
500	服务端异常	查看后端日志
(failed)	网络不通	检查后端服务是否启动

请求详情

点击具体请求查看详情面板：

• Headers：确认请求 URL、Method、Authorization Token。
• Payload：前端发送的数据，检查字段名和格式。
• Response：后端返回的数据，确认结构与前端解析匹配。

WebSocket 调试

系统通过 WebSocket 实时推送任务日志。在 Network 面板 Filter 中选择 WS，找到 socket.io 请求，查看 Messages 标签中绿色（发送）和白色（接收）的消息。如无消息或连接断开，检查后端日志。

后端与服务调试

500 错误或 AI 任务异常时，需要深入后端排查。问题分为两类：

• 服务问题：NestJS 主服务报错、数据库连接失败，导致接口 500。
• 任务问题：服务正常，但 AI 生成任务失败（容器异常、脚本错误）。

AI 任务排查

进入任务详情页：

1. 检查状态栏：WebSocket 必须为绿色连接；容器状态如果显示 dead 或 exited，说明容器崩溃。
2. 切换到"日志"视图查看容器运行日志，下载完整日志进行深度分析。

容器无日志时，使用终端检查：

# 查看所有容器（包括已停止的）
docker ps -a

# 查看容器日志
docker logs <container_id>

后端服务排查

本地开发：查看运行 pnpm dev 的终端窗口输出，关注 Error Stack Trace 中的 File 行定位错误位置。

Docker 部署：

# 查看后端服务日志
docker compose logs --tail=100 -f server

数据库问题：日志中出现 PrismaClientInitializationError 或 Connection refused 时，确认 Postgres 是否运行：

docker ps | grep postgres

重启大法

实在找不到原因时，可以尝试 docker compose restart 或 docker compose down && docker compose up -d。注意 down 会清除未挂载卷的数据。