3.1 环境搭建与开发准备

新同事第一天，照着文档十分钟起好环境

在实践层的起点，环境一致性是后面一切的地基。我们主张：环境自检应该是一段可运行的脚本，而不是写给人看的一段话。

下面给出一段跨平台的依赖自检。它不假设你已装好什么，而是逐项验证并给出明确结论。

import importlib, sys

REQUIRED = {'numpy': '1.24', 'leann': '0.3'}

def check_env():
    report = []
    for pkg, ver in REQUIRED.items():
        try:
            mod = importlib.import_module(pkg)
            ok = getattr(mod, '__version__', '?')
            report.append(f'{pkg} 已装 版本={ok} 期望>={ver}')
        except Exception as e:
            report.append(f'{pkg} 缺失: {e}')
    return report

for line in check_env():
    print(line)
​

这段脚本的取向是「失败要可见」：缺一个包就明确报出来，而不是等到运行时抛奇怪的错。边缘设备常用 ARM 架构，某些包要装对应轮子，自检能提前暴露。

虚拟环境是另一道保险。下面用标准库方式生成一份 requirements 校验，确保团队用的版本一致。

def freeze_check(pinned):
    import pkg_resources
    bad = []
    for name, ver in pinned.items():
        try:
            have = pkg_resources.get_distribution(name).version
            if have != ver:
                bad.append((name, have, ver))
        except Exception:
            bad.append((name, '缺失', ver))
    return bad

print('版本漂移:', freeze_check({'numpy': '1.24.3'}))
​

案例：ARM 设备缺轮子

• 背景：x86 开发机一切正常，树莓派上 import 报错。
• 操作：跑上面的 check_env，发现 leann 的 ARM 轮子没装，提示缺失。
• 结果：换装 ARM 兼容构建，环境自检通过，后续流程一路绿灯。
• 解读：自检脚本把「设备差异」变成「明确报错」，比事后调试省数小时。
• 变式：可把自检接进 CI，每次提交都验证依赖声明是否完整。

环境自检还能更深一层：当依赖冲突真的出现，光报「缺失」不够，要能定位是哪两个包抢同一个底层库。下面给出一段冲突扫描，比较已装包的依赖树里是否出现同一库的两个大版本。

def find_conflicts(installed):
    # installed: 包名->版本，这里用简化规则演示冲突本质
    seen = {}
    conflicts = []
    for name, ver in installed.items():
        major = ver.split('.')[0]
        if name in seen and seen[name] != major:
            conflicts.append((name, seen[name], major))
        seen[name] = major
    return conflicts

print('冲突:', find_conflicts({'numpy': '1.24', 'leann': '0.3'}))
​

这段例子的重点是「思路」：冲突的本质是同一库出现不兼容的主版本，定位到它就能精准升级而非全盘重装。边缘设备常遇到的是 ABI 不匹配，即 C 扩展编给旧 glibc 而新系统跑不了，自检可加一项动态库探测，把这类问题在装机阶段暴露，而不是等到推理时崩溃。

环境这件事，最贵的不是搭起来，而是「别人也能搭起来」。我们见过太多项目，原作者机器上跑得飞起，换个人就卡三天。根因往往是环境只活在原创者的脑子里，没落到可执行的检查里。自检脚本的价值，就是把「我机器上是好的」变成「任何人跑这条命令都是好的」，让环境从个人经验变成团队资产。

更进一步，自检应进持续集成。每次有人改依赖声明，CI 就跑一遍 check_env，声明和实际不一致立刻红。这样环境漂移在提交时就被拦下，而不是在集成后爆发。我们把这称为「把摩擦前移」：越早暴露的问题，修复成本越低，这是贯穿全册的工程取向，从配置校验到健康检查都是同一逻辑。

环境一致性还有个延伸议题：开发、测试、生产三套环境能否用同一份声明。我们见过开发用最新版、生产用旧版，问题只在生产冒头，定位时却拿开发环境复现不出来。解决方法是同一份依赖锁定文件贯穿三环境，任何人装都是同一组版本，差异被消灭在源头。

对于边缘设备，还要考虑目标架构的差异。x86 上编的包，到 ARM 可能根本 import 不了，自检脚本必须在实际目标架构上跑，而不是在开发机上代跑。我们建议 CI 里挂一台真实目标设备或用对应架构的模拟环境，让自检在「真家伙」上验证。

最后一步是把环境打包成可分发单元。无论是容器镜像还是系统包，目标是让别人拿到就能跑，而不是拿到一份安装说明书。文档降级为备查，可执行单元才是主路径。这把「环境」从一段知识变成了一个物件，是工程成熟度上台阶的标志。我们也提醒别过度依赖单一环境的固化镜像，更好的做法是镜像只装运行时，依赖由锁定文件在启动时拉齐，既快又可控。

我们还建议把环境自检的通过标准也写进文档开头，让人一眼知道「什么算就绪」。就绪标准越明确，新人自我排查的成功率越高，求助的次数就越少。环境文档的最高形态，是让人不需要提问就能跑通，自检脚本就是这份文档的可执行版本。当文档和脚本合二为一，知识就不再有「说过」和「能做到」之间的缝隙。

环境准备好之后，真正的考验是「别人能否复现你的成功」。我们见过太多「在我机器上是好的」，这类问题一半以上源于环境差异。自检脚本把环境变成可执行的断言，谁的环境不达标一眼可见。把这一步做扎实，后面所有调试都能省下大量扯皮时间，这是性价比最高的一笔工程投入。

本节可考核点：能说出环境自检为何比文档更有用，并写出「缺依赖即明确报错」的最小实现思路。