从 0 到 1 搭一个「环境自检」脚本：把部署踩坑变成一次输出

从 0 到 1 搭一个「环境自检」脚本：把部署踩坑变成一次输出

做过几次项目部署之后，我总结出一个规律：真正花时间的往往不是写代码，而是搞不清「到底缺什么」。Python 版本不对、Node 没装、端口被占、环境变量没配——这些问题单独出现都简单，但混在一起就很难定位。

这篇文章记录我为自己项目写的一个环境自检脚本，思路很简单：把所有前置条件一次性检查完，输出一份清单。

## 为什么要做这个

以前我的习惯是「遇到报错再查」，结果是：

- 一个 ModuleNotFoundError 查了 10 分钟，最后发现是虚拟环境没激活
- 端口冲突折腾半天，以为是代码问题
- 环境变量忘了配，程序静默失败，没有任何提示

这三次经历之后我意识到，与其事后排查，不如事前体检。

## 检查什么

我的脚本只做六件事，都是最基础但最容易出问题的：

1. 运行时版本（Python / Node）
2. 包管理器是否可用
3. 必需的环境变量是否存在（只判断存在，不打印值）
4. 关键依赖能否 import
5. 默认端口是否被占用
6. 关键 API 端点能否连通

## 输出格式

检查结果用统一的前缀标记，一眼就能看出问题在哪：

```text
[OK] Python 3.11.4
[OK] Node v20.11.0
[WARN] 未检测到 HUAWEICLOUD_SDK_AK，部分功能不可用
[FAIL] 端口 8080 已被占用（PID 12345）
结论：2 项通过，1 项警告，1 项失败
```

用三种状态而不是简单的成功/失败，是因为「警告」和「失败」的处理方式完全不同。警告可以继续跑，失败必须修。

## 几个实现细节

**环境变量只判断存在，不打印值**

这是安全考虑。脚本可能会被贴到 issue 里求助，打印机密值会很危险。

**端口检查要有 PID**

只报「端口被占用」没有意义，用户还需要知道被谁占了，才能决定是杀掉还是换端口。

**失败不中断，全部跑完**

初版我在第一个失败就 exit 了，结果修完一个再跑，又暴露下一个，来回折腾。改成全部跑完后统一输出，一次就能看到所有问题。

## 效果

现在我的流程是：clone 下来，先跑 check，看到全绿再开始。平均能省掉 10-15 分钟的摸索时间。

更重要的是心态变化——从「又报错了」变成「先看看体检报告」，排查变得更有条理。

## 小结

环境自检脚本不是什么高技术含量的东西，但它把「隐性的前置条件」变成了「显性的检查清单」。如果你也在维护需要别人跑起来的项目，值得花半小时写一个。

（本文经 AI 辅助整理，内容来自实际项目经验。）