本地环境排障

何时使用

• 服务起不来、启动报错;
• 页面打不开、接口连不上、数据库连接失败;
• 依赖安装失败、版本对不上;
• "在我机器上好好的,你这边就不行"类问题。

使用步骤

第 1 步:复述现象

先让用户说清三件事:

1. 在做什么操作时出的问题;
2. 完整报错信息(不是"报错了"三个字);
3. 最近改了什么(代码、配置、依赖、系统)。

第 2 步:按验证阶梯逐层排查

从最外层开始,一次只查一层,查完再往下:

第 3 步:定位根因

端口、依赖、数据库、网络等常见报错速查见 references/COMMON_ERRORS.md。

• 每层验证都有明确结论(通/不通),不通的那层就是怀疑重点;
• 用二分法:改一行配置就测一次,确认因果;
• 找到根因后给修复方案,并解释为什么这样改。

第 4 步:输出排障记录

# 环境排障记录

## 现象
## 排查过程(每层结果)
## 根因
## 修复
## 预防(以后怎么避免)

输入与输出

• 输入:报错信息或现象描述;
• 输出:根因 + 修复方案 + 排障记录。

示例

现象: 前端 npm run dev 报 EADDRINUSE: address already in use :::5173。

排查:

netstat -ano | findstr :5173
# 发现 PID 1234 占着端口,是上次没关掉的 dev server

修复: 结束旧进程,或换端口 npm run dev -- --port 5174。

预防: 关 IDE 前先停 dev server;启动脚本里加端口检测提示。

辅助脚本

scripts/port_check.py 检查端口占用情况和占用进程:

python scripts/port_check.py 8080

脚本只做检查,是否结束进程需要用户确认。

注意事项

• 先环境后代码,不要一上来就改业务代码;
• 一条命令一条命令来,别一口气跑一串看不到中间结果;
• 报错信息必须拿全,只拿最后一行往往会误判;
• 网络问题先排除代理再找别的原因;
• 修复后让用户复现一遍原操作,确认问题真的没了。

不适用场景

• 问题在生产环境(那是运维排障,流程不同);
• 用户连报错信息都拿不到且拒绝提供;
• 明确的业务逻辑 Bug(走 bug-diagnoser)。

验证方式

1. 触发:"本地起不来""端口被占""连不上数据库";
2. 检查:排障记录按阶梯分层,每层有结论;
3. 复核:按修复方案操作后,原操作能跑通。