第1章 搭建专业开发环境

为什么"能跑起来"还不够

你写了一段代码，在自己的电脑上跑通了，于是发给同事。同事一运行就报错——少了个库，或者库的版本不对。问题不在你的代码，而在你没法把"让它跑起来的那一整套环境"也一起寄过去。

这一章要解决的，就是怎么把"在我机器上能跑"变成"在任何人、任何一台干净电脑上都能照着步骤重跑出同样结果"。把它想成一条流水线：原料是代码和依赖，机器是跑代码的程序，质检是测试和检查，装箱单是版本锁定和配置。任何一环只凭"我这里没问题"都不算数。

没有这套流程会怎样？同一段代码今天能跑、明天换台机器就崩；出问题时不知道是代码变了还是环境变了，只能靠运气和回忆去猜。把环境本身也当成要交付的东西，后面所有章节才有稳固的地基。

先做预测

先预测：一段代码在自己电脑上跑通了，是否就证明它能交给别人长期维护？不能。还要说清它靠什么运行、需要哪些外部条件、什么情况下会失败、能看到什么结果、怎么一步步重建。本章就把这条要求当成第一个约定，放进一个可以反复重跑的流程。

原书骨架与现代迁移

官方章节围绕Python实现与工具链、可复现安装、交互提示符、包管理迁移、编辑器与IDE展开。原书出版于Python 2.5与早期敏捷工具生态，本章保留它解释"为什么"的结构；命令和安全默认按当前Python、标准库与PyPA维护文档迁移，不把EasyInstall、distutils安装命令、旧CI或旧项目平台直接当成新项目默认。

承接前两项，把局部语法或工具放回应用数据流。阅读时沿输入、协议、状态、输出和证据追踪，避免只背API名称。

概念讲解

机制一：Python 实现与责任

原书从CPython、Jython、IronPython与PyPy说明实现差异；现代项目仍要记录解释器实现、版本、ABI和平台，不能把Python语言与某个运行时完全等同。原书把CPython、PyPy这类执行Python代码的运行时程序称为 Python实现；选错实现会在 C 扩展或 ABI 上直接报错。

系统包、源码编译和Windows工具链会改变头文件、动态库与扩展构建结果；当前实践应使用受支持解释器和隔离环境，并在干净机器验证创建与安装。先写出公共行为和失败类型，再选择语法或工具——这样即使实现从原书工具迁到当前生态，调用者仍能依据相同契约判断结果。

提醒我们：抽象不能消除成本，只会改变成本出现的位置。包装、生成器、构建系统、CI或缓存都必须说明资源、顺序和异常传播。

先用一段自检代码把"当前跑在哪个实现上"固化下来：

import platform, sys
print(sys.implementation.name)
print(platform.python_version())
print(sys.executable)

sys.implementation.name  解释器实现 —— CPython/PyPy/Jython，决定 ABI
platform.python_version  语言版本 —— 语法与标准库可用范围
sys.executable           解释器路径 —— 锁定当前用的是哪个 venv

机制二：可复现安装与隔离

原书的setuptools与EasyInstall建立依赖安装意识；现代项目用pip、venv和pyproject声明构建边界，旧命令只作为迁移背景。把项目的解释器和依赖关进一个称为 虚拟环境 的隔离目录，再把每个依赖的精确版本固定——这种做法称为 依赖锁定。

边界实验至少包含正常、空输入、上限附近、依赖失败和重复执行。涉及网络、并发或外部制品时，再加入超时、取消、部分完成与摘要校验。

历史工具不等于无价值。正确迁移是先提取声明式配置、隔离、持续反馈和可回滚发布等不变量，再用维护中的接口重写；错误做法是机械替换命令却保留隐式环境和不可追踪副作用。

先用 venv 建一个可丢弃的隔离环境：

python -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip

venv .venv             建隔离环境 —— 把解释器和依赖关进 .venv 目录
activate               进入环境 —— 改写 PATH 与 sys.prefix，指向 .venv
pip install --upgrade  升级安装器 —— 避免旧 pip 装新格式失败

机制三：交互提示符与包管理迁移

在称为 REPL 的交互提示符里逐行试代码，能快速验证表达式和缩小故障范围；但 REPL 会话历史不是可复现程序，有效实验要转成脚本、测试或文档示例。包管理则从 setuptools/EasyInstall 迁到 pip + pyproject：保留声明式配置、隔离、持续反馈这些不变量，而不是机械替换命令却保留隐式环境。

证据闭环：工具配置进版本库

负责收束验收。编辑器、调试器、格式与静态检查共同构成反馈环；工具选择可以变化，但项目配置应进版本库，并能从命令行复现同一检查。保存解释器、依赖锁定、输入、命令、退出状态、关键输出和制品摘要，才能让另一台干净机器重放同一结论。

python -m compileall -q src
python -m unittest discover -s tests
python -m pip check

compileall -q src          编译检查 —— 源码能字节码编译，提前抓语法错
unittest discover -s tests 运行测试 —— 命令行复现同一组断言
pip check                  依赖体检 —— 发现冲突或缺失的已装依赖

交互演示：本章概念地图

把上面五个概念点成一棵可点的地图。猜一猜：依次点开"解释器""隔离环境""REPL""包管理""工具链"五个节点，再打开"故障注入"——哪条失败路径最容易被新手忽略？

实战验收清单

1. 在隔离环境运行三段示例，记录解释器实现、版本和依赖来源。
2. 为核心行为增加正常、空输入、失败和重复执行测试，先看到失败再修改实现。
3. 清理缓存和临时文件后重跑，证明结果不依赖工作区残留。
4. 对历史命令写出当前替代路径，并说明保留的架构不变量与不再采用的安全默认。

迁移决策题

设想团队正在维护一个已经运行多年的Python服务：它仍依赖本章对应的历史工具，但业务不能停机。先不要直接重写。第一步列出Python实现与工具链承担的真实输入和输出，再用可复现安装识别构建或运行时依赖；第二步把交互提示符放进隔离实验，证明当前行为与失败类型；第三步用包管理迁移设计兼容层，让旧入口和新入口在同一组契约测试下运行；最后以编辑器与IDE保存制品摘要、性能或行为差异与回滚条件。只有新路径在正常、边界和故障输入上都达到既定条件，才逐步切换流量或调用者。这样迁移的是可验证契约，而不是把一个旧命令盲目替换为一个新命令。

常见误区

误区 1

现象 → 同一份代码换到 PyPy 或另一台机器就报 ABI/C 扩展错误 原因 → 假设"Python 语言"等于"当前这个运行时"，没记录解释器实现与版本 修法 → 用 sys.implementation.name 与 platform.python_version() 记录实现和版本，C 扩展按 ABI 区分构建

误区 2

现象 → 两个项目依赖同一个库的不同版本，装哪个另一个就崩 原因 → 都装在全局 site-packages 里，没有隔离 修法 → 每个项目用 venv 建独立环境，依赖写进 pyproject 并锁定版本

误区 3

现象 → 在交互提示符里调试出结果，写成脚本重跑却不一样 原因 → 把 REPL 会话历史当成可复现程序，漏掉了中间隐式状态 修法 → 有效实验转成脚本或测试，显式写出全部输入与依赖

误区 4

现象 → 换台电脑拉下代码，编辑器配置和检查规则全没了 原因 → 工具配置只存在 IDE 本地，没进版本库 修法 → 格式化、静态检查、测试命令的配置都提交进版本库，能从命令行复现同一检查

小结

• Python 不等于单一运行时：记录实现、版本、ABI 和平台
• 可复现安装用 venv 隔离，依赖进 pyproject 声明并锁定
• 交互提示符用于探索，有效实验须转脚本或测试
• 包管理从 setuptools/EasyInstall 迁到 pip + pyproject，保留不变量
• 工具配置进版本库，能从命令行复现同一检查

练习与验收

名词解释