第2章 开发环境搭建：Python环境、依赖管理、SDK安装与配置
说到开发环境搭建，这可能是整个课程里最容易被忽略、却坑最多的一步。我记得有次接手的项目，对方用了Py2.7写加密逻辑，生产环境跑了一周开始乱码。查了一通发现是Python版本不兼容。嗯，从那以后，我所有加密项目都先锁死环境。
这一章我们就来解决一个问题：把你的机器变成一个可复现、可靠的加密SDK开发工作站。说白了，就是让项目换台电脑也能一键跑起来。
2.1 Python版本选型与安装
加密库对Python版本很挑剔。尤其是涉及底层C扩展的包（比如cryptography、pycryptodome），有时在3.7能编译通过，3.10就报语法错误。
我个人推荐范围：Python 3.8 ~ 3.11。3.12刚出时我和团队试过，有几个老牌加密库的wheel还没跟上，踩了一周坑才切回3.10。
| Python版本 | 推荐度 | 原因 |
|---|---|---|
| 3.8 | ⭐⭐⭐⭐ | 稳定，兼容性最好，适合老项目 |
| 3.9 | ⭐⭐⭐⭐⭐ | 我最常用，生态完整，性能均衡 |
| 3.10 | ⭐⭐⭐⭐ | 支持模式匹配，新特性多 |
| 3.11 | ⭐⭐⭐ | 性能提升大，但部分库wheel发布滞后 |
pyenv 或 conda。我倾向 conda，因为它连非Python依赖（如OpenSSL）也一起管了，加密项目特别方便。
2.2 环境隔离：为什么必须用虚拟环境
你想想，一个项目依赖cryptography 3.4，另一个项目依赖3.6。如果直接装在系统Python里，你迟早会疯。我之前就遇到过，升级系统级pip时把所有项目的加密库都搞崩了。
目前主流的三种隔离方案：
- virtualenv / venv： Python自带，轻量，适合小项目。但换目录就废，跨项目迁移麻烦。
- Conda： 重但稳。能管理Python版本、C库、甚至R语言。我所有加密项目都锁conda环境。
- Poetry / Pipenv： 把依赖声明和环境管理合起来了。如果团队新人多，我推荐Poetry，因为它有lock文件，能确保每个人装的依赖版本一模一样。
我个人习惯用conda + pip结合。conda管大环境，pip管那些conda源里没有的包。但注意，混用时别用--user参数，容易破坏隔离。
# 创建独立环境，指定Python版本
conda create -n crypto-sdk python=3.10
# 激活环境
conda activate crypto-sdk
# 验证Python版本和路径
which python
# 输出应为：/Users/yourname/miniconda3/envs/crypto-sdk/bin/python
python --version
# Python 3.10.x
conda activate 的习惯。
2.3 依赖管理：requirements.txt vs pyproject.toml
我以前只用requirements.txt。但后来项目多了，发现它有个致命缺陷——没有lock机制。团队里A装的是1.0.1，B装的是1.0.2，虽然理论上兼容，但加密库的微版本升级经常改接口。
现在我的做法是： 同时维护两个文件。
requirements.in：记录顶层依赖（只写包名，不写版本或写范围）requirements.txt：用pip freeze生成的完整锁定版本列表
如果是新项目，我会直接用 pyproject.toml + poetry.lock。Poetry会自动解析依赖树，锁住每个子依赖的哈希和版本。
# 安装Poetry（如果没用conda）
pip install poetry
# 在项目根目录初始化
poetry init
# 添加核心依赖
poetry add cryptography==41.0.7
poetry add requests==2.31.0
# 添加开发依赖
poetry add --dev pytest pytest-cov
# 安装所有依赖
poetry install
# 导出requirements.txt（供CI/CD使用）
poetry export -f requirements.txt -o requirements.txt
pytest。加密库的接口调整很频繁，不测一下直接上生产，等到解密失败才回头排查，就晚了。
2.4 SDK安装与验证
好，环境建好了，依赖装了。接下来就是把我们课程要用的加密接口SDK装进去。
这里假设SDK已经发布到了PyPI（或者我们内部私有源）。如果是私有源，记得先配置 pip.conf 或设置环境变量 PIP_INDEX_URL。
# 激活刚才建好的环境
conda activate crypto-sdk
# 直接从PyPI安装
pip install crypto-interface-sdk==0.2.0
# 如果是企业内部私有源
pip install --extra-index-url https://pypi.company.com/simple \
crypto-interface-sdk==0.2.0
# 验证安装
python -c "import crypto_sdk; print(crypto_sdk.__version__)"
# 输出：0.2.0
如果遇到ImportError，最可能的原因：
- 你安装到了base环境，但当前激活的是crypto-sdk环境。
- Python解释器路径不对。用
which python检查，确保指向conda环境内部。 - 依赖冲突。比如
cryptography版本与cffi不兼容。这时用pip check可以快速扫描。
# 快速检查依赖一致性
pip check
# 如果提示冲突，重新安装当前环境所有包
pip install --upgrade --force-reinstall -r requirements.txt
python3命令，结果pip3 install安装到了/usr/local/lib，而项目用的是conda虚拟环境。互相看不到。记住：永远不用sudo pip install，永远在虚拟环境里执行。
2.5 本章知识体系总览
下面这张图总结了整个开发环境搭建的流程和关键节点。你可以把它贴在办公桌旁边，每次搭建新项目时照着过一遍。
2.6 常见疑难与快速诊断
搭建过程中难免会遇到问题。我把这几年最常见的几个场景整理成了一张表，方便你对照排查。
| 现象 | 最可能原因 | 快速解决 |
|---|---|---|
pip install时报"externally managed environment" |
系统Python被OS保护，禁止pip直接写site-packages | 切换到conda或venv虚拟环境 |
| 安装cryptography时报编译错误（缺少openssl头文件） | 底层C库不完整 | conda install openssl，或用conda直接装cryptography（自带预编译wheel） |
import crypto_sdk成功但调用时报AttributeError |
缓存了旧版本的.pyc文件 |
find . -name "*.pyc" -delete，重新import |
conda环境激活后python还是指向系统Python |
shell未重新加载PATH |
conda init，然后重新打开终端；或用conda run -n crypto-sdk python强制指定 |
which python确认解释器路径python -c "import sys; print(sys.path)"看模块搜索路径pip list核对已安装的包和版本
环境搭建这事，一次配置好就能一劳永逸。我建议你把environment.yml或poetry.lock提交到Git仓库。这样新成员拉下代码后，一条命令就能拉起完全一致的环境，省去反复沟通“你用的什么版本”的时间。