环境准备：开发环境要求、依赖管理、版本兼容性检查

做 SDK 集成，第一步不是写代码，是先把环境收拾利索了。我见过太多人上来就 npm install，结果 build 报一堆红，一查是 Node 版本不对。今天咱们就聊聊环境准备这个“地基活”。

3.1 开发环境要求

说白了，你得知道 SDK 在什么机器上能跑起来。不同 SDK 的要求差别挺大，但有几条是共通的。

• 操作系统：Windows / macOS / Linux，记得看 SDK 文档里写的支持列表。我遇到过有人拿 M1 Mac 编译 ARM 库，结果 SDK 只提供了 x86 的预编译 .a 文件……踩坑之后我养成了先看 os/arch 的习惯。
• 语言运行时：比如 Android SDK 需要 Java 8+、Kotlin 1.5+；iOS SDK 需要 Swift 5.0+。别想当然，直接上表格。

平台	最低版本要求	推荐版本	备注
Android	API 21 (Android 5.0)	API 33+	Gradle 7.0+
iOS	iOS 12.0	iOS 15.0+	Xcode 13+
JavaScript	Node.js 14	Node.js 18 LTS	npm 8+ / yarn 1.22+

3.2 依赖管理

依赖管理本质上就是“告诉我你家的 SDK 要吃什么，我好给你端上来”。常见的包管理器就那些，但坑往往在版本号上。

3.2.1 包管理器选择

• Android：Gradle + MavenCentral / JitPack。依赖声明在 build.gradle 的 dependencies 块里。
• iOS：CocoaPods / SPM / Carthage。我个人最推荐 SPM，因为不用装 Ruby 和 CocoaPods 那一套。
• JavaScript：npm / yarn / pnpm。嗯，我现在基本只用 pnpm，速度快，还省磁盘。

3.2.2 依赖声明与锁定

你会看到 SDK 文档里通常给一个 package.json 示例片段，类似这样：

{
  "dependencies": {
    "@xxx/sdk-core": "^2.3.0",
    "@xxx/sdk-ui": "~1.0.4"
  }
}

这里 ^ 表示允许小版本升级，~ 只允许 patch 版本。为什么这么搞？为了避免你装到不兼容的版本。

我建议你提交 package-lock.json 或 yarn.lock 到仓库。不然 CI 上和本地装的依赖版本可能不一样。我之前遇到过因为 lock 文件没提交，导致线上 build 出了个低级 Bug，排查了俩小时。

3.3 版本兼容性检查

版本兼容性是最烦人的，尤其是你的项目里已经有一堆第三方库了。SDK 可能跟某个版本的 OkHttp 冲突，或者跟 React Native 的 Hermes 不兼容。

3.3.1 语义化版本（SemVer）

版本格式	含义	举例
MAJOR.MINOR.PATCH	主版本.次版本.补丁	2.3.1
^2.3.0	允许 2.x.x，但不允许 3.0.0	可安装 2.4.0，不可安装 3.0.0
~1.0.4	只允许补丁版本	可安装 1.0.5，不可安装 1.1.0

3.3.2 冲突检查工具

• npm：npm ls <package> 查看依赖树；npm dedupe 尝试扁平化。
• Gradle：./gradlew dependencies 打印完整的依赖图，还能看到冲突标记。
• CocoaPods：pod outdated 检查过时版本；pod deintegrate 重置。

举个例子。你项目里用了 react-native 0.70，SDK 依赖 @react-native-async-storage/async-storage 某一个版本，结果你又在别的地方装了另一个版本。这时候 npm ls async-storage 就能看到两个版本并存——大概率会有运行时崩溃。

整体流程：看看图就清楚了

我把环境准备的核心逻辑画成了下面这张图，帮你快速建立全局印象。

从图里能看到，三个步骤是顺序推进的：先把开发环境确认清楚，然后拉依赖并锁定版本，最后检查兼容性。全部通过后，集成才不会翻车。