iOS 构建体系与 CocoaPods/SwiftPM 依赖管理

回到总览：构建与发布工程相关模块：Android Gradle/AGP 构建生命周期 · Flutter iOS 产物（并入 07，待补）

一句话定义

iOS 构建 = xcodebuild 驱动的工程/scheme 编译 + 依赖管理（CocoaPods / SwiftPM）+ 签名与分发；它强绑定 Xcode 版本、签名证书、Provisioning Profile 与本地 DerivedData 缓存，因此“本地能编、CI 编不过”是高频事故。

代码索引

主题	Lab 说明	源码
iOS/Fastlane 边界收口样板	flutter-host-fastlane-boundary-demo	Fastfile

为什么需要

为什么 iOS 项目“换台机器就编译不过”？
- 一句话答：构建强依赖 Xcode 版本、签名证书/Provisioning Profile 与本地 DerivedData 及 Pod 缓存，这些环境不随代码锁版本，任何一项不一致就失败（详见下文 §底层机制.3）。
CocoaPods 和 SwiftPM 怎么选？
- 一句话答：CocoaPods 用独立 Pods 工程 + workspace、Podfile.lock 锁版本、生态最成熟但中心化；SwiftPM 是苹果官方、与 Xcode 原生集成、去中心化（直接引 Git），但对二进制分发/某些插件场景支持弱（见「相近概念对比」）。
为什么 archive 比普通 build 慢很多？
- 一句话答：archive 走 release 配置、做代码签名、导出 .xcarchive 并最终产 .ipa，比调试期 build 多出签名与打包导出步骤（见 §底层机制.4）。

底层机制

1. xcodebuild 构建流程

概念：scheme 决定编译哪个 target、configuration(Debug/Release) 决定优化与签名；xcodebuild 是命令行入口，fastlane gym 是其封装。

2. 依赖解析：CocoaPods vs SwiftPM

ruby

# Podfile（CocoaPods）
target 'MyApp' do
  pod 'Alamofire', '~> 5.8'
end
# 执行 pod install 后生成 Pods/ 工程与 Podfile.lock

swift

// Package.swift（SwiftPM）
dependencies: [
  .package(url: "https://github.com/Alamofire/Alamofire.git", .upToNextMajor(from: "5.8.0"))
]
// 生成 Package.resolved 锁定版本

可能输出

$ pod install
Analyzing dependencies
Downloading dependencies
Generating Pods project
Integrating client project

预期现象：CocoaPods 在每次 pod install 时按 Podfile.lock 还原版本并重建 Pods 工程；SwiftPM 按 Package.resolved 还原，依赖直接编译进主工程，无独立 workspace 注入。
观察重点：Podfile.lock / Package.resolved 必须提交到仓库，否则协作者/CI 可能拉到不同版本导致行为漂移。

3. 签名三件套：证书 / Provisioning Profile / Entitlements

Certificate（开发/分发）：标识开发者身份，存于钥匙串。
Provisioning Profile：把证书、App ID、设备 UDID（开发版）绑定，授权哪台设备能装。
Entitlements：声明 App 需要的特殊能力（推送、Keychain 分组等）。
任一项过期或与 bundle id 不匹配，xcodebuild 即报 No matching provisioning profiles found。

4. 产物链路：.app → .xcarchive → .ipa

.app：编译链接后的应用包（未签名或开发签名）。
.xcarchive：archive 产物，含签名后的 .app 与 dSYM 符号表。
.ipa：最终分发包（实质是 zip，内含 .app + 签名物料）。

5. 当前仓库对 iOS 的“最小诚实落地”是什么

对应 Lab：flutter-host-fastlane-boundary-demo

这次没有新建 labs/ios/host，不是偷懒，而是当前仓库更适合一个边界清楚的最小样板：

已有 labs/flutter/host/ios/Runner，足以承载 Flutter host 的 iOS 工程骨架。
可以在 Fastfile 里调起：
- flutter build ios --simulator --debug --no-codesign
但不能假装已经具备：
- xcodebuild archive
- exportOptionsPlist
- 真实证书/Profile 注入
- upload_to_testflight

ruby

lane :host_ios_build_dry_run do
  sh("flutter --version")
  sh("flutter pub get", chdir: "../../flutter/host")
  sh("flutter build ios --simulator --debug --no-codesign", chdir: "../../flutter/host")
end

可能输出

text

$ fastlane ios host_ios_build_dry_run
$ flutter build ios --simulator --debug --no-codesign

预期现象：在具备 Flutter+iOS 工具链的 macOS 机器上，能验证 Flutter host 的 iOS 工程能否被 Fastlane 正确调起并成功完成 simulator debug 构建。
观察重点：这条样板验证的是“构建链路入口”和“lane 组织方式”，不是“真实发布能力”。

Android / Flutter / Web / Backend 对照

维度	iOS (xcodebuild)	Android (Gradle/AGP)	Flutter (flutter build ios)	Web (Webpack/Vite)
构建入口	`xcodebuild` / `gym`	`gradlew` / AGP	`flutter build ios`	`vite build` / `webpack`
依赖管理	CocoaPods / SwiftPM	implementation/api	pubspec + pub get	npm / pnpm
签名	证书 + Provisioning	keystore / jks	复用 Xcode 配置	无
产物	.ipa / .xcarchive	APK / AAB	Runner.app / Runner.ipa	静态资源
增量机制	DerivedData 缓存	up-to-date + Build Cache	热重载	HMR

常见场景

多 target / Framework：主 App + 多个动态/静态 Framework，Archive 时按 dependency 顺序编译。
CI 构建：用 xcodebuild archive 或 fastlane gym 在干净机器（macOS runner）上出包。
Catalyst / Mac 目标：同一份代码编译为 macOS App，签名体系共用但 profile 类型不同。

常见误配、事故后果与排障

1. 事故：Podfile.lock 没提交，CI 拉到新版三方库编译失败

误配原因：开发者本地 pod update 后只提交了 Podfile，没提交 Podfile.lock。
后果：CI 重新解析到不兼容的新版本，编译报错或运行时崩溃。
排障与修法：把 Podfile.lock（Package.resolved 同理）纳入版本控制；CI 用 pod install --deployment 禁止自动更新。

2. 误配：证书过期 / Provisioning Profile 不匹配

后果：xcodebuild 报 No matching provisioning profiles found 或上传被拒。
排障与修法：在开发者后台续期证书并重新下载 profile；CI 用 fastlane match 统一管理签名物料，避免每台机器各自导入。

3. 误配：模拟器(arm64/x86_64)与真机架构混淆

后果：Archive 选错 destination，真机安装报架构不支持。
排障与修法：Archive 必须用 generic iOS Device / Any iOS Device 而非模拟器；导出时按真机切片。

4. 误配：没有 Xcode / 签名环境，却把 demo 文档写得像“已可真实发版”

后果：后来的人会误判仓库已经具备完整 iOS 发布能力，真正接 CI 时才发现缺证书、缺 profile、缺 App Store Connect 权限。
排障与修法：像当前这样把“simulator + no-codesign”与“archive/export/upload”明确拆层，文档表达保持诚实。

相近概念对比

CocoaPods vs SwiftPM：前者中心化仓库、workspace 注入、生态全；后者官方原生、去中心化、与 Xcode 深度整合但对二进制/插件弱。
CocoaPods vs Carthage：Carthage 只预编译 framework 不修改工程，侵入更小但集成更手工。
Debug vs Release：Release 开优化、去断言、需发布签名，构建更慢但产物可上架。
.app vs .ipa vs .xcarchive：开发包 / 最终分发包 / 归档（含 dSYM）。

对应实验

Lab	说明	源码
flutter-host-fastlane-boundary-demo	复用现有 Flutter host，验证 Fastlane 能否调起 iOS no-codesign 构建并明确签名边界（与文首「代码索引」一致）	Fastfile

复习检查题

为什么 iOS 构建对 Xcode 版本和签名环境如此敏感，而 Android Gradle 构建相对没那么“挑机器”？答：iOS 构建依赖 Xcode 工具链版本、本地钥匙串证书与 Provisioning Profile，这些环境状态不随代码锁版本；Android 构建主要依赖 Gradle/AGP 版本（写进 gradle-wrapper 与 build.gradle），环境差异被构建脚本吸收，故更可移植。
CocoaPods 的 Podfile.lock 为什么必须提交？答：它锁定了每个三方库的精确版本，保证协作者与 CI 解析到完全一致的依赖；不提交则每次可能解析到不同版本，引发编译或行为漂移。
.xcarchive 与 .ipa 的关系？答：archive 生成 .xcarchive（含签名 .app 与 dSYM 符号表），再 export 为 .ipa 分发包；dSYM 用于线上崩溃符号化。

速记

三绑定：Xcode 版本 + 证书/Profile + DerivedData，缺一不可。
两锁文件：Podfile.lock / Package.resolved 必提交。
仓库边界：当前只验证到 Flutter host iOS 的 no-codesign/simulator 构建，不伪造 archive/upload 链路。
产物链：.app → .xcarchive(含 dSYM) → .ipa。

iOS 构建体系与 CocoaPods/SwiftPM 依赖管理 ​

一句话定义 ​

代码索引 ​

为什么需要 ​

底层机制 ​

1. xcodebuild 构建流程 ​

2. 依赖解析：CocoaPods vs SwiftPM ​

3. 签名三件套：证书 / Provisioning Profile / Entitlements ​

4. 产物链路：.app → .xcarchive → .ipa ​

5. 当前仓库对 iOS 的“最小诚实落地”是什么 ​

Android / Flutter / Web / Backend 对照 ​

常见场景 ​

常见误配、事故后果与排障 ​

1. 事故：Podfile.lock 没提交，CI 拉到新版三方库编译失败 ​

2. 误配：证书过期 / Provisioning Profile 不匹配 ​

3. 误配：模拟器(arm64/x86_64)与真机架构混淆 ​

4. 误配：没有 Xcode / 签名环境，却把 demo 文档写得像“已可真实发版” ​

相近概念对比 ​

对应实验 ​

复习检查题 ​

速记 ​