搭建开发环境——各平台SDK集成的前置条件与工程配置

说实话，开发环境搭不好，后面所有工作都是白忙。我见过太多团队急着跑Demo，结果卡在证书过期、CocoaPods版本不一致这类细节上，一查就是大半天。

本章我们就来捋一捋iOS、Android、Web三个平台，集成SDK之前必须搞定的那些前置条件和工程配置。我把它们拆成了三个独立的小节，你可以按平台来跳着读。

一、iOS 平台——Xcode 与包管理器的那些坑

我个人的习惯是，接到新SDK集成任务，先把Xcode和CocoaPods的版本锁定。为什么呢？因为我吃过亏——之前有个项目用Xcode 14.3编译的库，在Xcode 15上直接报了linker error，查了半天发现是新的LLVM ABI不兼容。

前置条件清单

• macOS 版本：至少 macOS 14.x（Sonoma），因为新版Xcode不支持老系统。嗯，这里要注意，部分第三方SDK最低要求是Xcode 15，那你就没法在12.x上跑了。
• Xcode 命令行工具：安装完后执行 xcode-select --install，确认xcrun、swiftc可用。
• 包管理器：CocoaPods (≥1.12)、Swift Package Manager (Xcode自带)、或 Carthage。我个人倾向SPM，因为不用操心Podfile。

工程配置的关键步骤

1. 创建或打开 Xcode 工程，确定 target 的 iOS Deployment Target ≥ SDK 的最低要求（比如 iOS 13.0）。
2. 集成方式选择：
   • 如果用 CocoaPods，在 Podfile 里写 pod 'YourSDK'，然后 pod install。
   • 如果用 SPM，Xcode → File → Add Package Dependencies → 输入仓库URL → Add to target。
   • 手动集成：下载 .xcframework 拖入项目，确保 Embed & Sign。
3. Info.plist 调整：很多SDK需要添加 NSAppTransportSecurity 允许 HTTP 请求，或者 NSLocationWhenInUseUsageDescription 等权限描述。
4. Build Settings 检查：Bitcode 是否关闭（iOS 14+ 已废弃），以及 Other Linker Flags 是否添加了 -ObjC（针对纯 OC 库）。

二、Android 平台——Gradle 版本与依赖管理的玄学

Android 的集成为什么感觉比 iOS 复杂？说白了，主要是 Gradle 的版本兼容性问题。你想想看，AGP、Gradle、Kotlin、compileSdk 四个版本需要相互匹配，稍微错一个就可能报错。

前置条件清单

工程配置步骤

1. 检查 gradle-wrapper.properties：确保 distributionUrl 指向的 Gradle 版本与 AGP 兼容。例如 AGP 8.2 需要 Gradle 8.2~8.4。
2. 在 build.gradle (module级) 添加依赖：

   dependencies {
       implementation 'com.example:sdk:1.2.3'
       // 如果需要传递依赖解析，使用 implementation 而非 api
   }

3. minSdkVersion 与 targetSdkVersion：我个人建议 minSdkVersion 设置为 21（Android 5.0），这样可以覆盖 95% 的设备。targetSdkVersion 紧跟 compileSdk。
4. ProGuard / R8 规则：在 proguard-rules.pro 里添加 SDK 的 keep 规则，防止混淆后调用失败。

   -keep class com.example.sdk.** { *; }
   -keepclassmembers class * { @com.example.sdk.annotation.Keep *; }

configurations.all {
    resolutionStrategy {
        force 'com.squareup.okhttp3:okhttp:4.12.0'
    }
}

三、Web 平台——Node.js 与模块打包的“暗流”

Web 端的 SDK 集成看似最简单——npm install 一下就行。但如果你的项目是个大龄 Angular 项目，或者用了奇葩的模块联邦机制，那就要格外小心了。

前置条件清单

• Node.js 版本： ≥ 18.x（建议使用 LTS 版本），npm ≥ 9.x。可以用 nvm 管理多版本。
• 包管理器：npm、yarn、pnpm 均可，但注意 lock 文件的兼容性。我习惯用 npm。
• 构建工具：Webpack 5、Vite、或 Rollup。不支持 ES Module 的 SDK 可能需要配置 CommonJS 兼容。

工程配置步骤

1. 初始化 package.json，执行 npm init。确保 name、version 不为空，且 main 或 module 字段指向入口文件。
2. 安装 SDK 包：

   npm install your-sdk-name --save

   如果是私有包，需要配置 .npmrc 或登录 npm registry。
3. 在项目中引入：

   import { YourSDKClient } from 'your-sdk-name';
   // 或者 CommonJS 语法：
   const { YourSDKClient } = require('your-sdk-name');

4. Polyfill 与浏览器兼容性：如果 SDK 用了某些 Node.js 核心模块（如 crypto、stream），需要在 Webpack 配置里 fallback：

   resolve: {
       fallback: {
           crypto: require.resolve('crypto-browserify'),
           stream: require.resolve('stream-browserify')
       }
   }

5. CSP（内容安全策略）对齐：检查 SDK 是否动态创建 <script> 或使用 eval()。如果有，需要调整你的 CSP 策略。

四、跨平台通用检查清单

不管哪个平台，你在跑第一个 Demo 之前，最好过一遍下面这张表：

五、验证环境是否搭对——一个最简单的“Hello SDK”

环境搭完，别急着写业务逻辑。先跑一个空壳集成，就调用 SDK 的初始化方法，不报错就算成功。

我曾经在项目中跳过这步，结果发现 SDK 依赖了一个旧版本的系统库，真机测试直接闪退。你想想看，要是等到集成完成后才发现，定位问题就更难了。