第 3 章：环境准备——操作系统、编程语言运行时与包管理工具

说实话，SDK 的坑，有一大半都出在环境准备上。

我记得刚带团队那会儿，有新人拿着官方文档一步步配，结果连 hello world 都跑不起来。查了一下午，原来是操作系统里少装了一个 C++ 运行时库。你想想看，一个 SDK 初始化教程要是开头就卡了，后面讲再多鉴权流程都没用。

所以我个人习惯，每接手一个新项目，先把环境列成清单，逐项打勾。这一章我们就来把这三件事说清楚：操作系统、语言运行时、包管理工具。

3.1 操作系统选择与基础配置

主流的 SDK 开发调试环境有三个：Windows、macOS、Linux。选哪个？

我的答案是：看你项目的部署目标。如果最终跑在 Linux 服务器上，那开发环境也尽量用 Linux 或 WSL2。如果只是做客户端插件，Windows 或 macOS 完全够用。

我在项目中遇到过一个问题：团队里有人用 Windows 原生 cmd 跑 shell 脚本，路径分隔符是反斜杠，结果 SDK 的构建脚本硬编码了 POSIX 路径，直接报错。

从那以后，我强制要求所有人用 PowerShell 7+ 或 WSL2 的 bash。Windows 用户可以用下面命令快速装 WSL2：

# 管理员权限打开 PowerShell
wsl --install -d Ubuntu-22.04
wsl --set-default-version 2

装完后记得检查一下系统区域设置。有些 SDK 的国际化模块依赖 LC_ALL 环境变量，没设对的话，日志里全是乱码。

说白了，环境准备的第一步就俩字：对齐。你用的操作系统版本、位数、编码、时区，最好与线上服务器保持一致。不然 Debug 时总会冒出一些“本地能跑远程挂”的诡异问题。

3.2 编程语言运行环境

SDK 通常提供多种语言版本。我见过最多的三种：Python、Node.js、Java。其他像 Go、C++、Rust 也不是没有，但入门门槛稍微高一点。

3.2.1 Python 运行时

Python 的版本分裂很要命。SDK 文档说支持 3.8+，你装了个系统自带的 3.6，然后吭哧吭哧装依赖，发现一堆 typing 语法报错。

我建议用 pyenv 来管理 Python 版本，可以随时切换。下面是快速安装脚本：

# macOS / Linux
curl https://pyenv.run | bash
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
exec "$SHELL"

# 安装指定版本（例如 3.11.4）
pyenv install 3.11.4
pyenv global 3.11.4

3.2.2 Node.js 运行时

Node.js 的版本切换更常见，因为 npm 生态依赖 Node 版本非常敏感。我用 nvm（Node Version Manager）已经好多年了，没出过大问题。

# macOS / Linux
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# 安装并使用 LTS 版本
nvm install 18
nvm use 18
node -v   # 应该看到 v18.20.x

Windows 用户可以使用 nvm-windows。注意：不要混用 nvm 和 nvs，它们管理的配置文件会冲突。我在项目中遇到过一次，CI 里总读到不同的 Node 版本，折腾了半小时才发现是全局 nvm 脚本被覆盖了。

3.2.3 Java 运行时 (JDK)

Java 的环境准备相对成熟。大部分 SDK 要求 JDK 8 或 11。但我个人更推荐 JDK 17，因为它在安全性和性能上都有明显提升，而且很多新特性可以用。

用 SDKMAN 来管理 JDK 版本非常方便。它不仅能管理 Java，还能管理 Scala、Kotlin、Maven 等。

curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"

# 安装 JDK 17 (Eclipse Temurin)
sdk install java 17.0.10-tem
sdk use java 17.0.10-tem

安装完后一定要检查 JAVA_HOME 环境变量是否指向正确的路径。我在调某个支付 SDK 时，因为 JAVA_HOME 指向了旧版 JDK 8，结果签名算法报错，白白浪费了一下午。

3.3 包管理工具安装与配置

不管用哪种语言，包管理工具都是 SDK 依赖的搬运工。但很多人只装不管配，结果下载速度慢、版本冲突、甚至下载到恶意包。

3.3.1 pip (Python)

pip 如果默认从 PyPI 下载，在国内常常超时。我建议配置阿里云或清华源：

# 全局配置
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn

# 验证
pip install requests   # 应该能瞬间下载

另外，永远不要把依赖装到系统 Python 里。用 venv 或 conda 创建虚拟环境，这是最基本的卫生习惯。

3.3.2 npm (Node.js)

npm 在国内同样需要换源。我个人更喜欢用 cnpm（淘宝镜像），但官方现在推荐用 npm config set registry 来设置：

npm config set registry https://registry.npmmirror.com
# 可选：检查是否生效
npm config get registry

3.3.3 Maven / Gradle (Java)

Maven 的默认中央仓库在国外。我通常在 ~/.m2/settings.xml 里配置阿里云镜像：

<mirrors>
  <mirror>
    <id>aliyunmaven</id>
    <mirrorOf>central</mirrorOf>
    <url>https://maven.aliyun.com/repository/central</url>
  </mirror>
</mirrors>

Gradle 可以在 ~/.gradle/init.gradle 里配置全局仓库：

allprojects {
    repositories {
        maven { url 'https://maven.aliyun.com/repository/public' }
        mavenCentral()
    }
}

这些配置配一次，能省后面 SDK 依赖下载的好几倍时间。我在之前做过一个微服务网关项目，依赖 20 多个第三方库，配了镜像后构建时间从 15 分钟缩短到 3 分钟——简直是质变。

3.4 用一个图串起来

环境准备其实是一条链：

从上到下，每个层级选对工具、配好版本、设好源，SDK 的依赖环境就稳了。我自己每次搭建新开发机，都用这个流程走一遍，基本不会出幺蛾子。

3.5 最后的测试：环境清单

配完以后别急着写代码。跑一遍下面的命令，确认关键组件的版本与你 SDK 文档要求的一致：

# 操作系统版本
cat /etc/os-release  # Linux
sw_vers              # macOS
winver               # Windows（需手动打开对话框）

# Python
python --version
pip --version

# Node.js
node --version
npm --version

# Java
java --version
mvn --version        # 如果装了 Maven
gradle --version     # 如果装了 Gradle

我曾经因为 python3 和 python 指向不同版本，导致 SDK 的脚本拿错了解释器。后来我养成了一个习惯：在项目根目录写一个 env-check.sh 脚本，每次初始化前跑一遍。这是个小动作，但能救大命。