环境检查别把“没执行”当“成功”：一次 Python 依赖误报的复现与改进

环境检查脚本经常位于项目启动的第一步。它的价值不是输出一排绿色，而是把“现在能运行什么、还缺什么、哪些内容没有检查”说清楚。2026 年 10 月 22 日的 一次实际排查中，同一份报告出现了“未找到可用的 Python 解释器”和“核心依赖可用”两条结论。脚本整体仍以失败退出，所以不能把问题描述成整个检查误判通过；真正的问题是一个未执行的子检查被报告成了成功。

本文以当时保存的 EduSwarm 环境检测结果为背景，解释这类状态错误怎样发生，再给出一个独立的 Python 示例。示例和文章由 AI 辅助编写，代码已在 Windows 上执行验证。示例不属于上游仓库补丁，也不代表上游当前版本仍有该问题。

1. 先固定复现范围，避免扩大结论

当时检查的是仓库提交 a1f62f17be387280993b44cd963351a6debd7de6 中的 scripts/env-check.ps1。复现时仅在子进程中收窄 PATH，让 python、python3 和 py 都不可发现；没有卸载 Python，也没有修改系统环境变量。数据目录指向单独的临时测试目录，未运行 EduSwarm 业务应用。

报告中与问题相关的三行如下，整体进程退出码为 1：

FAIL | 未找到可用的 Python 解释器（需要 3.11+）
ok   | 核心依赖可用（ruamel.yaml / fastapi / uvicorn / jiuwenswarm / openjiuwen）
warn | 跳过数据库检查（无可用 Python 解释器）

第一行和第三行符合前置条件，第二行却给出了没有证据支持的成功结论。对应的问题记录是 https://gitcode.com/agent-best-practices/eduSwarm/issues/551 。这份记录只说明当时版本的复现情况，不能替代对最新代码的检查。

2. 默认空字符串为什么容易带来误报

问题可以缩小成下面的控制流：

$missing = ""
if ($py) {
    $missing = & $py -c $probe
}
if ([string]::IsNullOrWhiteSpace("$missing")) {
    Write-Output "核心依赖可用"
}

这个变量同时承担了两个含义：没有缺失依赖，以及没有执行检查。前置解释器不存在时，探测分支根本没有进入，但默认值仍然满足成功条件。单纯把默认值改成另一个字符串，也容易在新增分支时再次出错。更清楚的处理方式，是先表示检查状态，再保存检查结果。

可以把依赖子检查划分为四种结果：skipped 表示前置条件不满足，error 表示探测过程失败或输出无效，missing 表示探测成功但找不到模块，ok 才表示探测成功且没有发现缺失模块。这四种状态分别对应“没有测”“没测成”“测到了问题”“在本次检查范围内通过”。

3. 一个可独立运行的探测示例

以下示例保存为 dependency_probe.py，使用已经选定的 Python 解释器启动独立子进程。它只检查模块能否被 importlib 定位，不安装依赖，也不承诺模块能成功导入、版本满足要求或应用能够启动。

"""Small, standalone example: distinguish skipped, error, missing and ok."""
import json
import subprocess

PROBE = r'''
import importlib.util
import json
import sys

missing = []
for name in json.loads(sys.argv[1]):
    try:
        found = importlib.util.find_spec(name) is not None
    except (ModuleNotFoundError, ValueError):
        found = False
    if not found:
        missing.append(name)
print(json.dumps({"checked": True, "missing": missing}))
'''


def check_modules(executable, modules, timeout=5):
    """Check discoverability of modules using an explicitly supplied interpreter."""
    if not executable:
        return {"status": "skipped", "reason": "no interpreter selected"}
    if not isinstance(modules, list) or not all(
        isinstance(name, str) and name and all(p.isidentifier() for p in name.split('.'))
        for name in modules
    ):
        raise ValueError("modules must be a list of valid dotted module names")
    try:
        result = subprocess.run(
            [executable, "-I", "-c", PROBE, json.dumps(modules)],
            capture_output=True, text=True, encoding="utf-8",
            errors="replace", timeout=timeout, check=False,
        )
    except (OSError, subprocess.TimeoutExpired) as exc:
        return {"status": "error", "reason": type(exc).__name__}
    if result.returncode != 0:
        return {"status": "error", "reason": "probe exited nonzero"}
    try:
        data = json.loads(result.stdout)
    except (ValueError, TypeError):
        return {"status": "error", "reason": "invalid probe output"}
    if (
        not isinstance(data, dict)
        or data.get("checked") is not True
        or not isinstance(data.get("missing"), list)
        or not all(isinstance(name, str) and name in modules for name in data["missing"])
    ):
        return {"status": "error", "reason": "invalid probe schema"}
    return {"status": "missing" if data["missing"] else "ok", "missing": data["missing"]}


if __name__ == "__main__":
    import sys
    for executable, modules in [
        (None, ["json"]),
        (sys.executable, ["json", "pathlib"]),
        (sys.executable, ["missing_module_example_20261024"]),
    ]:
        print(json.dumps(check_modules(executable, modules), ensure_ascii=False))

运行 python dependency_probe.py 后，本次实测输出如下：

{"status": "skipped", "reason": "no interpreter selected"}
{"status": "ok", "missing": []}
{"status": "missing", "missing": ["missing_module_example_20261024"]}

这里的 skipped 指调用方没有选定目标解释器。示例本身仍然需要 Python 才能运行，因此它没有模拟“整个计算机都未安装 Python”。若要复现前面的 PowerShell 场景，必须像原始排查那样在独立子进程中限制命令发现范围，不能把传入 None 与卸载解释器混为一谈。

4. 成功需要同时有过程证据和结果证据

子进程启动成功、退出码为零、输出能解析、结果结构有效、缺失列表为空，这几项共同构成成功条件。仅检查标准输出是不是空字符串，会把进程失败、无输出和检查通过混在一起。示例将解释器路径作为独立参数传给 subprocess.run，不使用 shell 拼接；异常处理也覆盖了找不到可执行文件和超时。

这里使用 -I 使目标解释器以隔离模式运行。它会忽略 PYTHONPATH 等环境设置，并排除部分用户路径，所以检查结果针对隔离模式下的模块可见性。若应用依赖项目目录或用户站点目录，需要明确自己的运行环境约定，再决定是否采用隔离模式。不能为了让检查通过而悄悄改变应用实际的模块搜索路径。

对于带点的模块名，find_spec 可能导入父包，因此该方法不适合直接扫描不受信任的任意包。它也不检查二进制扩展加载、动态库、导入时执行的业务逻辑或发行包版本。部署前仍应在受控环境中增加真实导入或应用级健康检查。

5. 回归验证应覆盖失败路径

本次为独立示例执行了 8 个 unittest 测试方法，覆盖未选择解释器、标准库可发现、不存在的模块、缺失父包、无效解释器路径、探测输出异常、超时以及非法模块名。其中异常输出用例通过模拟子进程返回非零退出码、空输出、非 JSON、checked 为 false、missing 类型错误和未知缺失项，确认这些情况均不会被报告成 ok。

标准库和不存在模块的检查使用真实 Python 子进程执行；超时及异常输出使用 unittest.mock 注入，验证的是结果分类逻辑，没有声称人为制造了实际网络超时或破坏过解释器。区分真实执行和模拟故障，能让测试报告的结论更准确。

这种状态区分也适用于云资源检查：没有凭证时应显示未检查，接口调用失败时应显示检查失败，调用成功且发现配置缺口时才输出具体问题。最终汇总还要看必需项是否真正通过；某项 skipped 并不自动代表部署可以继续。把检查前提、执行状态和检测结果分开记录，才能让报告既适合人工排查，也适合后续自动化处理。