📚 课程目录第4章 SDK集成方式

SDK 集成方式：手动集成、包管理器集成与集成验证

说实话，集成 SDK 这件事，新手和老手的差距往往不在写代码，而在「选对路子」。

我见过不少团队，明明只用三行命令就能搞定的事，非得去官网手动下载压缩包，然后跟路径、头文件、链接库死磕一下午。反过来，也有人盲目依赖包管理器，结果被隐性依赖炸得头皮发麻。

这一章咱们就把三种方式掰开揉碎讲清楚。我会把我踩过的坑、验证过的技巧都亮出来。

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

手动集成，说白了就是把 SDK 的文件直接拖进项目。适合以下场景：

包管理器不支持你的平台（比如某些 C 库只给了 .a 和 .h）
你公司的网络策略禁止访问外网仓库
你只需要 SDK 的某个子模块，不想把整个包拖进来

iOS 端（手动集成示例）

1. 下载 SDK 的 .framework 或 .xcframework
2. 拖入 Xcode 项目的 "Frameworks, Libraries, and Embedded Content"
3. 设置 "Embed & Sign"
4. 在 Build Settings 中检查：
   - Framework Search Paths 指向 SDK 所在目录
   - Other Linker Flags 添加 -ObjC（如需要）

我曾经这样摔过跤： 忘记把 .bundle 资源文件也拖进 Target，结果 SDK 里的图片和 xib 全部加载失败。而且 Xcode 不会给你任何编译报错——运行到那个页面才崩。所以手动集成时，请务必检查 .bundle 是否在 Copy Bundle Resources 里。

Android 端（手动集成示例）

1. 把 .aar 或 .jar 文件复制到 libs/ 目录
2. 在 app/build.gradle 中添加：
   implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar'])
3. 如果 SDK 有 JNI 库，检查 jniLibs/ 目录下的 so 文件是否按 ABI 放好

Web 端（手动集成示例）

<script src="path/to/sdk.min.js"></script>
<!-- 或使用 ES Module 方式 -->
<script type="module">
  import sdk from './sdk.esm.js';
</script>

我个人的一个小技巧：手动集成后，先在空白工程里编译一次。因为有时候 SDK 依赖的系统库（如 CoreBluetooth、ARKit）你忘了加，空白工程最容易暴露出缺失链接。

2. 包管理器集成——省心，但别太放心

现在的主流做法都用包管理器。CocoaPods、Gradle、npm……你想想看，一行命令拉下来，连依赖树都帮你搞定。确实爽。

CocoaPods（iOS）

# Podfile
platform :ios, '13.0'
target 'YourApp' do
  pod 'SomeSDK', '~> 2.1.0'
end

# 执行集成
pod install

注意： 从此以后必须用 .xcworkspace 打开项目，千万别再点 .xcodeproj。

Gradle（Android）

// 项目级 build.gradle
allprojects {
  repositories {
    mavenCentral()
    // 有些 SDK 放在 JitPack
    maven { url 'https://jitpack.io' }
  }
}

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

npm（Web/React Native）

npm install some-sdk@^2.1.0
# 或
yarn add some-sdk@^2.1.0

  避坑指南（我亲身经历）：
  版本冲突： 有一次我要集成两个 SDK，它们依赖了同一个底层库的不同大版本，结果 CocoaPods 直接报 dependency conflict。解决办法是查看 pod spec，手动统一版本号。
Podfile.lock 要提交到 Git： 很多人觉得它自动生成就忽略了。记得有一次团队里有人 pod install 后版本漂移，导致所有人本地环境不一致——排查了整整一天。

3. 集成验证——必要的「体检」

集成完了，不验证一把？别等到上线用户反馈才懵。我建议做完以下三步：

编译通过 ≠ 集成成功
至少调一个 API 做功能测试
检查资源文件和权限声明

编译检查

跑一遍 clean build，确保头文件能正确处理、链接库没有 Undefined symbols。

API 调用测试（以初始化为例）

// iOS
#import <SDK/SDK.h>
[SomeSDK startWithAppKey:@"your_key"];

// Android
import com.example.sdk.SDKManager;
SDKManager.init(this, "your_key");

// Web
sdk.initialize({ : 'your_key' });

如果编译报错说找不到类或方法 —— 八成是符号暴露范围或者链接顺序有问题。

资源与权限清单

平台	检查项目	常见遗漏
iOS	Info.plist（NSCameraUsageDescription 等）	定位、相机权限描述
Android	AndroidManifest.xml（permission、activity）	网络权限、SDK 自带的 Activity 声明
Web	Content Security Policy	script-src 放行 CDN 域名

另一个血泪教训： 曾经集成了一个视频渲染 SDK，手动折腾了三个小时，编译通过、初始化成功，但运行画面黑屏。最后发现是忘了在 Info.plist 里加 Camera Usage Description 字符串——iOS 13 以后不给权限描述直接闪退。所以 权限声明这块，SDK 文档里哪怕提了一句，你都别跳过。

4. 集成决策流程图

下面这张图是我总结的选择套路：

我个人习惯： 除非团队有严格的安全审计要求（比如 SDK 来自非官方渠道），否则我首选包管理器。不是因为懒，而是它能在 pod outdated 或 npm audit 时主动通知你版本漏洞。手动集成做不到这点。

最后多说一句：集成验证不是一次性的。每次升级 SDK 版本或修改项目配置后，最好重新跑一遍「编译 + 基础 API 调用」流程。嗯，别嫌麻烦——你在本地花十分钟，总比线上出问题后花两小时强。