📚 课程目录第2章开发环境准备

开发环境准备：操作系统要求、Python版本、包管理工具

写SDK调用之前，先把屋子收拾干净。环境搭对了，后面能省一半的调试时间。我自己踩过不少环境坑，所以这一章我重点讲几个硬指标：操作系统、Python版本、包管理工具。你别觉得基础，实际项目里八成以上的诡异报错都是这三样没对齐。

先说结论：这个SDK官方支持 Windows 10/11（64位）、macOS 12+（Intel / Apple Silicon）和主流Linux发行版（Ubuntu 20.04+、CentOS 7+、Debian 11+）。

我个人的主力机是MacBook Pro M2，但生产环境的CI跑的是Ubuntu 22.04。两套系统我都测过，核心行为一致。但是——嗯，这里要注意——Windows上如果你用PowerShell，编码问题偶尔会冒出来。记得把终端的编码切到UTF-8：

chcp 65001

为什么这么强调Linux？因为很多底层的native依赖（比如一些c扩展）在Windows上编译容易翻车。我曾经在Windows上折腾SDK的编译依赖搞了整整一个下午，最后切到WSL 2十分钟就过了。所以建议你：

这个SDK明确要求 Python 3.9 ~ 3.12。注意：3.8及以下不支持，3.13以上未经全面测试。

你可能会问：“3.11和3.12差别大吗？” 在我实际项目里，SDK内部用了不少3.9+的特性（比如 zoneinfo、match 语句），所以版本太旧直接跑不起来。但也不要盲目追新——我记得去年有个同事直接装了3.13的预发布版，结果SDK里某个C扩展没来得及适配，花了好几个小时定位。

我的个人建议：统一用 Python 3.11。性能比3.9提升明显，而且社区兼容性最好。如果你团队有版本管理规范，那跟着组里的统一版本走。

检查Python版本：
python --version 或 python3 --version。
如果你同时装了多个版本，建议用 pyenv 或 conda 管理，别在系统级混装。

咱们的SDK依赖管理走的是 pip + requirements.txt，标准的Python生态。但实际开发中光有pip不够，你最好再搭配一个虚拟环境工具。

我习惯用 venv（Python 3自带的），轻量、没坑。当然也有人用 Poetry、Pipenv，但除非团队强制，否则我建议你先从venv开始，别给新手期增加复杂度。

python -m venv .venv

激活方式因系统而异：

激活后终端前面会出现 (.venv) 标志，说明成功了。

重要：不要用管理员/root 权限装SDK到系统全局。
我曾经见过有人直接 sudo pip install 然后系统Python环境被搞崩了，恢复起来非常麻烦。虚拟环境就是给你隔离用的，请务必养成习惯。

拿到SDK的发布包（通常是 .whl 或 tar.gz），在激活的虚拟环境里执行：

pip install sdk-xxx.whl

或者如果你是通过 PyPI 安装（如果有公开源）：

pip install your-sdk-name

也可以使用 requirements.txt 一次性装完：

pip install -r requirements.txt

这个文件里不光写了SDK，还有它依赖的第三方库（比如 requests、cryptography）。如果安装过程报错，大概率是某个底层依赖缺少编译工具链。

环境弄完，先跑个最简单的检查脚本：

import sdk
print(sdk.__version__)

如果能正确打印出版本号，恭喜你，环境通了。如果报错 ModuleNotFoundError，先检查虚拟环境有没有激活，再检查pip list里有没有对应的包。

我记得有一次帮新同事排错，他明明装了但报错找不到模块，后来发现他激活的虚拟环境和安装时用的不是同一个终端……这种低级错误我也犯过。

下面这张图把本章的核心逻辑画清楚了——你照着这个步骤走，基本不会偏。

这张图很直白：你先搞定操作系统的基本要求，再确定Python版本，然后用虚拟环境和pip装SDK。每一步都有对应的「避坑点」，走完就进入下一章了。

问题	原因	解决方案
`pip install` 报错编译失败	缺少C编译工具链	Linux安装 `build-essential` / macOS安装 `Xcode CLI`
安装后 `import` 报 `ModuleNotFoundError`	虚拟环境未激活或未安装到当前环境	`which python` 查看当前解释器路径，确认在 `.venv/bin` 下
`python` 命令找不到	系统未添加 PATH	检查安装路径，Windows重新运行安装程序勾选"Add to PATH"
Windows下路径报 `SyntaxError`	反斜杠被当作转义字符	使用原始字符串 `r'路径'` 或正斜杠 `path/to/file`

  简单总结：

操作系统选主流64位，Windows用户推荐WSL2。

Python锁定3.9~3.12，稳定就用3.11。

永远在虚拟环境里操作，别污染系统Python。

好了，环境准备好，下一步咱们就开始初始化SDK。记住我刚刚说的几个关键检查点，特别是 虚拟环境是否激活 这个坑。打开终端，把上面的步骤走一遍，确保你能看到那个版本号再往下翻。