SDK 集成方式对比：手动集成 vs 包管理器

做 SDK 集成，第一件事就是选方案。选对了，后面省很多事；选错了……嗯，我吃过不少苦头。今天咱们把四种主流方式掰开揉碎聊一聊：手动集成、CocoaPods / Swift Package Manager、Gradle / Maven、npm / yarn。

手动集成——最原始，也最可控

说白了，就是把 SDK 的二进制文件（.a、.framework、.jar、.aar）或源码直接拖进项目。我早年做 iOS 开发时，碰到一个需要改底层的蓝牙 SDK，对方只提供了 .a 文件加一堆头文件，没法用 CocoaPods，只能手动拖。

优点很明显：

• 完全掌控集成过程，不依赖任何工具。
• 适合内部自研 SDK 或极度定制的第三方库。
• 没有版本冲突的“黑盒”风险。

缺点也更明显：

• 升级换版本——手动替换文件，容易漏掉依赖。
• 团队协作时，每个人本地环境不一致，集成结果可能不同。
• 无法自动处理传递依赖，比如 SDK A 依赖 B，B 依赖 C，你得一个个补。

CocoaPods / Swift Package Manager——iOS 生态的左右手

iOS 开发，这俩是绕不开的。CocoaPods 老牌，SPM 是 Apple 亲儿子。怎么选？我的经验是：能用 SPM 就用 SPM，但别太激进。

对比项	CocoaPods	Swift Package Manager
集成方式	Podfile + pod install	Xcode 内点几下，或 Package.swift
版本管理	Podfile.lock 锁定	Package.resolved 锁定
对 Xcode 版本要求	无特殊要求	Xcode 11+，部分功能需更新
自定义	可通过 podspec 精细控制	有限，依赖 Swift 模块
第三方库支持	极多，几乎覆盖所有	主流库基本覆盖，小库可能缺失

CocoaPods 的项目，我建议至少用 1.11+，否则插件兼容性有坑。SPM 的坑在于——有些 SDK 在 SPM 下会丢失资源文件（图片、bundle），你想想看，跑起来 UI 裂了，多尴尬。

Gradle / Maven——Android 与 Java 世界的标准答案

Android 这边，Gradle 是官方钦定。Maven 则是后台 Java 服务的老牌选择。两者本质上都是声明式依赖管理。

Android 集成 SDK 的真实流程通常是：

1. 在项目级 build.gradle 添加仓库（mavenCentral / jcenter 已凉，现在用 mavenCentral 或 google()）。
2. 在模块级 build.gradle 的 dependencies 里写一行 implementation 语句。
3. sync，等着 Gradle 把依赖树拉下来。

// 项目级 build.gradle
allprojects {
    repositories {
        google()
        mavenCentral()
        // 私有仓库
        maven { url 'https://my-sdk-repo.com/releases' }
    }
}

// 模块级 build.gradle
dependencies {
    implementation 'com.example:awesome-sdk:2.1.0'
}

这样做的好处是：传递依赖自动解析，版本冲突 Gradle 会报错或通过依赖约束处理。但坏处是——一个项目十几个模块，每个模块各自声明版本，稍不注意就出现“依赖地狱”。

npm / yarn——前端与 Node 开发的基石

前端 SDK 集成，npm 或 yarn 是标配。同样是把依赖写进 package.json，然后运行 install 命令。但这里有个微妙区别：npm 的扁平化策略 vs yarn 的确定性 lock 文件。

特性	npm	yarn
安装速度	v7+ 有改进，但不如 yarn	利用并行下载，快
lock 文件	package-lock.json（自动生成）	yarn.lock（自动生成）
离线缓存	有	更强，离线安装体验好
workspace 支持	有，但配置稍复杂	原生 mono-repo 解决方案

我个人的观点是：团队统一就行。npm 和 yarn 的功能重叠度超过 95%，别因为“yarn 比 npm 快”就强制迁移，迁移成本往往比那几秒安装时间高得多。

怎么选？——一张流程图搞定

流程图里没画前端的 npm / yarn，因为那是另一个生态。但逻辑类似：先确认 SDK 是否支持包管理器，支持就用，不支持再考虑手动。前端世界里，绝大多数 SDK 都发布在 npm 上，所以默认选 npm 或 yarn 就行，只有极少量闭源 SDK 要手动复制 .min.js 文件。

避坑总结——我踩过的那些雷

• 手动集成一定要写集成文档。不要口头交代，否则离职交接时就是噩梦。
• CocoaPods 的 use_frameworks! 如果你同时有 Swift 和 ObjC 的 Pod，不加这个会编译不过。但加了之后可能影响链接速度——这在旧项目迁移时尤为明显。
• SPM 的资源文件坑。有些 SDK 的图片、JSON 配置文件没有被正确打包进 framework bundle，运行时找不到。我的做法是：集成后第一时间跑 UI 快照测试，看资源是否加载正常。
• Gradle 的 dependencyInsight 命令 比看 build.gradle 好用十倍。遇到依赖冲突，先跑 ./gradlew :app:dependencyInsight --configuration releaseRuntimeClasspath --dependency xxx。
• npm 和 yarn 不要混用。一个项目里 lock 文件只能有一种，混用会导致版本不定。我见过有人开始用 yarn，后来同事用 npm install 把 yarn.lock 删了，结果上线后 SDK 版本错乱。