常见报错排查

遇到错误时先不要连续修改很多文件。记录三个信息：执行了什么命令、完整报错第一段、浏览器 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

1. 类型错误通常会导致测试和构建同时失败，先处理。
2. Lint 和格式错误通常不改变业务，按提示逐文件修正。
3. 测试失败需要观察预期值与实际接口响应。
4. 构建失败最后处理浏览器打包或环境变量问题。

求助时应提供什么

不要只说“运行不了”。提供：

操作系统与 node -v：
执行的命令：
完整报错前 20 行：
失败接口路径及状态码（如有）：
最近修改的文件：

这样他人才能快速定位问题，你也会逐渐形成工程排错习惯。