常见报错排查
遇到错误时先不要连续修改很多文件。记录三个信息:执行了什么命令、完整报错第一段、浏览器 Network 中失败请求的状态码。一次只修一个原因。
一、命令或安装失败
| 症状 |
检查 |
处理 |
node 或 npm 不是命令 |
node -v |
安装 Node.js 20 LTS,重开 PowerShell |
npm install 长时间无响应 |
网络是否正常 |
终止后切换网络重试 |
Cannot find package ... |
package.json 是否已有依赖 |
在项目根目录运行 npm install |
| Workspace 未找到 |
当前是否在根目录 |
执行 pwd,进入 servicedesk-practice |
二、启动和端口问题
| 症状 |
原因 |
处理 |
EADDRINUSE: 3001 |
后端端口已被其他进程使用 |
找到旧的开发终端并按 Ctrl + C |
Port 5173 is already in use |
前端已有服务 |
关闭旧服务,避免打开错误页面 |
| 页面打开但接口 404 |
API 前缀或代理路径不一致 |
接口统一使用 /api/v1,检查 Vite proxy |
| 浏览器报 CORS |
后端没有启用 cors() 或未经过代理 |
检查 app.use(cors()) 与代理配置 |
三、登录与权限问题
| 症状 |
检查方法 |
修正 |
| 登录始终 401 |
用演示账号 user / 123456 请求登录接口 |
检查内存初始化与 bcrypt 比较 |
| profile 返回 401 |
Network 请求头是否有 Authorization |
检查 Axios 请求拦截器与 localStorage |
| 刷新保护页面变 404 |
profile 是否在路由进入前加载 |
在守卫中先 await auth.restore() 再注册路由 |
| 菜单隐藏但接口可访问 |
直接用 PowerShell 请求接口验证 |
后端补 requirePermission 和数据范围判断 |
| 用户能看他人工单 |
详情读取未校验归属 |
校验 view_all/view_assigned/view_own |
四、工单流程问题
| 症状 |
原因 |
修正 |
| 状态可任意跳转 |
接口直接接受目标状态 |
改为接受动作并由 Service 判断 |
| 处理人无法提交结果 |
工单没有正确分配给该账号 |
确认 assigneeId 和处理权限 |
| 待受理编辑后 SLA 不更新 |
只更新了优先级文本 |
按原 createdAt 重算 dueAt |
| 预置关闭工单无时间线 |
种子数据未写日志 |
按每个经过的状态插入日志 |
| 筛选后返回丢条件 |
查询只存在组件变量中 |
将筛选和分页写入路由 query |
五、看板和 MySQL 问题
| 症状 |
原因 |
修正 |
| 图表空白且没有提示 |
渲染了全零配置 |
计算有无数据,无数据使用 el-empty |
| 图表缩放错位 |
未调用 resize() |
用 ResizeObserver 监听容器 |
| MySQL 无法连接 |
容器未启动或 .env 错误 |
docker compose ps 并核对账户端口 |
| MySQL 登录成功但数据空 |
未初始化演示数据 |
执行 npm run db:init -w server |
六、验收命令失败时的顺序
请按以下顺序修复,前一步未通过不要跳到下一步:
npm run typecheck
npm run lint
npm run format:check
npm test
npm run build
- 类型错误通常会导致测试和构建同时失败,先处理。
- Lint 和格式错误通常不改变业务,按提示逐文件修正。
- 测试失败需要观察预期值与实际接口响应。
- 构建失败最后处理浏览器打包或环境变量问题。
求助时应提供什么
不要只说“运行不了”。提供:
操作系统与 node -v:
执行的命令:
完整报错前 20 行:
失败接口路径及状态码(如有):
最近修改的文件:
这样他人才能快速定位问题,你也会逐渐形成工程排错习惯。