4、SDK 环境准备与安装：让开发环境跑起来
环境配置，说白了就是给代码找个舒适的窝。我见过太多人跳过这步，结果被诡异的报错折磨一整天。嗯，这一节我们就把窝搭好。你想想看，一个干净的 Python 虚拟环境，配上正式签发的令牌化 SDK 包，这就是安全开发的起点。
4.1 Python 虚拟环境：为什么要建个“隔离区”？
Python 的全局环境就像公共厨房，谁都能往里扔东西。今天装个 A 库，明天装个 B 库，版本冲突是迟早的事。我个人习惯，每个项目都建一个独立的虚拟环境。这样项目 A 用 Django 3.2，项目 B 用 Django 4.0，互不干扰。
虚拟环境的核心工具是 venv（Python 3.3+ 自带）或 virtualenv。我推荐直接用 venv，少装一个依赖就是少一个潜在坑点。
4.1.1 创建虚拟环境
打开终端，进入你的项目目录，然后执行这条命令：
python3 -m venv _sdk_env这会在当前目录下创建 _sdk_env 文件夹。里面藏着 Python 解释器、pip 和一套干净的 site-packages。为什么叫 _sdk_env？因为这是专门给令牌化 SDK 用的，命名清晰，团队其他人一看就懂。
.gitignore。虚拟环境不应提交到版本库，因为它是可复现的。队友拉下代码后，自己重建就行。
4.1.2 激活虚拟环境
不同操作系统激活方式不同。Windows 上：
_sdk_env\Scripts\activatemacOS / Linux 上：
source _sdk_env/bin/activate激活后，终端前面会出现 (_sdk_env) 这样的标记。这说明你已经在隔离环境里了。有时候激活失败是因为执行策略限制（Windows）或权限问题（Linux）。我记得有一次在一台新买的 Mac 上，执行 source 后没反应，后来发现是 Shell 配置问题，切换成 bash 就好了。
4.2 pip 安装令牌化 SDK 包
环境激活好了，接下来装 SDK。官方包通常发布在 PyPI（Python Package Index）上。我用 pip 安装，它的全称是“Pip Installs Packages”，挺好记的。
4.2.1 直接安装
假设这个 SDK 叫 -sdk，在 PyPI 上可用。安装命令：
pip install -sdkpip 会自动解析依赖。比如 SDK 依赖 cryptography 和 requests，它会一并下载。输出信息像流水账一样，但你要关注最后几行——Successfully installed 后面列出的包名和版本号。没看到这个，就是失败了。
--index-url。比如：pip install -sdk --index-url https://pypi.company.com/simple/。我曾经用过一次公共源安装公司内部包，结果装了个同名但功能完全不同的库，折腾了半小时。
4.2.2 从 requirements.txt 安装
团队开发时，建议用 requirements.txt 锁定版本。它的内容大概是这样：
-sdk==1.2.3
cryptography==41.0.7
requests==2.31.0安装命令：
pip install -r requirements.txt这么做的好处是环境完全可复现。不然你本地装了个 1.2.3 版本，同事装的是 1.2.5，接口变了，bug 就会找上门来。
4.2.3 升级已有 SDK
如果 SDK 发布了新版本：
pip install --upgrade -sdk升级后一定要重跑测试。我有过惨痛教训：只看了更新日志觉得没问题，结果一个函数的参数顺序变了，线上直接报错。嗯，升级后务必验证。
4.3 验证安装是否成功
装完别急着关终端。先验证一下。最简单的方法：进入 Python 交互环境，导入包。
python
>>> import _sdk
>>> _sdk.__version__
'1.2.3'没报错，说明安装成功。更正式的验证方式，是调一下 SDK 的健康检查接口：
from _sdk import Client
# 初始化客户端，参数为环境地址和令牌
client = Client(base_url="https://api.tokenization.dev", ="test_key")
print(client.check_health())如果输出 {'status': 'ok'} 或类似信息，恭喜你，环境已经完全就绪。
check_health 返回 401 或 500，可能是 不对或网络有问题，不一定是安装失败。
4.4 常见安装报错解决
安装过程中，报错是家常便饭。我整理了几个高频问题，附上解决方案。
| 报错信息 | 原因 | 解决方案 |
|---|---|---|
No matching distribution found for -sdk |
PyPI 上找不到这个包 | 检查包名拼写；确认是否使用了私有源 |
Could not find a version that satisfies the requirement cryptography |
依赖包无法解析 | 升级 pip：pip install --upgrade pip；或手动安装依赖 |
error: Microsoft Visual C++ 14.0 is required |
Windows 上缺少 C++ 编译工具 | 安装 Microsoft C++ Build Tools；或使用预编译 wheel |
Permission denied 或 Operation not permitted |
系统权限不足 | 激活虚拟环境后再安装；避免用 sudo pip install |
pip: command not found |
pip 未安装或未在 PATH 中 | 使用 python -m pip install ...；或重新安装 Python |
Windows 用户常遇到编译问题。比如 cryptography 需要 OpenSSL 库，安装时可能报错。解决办法很简单：去 PyPI 或 Gohlke's site 下载对应 Python 版本的 .whl 文件，然后用 pip install path/to/your.whl 安装。这不是偷懒，是合理利用生态。
sudo pip install。这会让你系统全局的 Python 环境变得一团糟。我见过一位同事不小心用 sudo 装了个不兼容的版本，结果系统工具都打不开了。虚拟环境就是为此而生——没必要用 sudo。
4.5 环境安装核心工作流
下面这张图展示了从创建虚拟环境到验证安装的完整流程。我把它画出来，方便你对照操作。
这张图总结了核心步骤。照着做，环境问题基本能一次搞定。如果报错，别慌——先看错误信息，再查表格里的对应方案。大部分问题都能五分钟内解决。