SDK接入常见问题排查与定位指南 - 第2节

## 环境准备：开发环境搭建、依赖管理工具与版本号管理

做SDK接入，头一件事就是把环境搭好。我见过不少同学上来就写代码，结果编译报错一堆，最后发现是JDK版本不对、Gradle缓存没清干净……白白浪费半天时间。说白了，环境准备就是给SDK铺一条跑道，跑道不平，轮子再好也跑不起来。

1. 开发环境搭建：工具链的基准线

先说IDE。Android开发我推荐Android Studio，iOS自然用Xcode，跨平台用VS Code或CLion。但我个人习惯把IDE版本固定下来，尤其是团队协作时。我记得有一次，团队里有人用Android Studio Arctic Fox，有人用Chipmunk，结果Gradle插件版本不兼容，拉了一整天才对齐。所以我的建议是：在项目README里写清楚IDE最低版本，或者干脆用 `.idea` 配置锁定。

接着是JDK。Android SDK 31以上需要JDK 11，老项目可能还在用JDK 8。我踩过一个坑：项目gradle.properties里配了jdk路径，但系统环境变量指向别的版本，导致签名证书校验失败。解决方案很简单：统一用`JAVA_HOME`环境变量，并在CI脚本里显式echo出来做确认。

对于iOS，Xcode版本和Command Line Tools必须匹配。我建议用`xcode-select --print-path`检查当前路径，再用`xcodebuild -version`确认。之前有同事装了两个Xcode，打包时选了beta版，SDK里的Swift代码编译不过，折腾了两小时才发现。

此外，NDK、CMake、Python、Node.js这些依赖也要提前列好。我用一张表记录常用版本对照，分享给你：

平台	SDK类型	推荐IDE版本	必需工具链
Android	AAR / JAR	Android Studio Hedgehog+	JDK 11+, Gradle 8.x+, AGP 8.x
iOS	.xcframework	Xcode 15+	Xcode Command Line Tools, CocoaPods 1.15+
Flutter	plugin	VS Code / Android Studio	Flutter 3.x+, Dart 3.x+, CocoaPods
macOS	.framework	Xcode 14+	Xcode CLT, Swift 5.8+

2. 依赖管理工具：Gradle / Maven / CocoaPods / SPM

依赖管理工具是SDK接入的桥梁。不同平台有不同的生态，但核心逻辑就两个：声明依赖、解析冲突。我挑几个主流的讲。

2.1 Android：Gradle

Gradle用Groovy或Kotlin DSL写配置。我个人现在全用Kotlin DSL，因为类型安全、IDE提示好。下面是一个典型的依赖声明：

// build.gradle.kts（Module级）
dependencies {
    implementation("com.example:my-sdk:1.2.3")
    implementation("com.example:common:2.0.0") {
        exclude(group = "com.excluded", module = "unused-lib")
    }
}

注意implementation和api的区别。如果你的SDK暴露了某些接口给外部，必须用api，否则调用方会报ClassNotFoundException。我曾经接手一个项目，把所有依赖都写成了implementation，结果单元测试跑不过，排查一上午才发现这个坑。

2.2 iOS：CocoaPods vs Swift Package Manager

CocoaPods依然是iOS SDk接入的主流。Podfile长这样：

platform :ios, '13.0'
target 'MyApp' do
  pod 'MySDK', '~> 3.1.0'
  pod 'NetworkingLib', :podspec => 'https://example.com/specs/NetworkingLib.podspec'
end

SPM（Swift Package Manager）算是苹果亲儿子，优势是无需安装工具、直接集成到Xcode。但有些老SDK只提供CocoaPods版本。我的建议是：优先用SPM，如果SDK只支持CocoaPods再用CocoaPods。注意两者不能混用同一库，否则会符号冲突。

2.3 Maven（Java/Kotlin后端SDK）

Maven用pom.xml声明依赖，适用于服务端SDK。示例如下：

<dependency>
    <groupId>com.example</groupId>
    <artifactId>server-sdk</artifactId>
    <version>2.3.0</version>
</dependency>

Maven的依赖传递规则比较严格，我提醒你注意scope。如果SDK引入了compile范围的公共库，你的项目可能会无意中继承它，导致版本冲突。我习惯在dependencyManagement里统一锁定版本。

3. 版本号管理：你的SDK依赖到底用了哪个版本？

版本号管理是环境准备里最容易被忽视的环节。你想想看，同一个库在开发机器和CI上拉到的版本不一样，这种问题有多难查？

目前业界主流是语义化版本控制（SemVer），格式：主版本.次版本.补丁。例如2.3.1。我习惯的规则：

• 补丁号变化：bug修复，兼容性不变。可以自动升级（如～3.1.0）。
• 次版本号变化：新增功能，向后兼容。建议用^3.1.0锁定次版本下限。
• 主版本号变化：破坏性更新。必须显式指定精确版本。

但在实际项目中，我遇到过因为依赖范围写得太宽松导致线上事故的情况。比如Gradle里写1.0.+，结果第三方SDK偷偷发了个1.0.2，改动了接口签名，编译时没问题，运行时直接崩溃。从那以后，我所有项目都用精确版本号，配合gradle.lockfile或Podfile.lock锁定依赖树。

4. 环境准备知识图谱

下面我用一张图把上面的知识点串起来，方便你对照排查：

5. 实战建议：搭建一个可复用的环境脚本

我每次新项目都会写一个 setup.sh（或 setup.ps1），把环境检查和依赖安装自动化。核心逻辑：

1. 检测必要工具是否存在（java, gradle, pod, xcodebuild 等）。
2. 版本号是否满足最小要求。
3. 如果不符合，打印出下载链接或安装命令。
4. 运行 gradle wrapper --gradle-version 8.5 统一Gradle版本。
5. 最后执行 pod install --repo-update 或 swift package resolve。

这样新成员加入，只需要跑一遍脚本，环境就对齐了。省心，也省了沟通成本。