开发环境准备：操作系统、IDE、语言版本、依赖管理
做 SDK 接入改造，第一步就是搭环境。很多人觉得这事简单，装上 Python 就开干。嗯，我以前也这么想，结果被坑过好几次。环境不一致导致的问题，排查起来比写代码还痛苦。所以这一章，我把个人习惯的做法拆开来讲，你跟着走一遍，能少踩很多坑。
操作系统的选择
先说说操作系统。SDK 开发最怕“我机器上能跑，你那边就不行”。其实只要统一一个基线，问题就少一大半。
我个人偏好 Linux 或 macOS。为什么？因为终端生态和包管理更顺手。但 Windows 也不是不行，我见过不少团队用 WSL2 也跑得很稳。下面这张表，是我在实际项目中对比过的差异：
| 操作系统 | 优势 | 坑点 | 推荐场景 |
|---|---|---|---|
| Linux (Ubuntu 20.04+) | 原生 POSIX、Docker 兼容最好 | 桌面体验一般，驱动偶尔折腾 | CI/CD、服务器、重度依赖 C 扩展 |
| macOS (Ventura+) | 终端友好、Xcode 工具链完整 | 文件路径大小写不敏感，偶有兼容差异 | iOS SDK、前端 SDK、日常开发 |
| Windows + WSL2 | 家里 Windows 游戏机也能开发 | 跨文件系统性能损失、网络代理麻烦 | Windows 主力机，但想用 Linux 环境 |
我曾经在一个项目里，团队一半 macOS 一半 Windows。结果因为 os.path.join 和 shutil 的行为差异，浪费了两天联调。后来我们统一在 CI 里跑 Linux 容器，本地爱用啥用啥，但 上线环境强制对齐。这是个血泪教训。
IDE 与编辑器
编辑器这东西很个人。但做 SDK 接入改造，我建议选一个能同时支持 Python 和 JSON/YAML 语法的工具。毕竟我们经常要改配置文件、看日志、写测试。
我目前用得最多的是 VS Code。轻量、插件丰富，远程开发也方便。下面列出几个必装插件：
- Python（微软官方）——代码补全、调试、Linting 一条龙
- Pylance——类型检查，SDK 改造时特别有用，能帮你发现接口签名不匹配
- YAML + JSON——高亮和校验，避免手抖写错配置
- GitLens——看代码历史，方便追溯依赖改动的来源
如果你更喜欢 JetBrains 系，PyCharm Professional 也不错，尤其对大型项目重构支持好。但社区版就够了，别花冤枉钱。
这里有个经验：别在 IDE 里装太多“一键格式化”插件。我曾经被 autopep8 和 black 来回覆盖格式，导致代码提交全是格式噪音。团队里统一一个 formatter 就够了，我推荐 black + isort。
语言版本管理
SDK 接入改造通常要适配多个 Python 版本。你想想看，用户可能还在用 3.8，而你已经写了 3.11 的 match 语句。这兼容性怎么保证？
我的标配是 pyenv + virtualenv。pyenv 管 Python 版本，virtualenv 管项目隔离。具体操作：
# 安装 pyenv (macOS)
brew install pyenv
# 安装目标 Python 版本
pyenv install 3.8.18
pyenv install 3.10.13
pyenv install 3.11.7
# 在项目目录里设置局部版本
cd my_sdk_project
pyenv local 3.10.13
# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate
如果你团队用 conda，也完全可以。但我个人觉得 conda 太重，而且包解析有时慢得离谱。选一个工具坚持用就好，别混着来。
依赖管理
依赖管理是 SDK 改造的“隐形杀手”。很多问题来自锁文件不匹配或传递依赖冲突。这里我给出一个经过验证的流程：
- 用 pip-tools 生成锁文件。只维护
requirements.in，然后编译出requirements.txt。 - 锁定顶级依赖版本。比如
requests>=2.28,<3.0，别写>=2.0这种太宽的范围。 - 用 pip freeze 快照。上线前把虚拟环境里所有包版本记录到
requirements-lock.txt，确保可复现。
一个典型的 requirements.in 示例：
# SDK 核心依赖
requests>=2.28,<3.0
pydantic>=2.0,<3.0
cryptography>=41.0,<42.0
# 开发与测试
pytest>=7.4,<8.0
pytest-mock>=3.11,<4.0
black>=23.0,<24.0
编译命令：
pip-compile requirements.in -o requirements.txt
然后日常安装：
pip install -r requirements.txt
为什么要分两层？因为我以前直接写 requirements.txt，结果升级某个库时把锁文件改乱了，测试环境和生产环境差了三个版本。用 pip-compile 就能从源头上控制。
一站式环境检查流程
下面这张 SVG 把整个准备流程串起来了。你按这个顺序走，基本不会漏步骤。
看到这张图你就明白了：从操作系统开始，一路往下选 IDE、配版本、管依赖，最后验证通过，环境才算准备好。
- 操作系统尽量统一到 Linux 容器，别在环境差异上浪费时间。
- 语言版本用 pyenv 管，项目虚拟环境隔离是底线。
- 依赖管理用 pip-tools 生成锁文件，锁定主版本范围。
- 每次改依赖后，记得重新编译并提交锁文件。
好，环境准备好了。接下来就是真正动手写 SDK 接入改造的代码了。