📚 课程目录第3章 SDK集成第一步

第3章：SDK集成第一步：导入SDK文件、配置Build文件、检查签名与证书

说实话，我见过太多开发者——包括我自己早期也翻过车——一上来就急着写代码调接口，结果卡在编译报错上。后来我才明白，集成SDK的第一步如果没走稳，后面全是坑。这一章我就把几个最容易出问题的地方掰开揉碎讲清楚。

3.1 导入SDK文件——别小看这一步

SDK文件通常以 .jar、.aar（Android）、.framework 或 .xcframework（iOS）的形式给出。怎么导入？两种主流方式：手动拖入和依赖管理工具自动拉取。

方式	适用场景	常见坑
手动拖入	内网开发、无包管理工具	文件遗漏、路径不对
依赖管理（Gradle / CocoaPods / SPM）	团队协作、版本自动更新	版本号写错 / 仓库没配 / 缓存未清

我个人习惯优先用依赖管理。你想想看，手动拖进去之后，万一SDK升级，你又要重新拖一遍，容易漏。而且手动导入时很容易忘了把 .aar 放进 libs 目录或者忘记在 build.gradle 里加 flatDir。

  经验总结：不管是哪种方式，导入后第一件事是检查项目文件树。我曾在项目中遇到过队友把 .framework 只拖到项目目录却没加到 Target 的 Embedded Binaries 里，结果运行时直接崩溃。

// Android – 手动导入示例（build.gradle 需配置 flatDir）
android {
    ...
    repositories {
        flatDir { dirs 'libs' }
    }
}
dependencies {
    implementation fileTree(dir: 'libs', include: ['*.aar', '*.jar'])
}

// iOS – CocoaPods 自动导入
pod 'SomeSDK', '~> 3.2.0'

3.2 配置Build文件——核心参数别写错

导入文件只是第一步。接下来你要告诉编译器怎么用它。这里常常出现「编译通过但运行时闪退」的情况，原因多半是配置参数没写对。

3.2.1 Android：minSdkVersion / targetSdkVersion / compileSdkVersion

minSdkVersion 必须 ≤ SDK 要求的最低版本。我见过有人设高了，低版本手机直接无法安装。
compileSdkVersion 最好用最新稳定版，否则可能不兼容SDK里引用的新API。
targetSdkVersion 决定系统适配行为。别随便改低，否则会被 Play Store 警告。

曾经有个项目，因为 compileSdkVersion 设成 29，而SDK内部用了30才有的类，编译不报错但运行到某处直接抛 NoClassDefFoundError。排查了整整一天才发现是版本问题。

3.2.2 iOS：Build Settings 里的 Mach-O Type / Enable Bitcode / Other Linker Flags

大部分 SDK 要求 Mach-O Type 设为 Dynamic Library 或 Static Library，具体看文档。
Enable Bitcode：如果你集成的 SDK 不支持 Bitcode，必须把它关掉。我早期吃过亏，Xcode 编译通过但 Archive 时报错。
Other Linker Flags：经常需要加 -ObjC 或 -all_load，否则 Category 方法加载不上，运行时闪退。

// iOS – 在 Podfile 里添加
post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['GCC_OPTIMIZATION_LEVEL'] = '0' // 调试时可以关掉优化
    end
  end
end

3.3 检查签名与证书——集成最后一道鬼门关

文件导入了，build配置对了，编译通过。结果一安装到真机上又崩？别慌，多半是签名或证书问题。

说白了，签名是App的身份证。SDK如果做了代码保护或使用了系统级权限，会对你App的签名做校验。不匹配就拒绝工作。

3.3.1 Android：签名文件（.jks / .keystore）和 SHA1

一定要区分 debug签名 和 release签名。很多SDK的测试环境只认debug签名的SHA1，线上环境只认release。如果你在debug包上跑线上签名的KEY，回调永远不触发。
我建议在 build.gradle 里明确配置签名信息，避免混淆。

android {
    signingConfigs {
        debug { storeFile file("debug.keystore") }
        release {
            storeFile file("release.jks")
            storePassword "xxx"
            keyAlias "xxx"
            keyPassword "xxx"
        }
    }
    buildTypes {
        debug { signingConfig signingConfigs.debug }
        release {
            signingConfig signingConfigs.release
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }
}

一个小技巧：在集成阶段先用 debug 包调试，等接入无误再切 release。我曾用混淆后的 release 包定位问题，日志被混淆得一塌糊涂，自讨苦吃。

3.3.2 iOS：Provisioning Profile、App ID、Entitlements

App ID 必须和SDK后台配置的包名（Bundle Identifier）完全一致，大小写敏感。
如果SDK需要 Push Notifications 或 App Groups，你必须在 .entitlements 里开启，否则证书校验通过但功能不生效。
团队多人协作时，每个人本地的开发证书不同，记得在 Apple Developer Center 里添加所有开发者的设备 UDID。

我曾经接手一个项目，集成了某个支付SDK，测试环境一切正常，上线第二天发现部分用户无法唤起支付。查到最后发现是 release 证书的 Subject 里带了中文乱码（环境迁移时拷贝出错）。证书校验失败，SDK 直接拒绝了服务。

3.4 本章知识体系总览

下面这张图把三步走的关键流程串起来了。你可以当作集成前的自检清单。

嗯，这三步看着简单，但每个环节都有值得反复验证的地方。我的经验是：不要一次性把所有文件都配好再编译。每做完一小步就编译跑一次，出了问题能立刻定位到是哪个环节。集成SDK就像搭积木，底座稳了，上面的对接才敢放心做。你接下来就可以开始调接口了。