4、SDK安装与环境配置：Python SDK安装、依赖归纳总结

好了，到了真正动手的环节了。Python SDK 安装这事儿，说实话门槛不高，但坑也不少。我见过不少同事，装完了跑不起来，最后发现是环境没配对。

我的习惯是，先订好规矩，再动手。不然出了问题，排查起来真的很头疼。

4.1 环境准备：先把地基打牢

开始之前，你总得先确认自己站的地方对不对。Python 版本、操作系统、网络环境，哪一步错了都不行。

4.2 安装 Python SDK：两种主流姿势

4.2.1 用 pip 直接装（推荐）

这是最省事的方式。一行命令解决所有问题。

pip install oss2-crypto

但要注意，这里的 oss2-crypto 只是一个代号。实际你用的可能是 minio-crypto 或 s3-crypto-sdk。我个人的做法是，先去 PyPI 搜一下官方包名，再动手。别装了个盗版包，那就有意思了。

4.2.2 从源码编译安装（特殊场景）

什么时候需要走这条路？比如你要定制底层加密算法，或者 PyPI 上没有你需要的版本。

git clone https://github.com/your-repo/oss2-crypto.git
cd oss2-crypto
pip install -e .

加个 -e 参数，就是 editable 模式。我特别喜欢这个模式，改完代码立刻生效，不用反复重装。不过，如果依赖里带了 C 扩展（比如 cryptography），你得先装好 gcc、cmake 这些编译工具。嗯，这里要注意，Windows 用户可能会卡一卡。

4.3 依赖归纳：到底装了什么？

装完 SDK，它背后会拉来一堆依赖。知道这些依赖是干什么的，出了问题你才能快准狠地定位。

如果你用的是 requirements.txt 管理项目，可以直接导出当前环境的依赖清单：

pip freeze | grep -E "(cryptography|oss2|minio|boto3)" > sdk-deps.txt

这样你就能清楚知道，哪个版本被装上了。

4.4 验证安装：确认一切就绪

装完别急着跑业务代码，先写两行测试，看看 SDK 能不能正常导入。

import oss2_crypto
print(oss2_crypto.__version__)

# 试试能不能创建加密客户端
from oss2_crypto import CryptoOssClient
client = CryptoOssClient(endpoint="http://localhost:9000",
                         access_key="minioadmin",
                         secret_key="minioadmin",
                         bucket_name="test-bucket")
print("SDK 初始化成功，加密功能可用。")

如果跑通了，说明环境基本没问题。如果报错，别慌，先看错误日志。我遇到过很多次，都是因为虚拟环境没激活，或者 pip install 时漏了方括号里的 extra（比如 [crypto] 这种）。

4.5 整个流程串起来

下面这张图，是我习惯的安装与配置全流程。你可以照着它一步步走，不容易漏掉关键节点。

4.6 避坑指南：我替你摔过的跤

最后，分享几个实战中经常遇到的小问题。你要是遇到了，直接照着解决就好。

• pip install 报错 "No matching distribution found" —— 八成是 Python 版本不兼容。我遇到过一次，因为用了 Python 3.12，最后降到 3.10 就好了。
• 导入时提示找不到模块 —— 先确认虚拟环境是否激活。很多新手（包括我当年）直接在全局装，然后项目里用的虚拟环境，两套人。
• cryptography 编译失败 —— Linux 下先装 libssl-dev 和 build-essential。Windows 下装个 Visual Studio 构建工具就行。
• 报错 "ModuleNotFoundError: No module named 'six'" —— 老版本 SDK 的遗留问题。手动装一下 pip install six 就解决了。