3. 开发环境搭建：你得先把“战场”铺好
做操作系统兼容性验证，说白了就是让同一个 SDK 能在 Windows、Linux、macOS 上跑得一样稳。环境搭不对，后面全是坑。我个人习惯是先列一张“支持清单”，再动手装，这样思路不会乱。
3.1 支持的操作系统与版本
我手上的这套 SDK 主要面向三个主流平台。每个平台的版本很多，但真正经过我们 CI 全量覆盖的，其实就那么几列。我建议你优先选用下表里的版本，能省掉很多莫名其妙的兼容问题。
| 操作系统 | 架构 | 推荐版本 | 最低要求版本 | 备注 |
|---|---|---|---|---|
| Ubuntu | x86_64 / aarch64 | 22.04 LTS | 20.04 LTS | 内核 ≥5.15，gcc 11+ |
| CentOS / Rocky Linux | x86_64 | Rocky 9.3 | CentOS 7.9 | 建议用 Rocky，CentOS 7 已停止更新 |
| Windows | x86_64 | Windows 11 22H2 | Windows 10 20H2 | 需安装 Visual Studio 2022 生成工具 |
| macOS | arm64 (M系列) / x86_64 | Sonoma 14.x | Ventura 13.x | Xcode 15+，Command Line Tools 必须装 |
小经验： 别在 WSL1 里跑我们的 SDK。WSL2 可以，但需要确保内核版本 ≥5.10。我曾经因为 WSL1 的文件系统兼容问题，浪费了整整两天去追一个“看起来像内存越界”的 bug。
3.2 安装要求：先看清单再动手
环境装到一半发现缺依赖，真的很烦。我列了个最小依赖集，你在开始之前最好都确认一遍。
3.2.1 基础编译工具链
- Linux：gcc ≥11, g++ ≥11, make ≥4.3, cmake ≥3.22, pkg-config, autoconf, libtool
- Windows：Visual Studio 2022 Build Tools（社区版即可），或 MSYS2 + MinGW-w64
- macOS：Xcode Command Line Tools（xcode-select --install），cmake via brew
3.2.2 语言运行时
- Python 3.10+（推荐 3.11），需要 pip 和 venv
- Go 1.21+（如果 SDK 包含 Go 绑定）
- Rust 1.75+（可选，用于性能敏感模块）
3.2.3 关键系统库
| 库名 | Linux (apt/ yum) | macOS (brew) | Windows |
|---|---|---|---|
| openssl-devel | libssl-dev | openssl | vcpkg install openssl |
| libcurl | libcurl4-openssl-dev | curl | vcpkg install curl |
| libxml2 | libxml2-dev | libxml2 | vcpkg install libxml2 |
| zlib | zlib1g-dev | zlib | 内置（需勾选桌面开发） |
注意： 不要在系统 Python 里直接 pip install，一定用虚拟环境。我曾经在生产环境上因为系统 Python 被污染，导致整个 CI 缓存都失效了，教训惨痛。
3.3 配置步骤：按顺序来，别跳
下面是我反复验证过的最稳的一套流程。你跟着走，基本不会出幺蛾子。
3.3.1 Linux 环境（以 Ubuntu 22.04 为例）
- 更新系统包索引：
sudo apt update && sudo apt upgrade -y - 安装基础工具：
sudo apt install build-essential cmake pkg-config libssl-dev libcurl4-openssl-dev libxml2-dev zlib1g-dev -y - 安装 Python 3.11：
sudo apt install python3.11 python3.11-venv python3.11-dev -y - 创建虚拟环境：
python3.11 -m venv ~/sdk_env source ~/sdk_env/bin/activate - 验证编译器版本：
输出应显示 gcc ≥11，cmake ≥3.22。gcc --version cmake --version
3.3.2 Windows 环境
- 安装 Visual Studio 2022 Build Tools —— 务必勾选“使用 C++ 的桌面开发”工作负载。
- 安装 Git for Windows，并在安装时选择“将 Git 添加到 PATH”。
- 安装 Python 3.11 官方安装包，勾选“Add Python to PATH”。
- 打开“Developer Command Prompt for VS 2022”，执行：
pip install virtualenv virtualenv ~\sdk_env ~\sdk_env\Scripts\activate - 用 vcpkg 安装缺少的系统库（可选）：
git clone https://github.com/microsoft/vcpkg .\vcpkg\bootstrap-vcpkg.bat .\vcpkg\vcpkg install openssl curl libxml2
3.3.3 macOS 环境
- 安装 Xcode Command Line Tools：
xcode-select --install - 安装 Homebrew：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" - 用 brew 安装工具链：
brew install cmake pkg-config openssl curl libxml2 - 安装 Python 3.11：
brew install python@3.11 - 创建虚拟环境：
python3.11 -m venv ~/sdk_env source ~/sdk_env/bin/activate
验证全部通过后，建议跑一下 SDK 自带的
sdk_check_env.sh（Linux/macOS）或 sdk_check_env.bat（Windows）。这个脚本会检查所有依赖和编译器版本，比人眼可靠多了。
3.4 一张图看懂搭建全流程
下面这个 SVG 图把三个平台的关键步骤和判断点画出来了。你可以把它钉在工位旁，照着走不会迷路。
3.5 常见问题与避坑
- “找不到 -lssl”：Linux 下没装 libssl-dev，或者系统有多个 openssl 版本。建议统一用 apt 安装，不要自己编译。
- “Python.h 找不到”：没装 python3-dev 或者 python3.11-dev。Windows 下要选“Development Tools”组件。
- “cmake 版本太低”：Ubuntu 20.04 自带 cmake 3.16，确实不够。可以用 pip 装最新版：
pip install --upgrade cmake。 - macOS 下 brew link 冲突：有时 openssl 和系统内嵌的 SSL 会有冲突。可以用
brew link --overwrite openssl解决。我之前被这个坑了大半天，后来发现是 brew 没有正确设置 LDFLAGS。
特别提醒： 如果你在公司内网环境（没有外部网络），记得提前下载好 vcpkg 的 ports 包或者配置本地镜像源。否则安装依赖时会卡死在 “Fetching dependencies” 这一步。我的做法是在有网环境的虚拟机里跑一遍
vcpkg install，然后把整个 vcpkg 目录压缩打包，拷到内网环境里直接解压用。
环境搭好之后，下一步就是跑我们的第一个验证用例了。不过那已经是下一件事了，你先把自己的机器搞利索再说。