flutter-template/docs/setup-ios.md

iOS 配置指南

本文档覆盖 iOS 端从 CocoaPods 安装到 Archive 发布所需的全部配置步骤。

平台要求：macOS 系统 + Xcode 16+。Windows / Linux 无法进行 iOS 开发。

---

前提

• macOS 14 (Sonoma) 或更高版本
• Xcode 16.0（从 App Store 安装，包含 iOS 18 SDK）
• CocoaPods 1.15+：sudo gem install cocoapods
• Apple Developer 账户（真机运行需 Free 账户，发布需 Paid 账户 $99/年）
• 已完成 setup-project.md 的 Step 1–4

---

1. 安装 CocoaPods 依赖

cd ios
pod install
cd ..

首次执行会拉取依赖，耗时 5–15 分钟（取决于网络）。成功后生成：

• ios/Pods/ 目录（gitignore，不提交）
• ios/Podfile.lock（版本锁定，应提交）

如果 pod install 卡住，检查 CocoaPods 源：

pod repo update

---

2. 验证基础构建

# 无签名编译验证（不需要 Apple 账户）
flutter build ios --no-codesign --flavor dev \
  --dart-define-from-file=dart-defines/dev.json

# 预期输出：
# ✓ Built build/ios/iphoneos/Runner.app

---

3. 配置 Bundle Identifier

打开 Xcode（必须通过 .xcworkspace 打开）：

open ios/Runner.xcworkspace

在 Xcode 中：

1. 左侧导航选择 Runner 项目
2. 选择 Runner Target → General 选项卡
3. Bundle Identifier 改为业务项目实际 ID：

Build Configuration	Bundle ID
Debug（dev 开发调试）	com.your_company.your_app.dev
Debug-staging	com.your_company.your_app.staging
Release（prod 发布）	com.your_company.your_app

脚手架默认使用单个 Bundle ID，Flavor 区分由 xcconfig 控制。若需要三个独立 Bundle ID，在 ios/Flutter/flavors/ 的 xcconfig 文件中添加 PRODUCT_BUNDLE_IDENTIFIER 覆盖。

---

4. 配置 Xcode Build Configuration 和 Scheme

脚手架已在 ios/Flutter/flavors/ 中提供三套 xcconfig：

文件	对应 Flavor
dev.xcconfig	开发包（Debug-dev）
staging.xcconfig	测试包（Debug-staging / Release-staging）
prod.xcconfig	正式包（Release）

关联 xcconfig 到 Build Configuration

1. Xcode → Runner 项目 → Info 选项卡 → Configurations
2. 展开每个 Configuration，点击 Runner 旁的下拉：

Configuration 名称	关联 xcconfig
Debug	Flutter/flavors/dev.xcconfig
Release	Flutter/flavors/prod.xcconfig
Profile	Flutter/flavors/prod.xcconfig

若需要 staging 独立 Configuration，在此添加 Debug-staging / Release-staging。

添加 dev / staging Scheme（推荐）

1. Xcode → Product → Scheme → Manage Schemes
2. 复制 Runner Scheme，重命名为 dev
3. 编辑 dev Scheme：
   • Build Configuration（Run）→ Debug
   • 在 Arguments 中确认无硬编码的 dart-defines（Flutter 通过 --dart-define-from-file 注入）

---

5. 配置代码签名

5.1 自动签名（开发调试，推荐）

1. Xcode → Runner Target → Signing & Capabilities
2. 勾选 Automatically manage signing
3. Team 选择你的 Apple Developer 账户
4. Xcode 会自动创建 Provisioning Profile 和 Signing Certificate

5.2 手动签名（CI/CD 或发布版）

1. 在 Apple Developer Portal 创建：
   • Distribution Certificate（可签发 App Store / Ad Hoc 包）
   • App ID（对应 Bundle Identifier）
   • Provisioning Profile（Distribution 类型）
2. 下载 .mobileprovision 文件，双击安装到 Xcode
3. 取消勾选 Automatically manage signing
4. 选择对应的 Signing Certificate 和 Provisioning Profile

---

6. 真机运行

# 确认设备已连接
flutter devices

# 运行到真机（dev 包）
flutter run --flavor dev \
  --dart-define-from-file=dart-defines/dev.json \
  -d <device-id>

# 或通过 Xcode 直接运行（选择 dev Scheme + 目标设备）

首次在设备上运行需要：

• 设备 → 设置 → 通用 → VPN 与设备管理 → 信任开发者证书

---

7. 构建 TestFlight / App Store Archive

# 1. 确保 prod.json 已配置正确
cat dart-defines/prod.json

# 2. 构建 iOS Release
flutter build ios --flavor prod --release \
  --dart-define-from-file=dart-defines/prod.json

# 3. 在 Xcode 中 Archive（需要 Distribution Certificate）
# Product → Archive → Distribute App → App Store Connect

CI/CD Archive（Fastlane 示例）

# Fastfile
lane :beta do
  build_app(
    workspace: "ios/Runner.xcworkspace",
    scheme: "Runner",                    # 或 prod scheme
    configuration: "Release",
    export_method: "app-store",
    export_options: {
      provisioningProfiles: {
        "com.your_company.your_app" => "Your App Store Profile"
      }
    }
  )
  upload_to_testflight
end

---

8. 常用 xcconfig 字段说明

ios/Flutter/flavors/dev.xcconfig：

// 覆盖 Display Name（桌面图标显示的应用名）
DISPLAY_NAME=YourApp Dev

// 覆盖 Bundle ID（若三包使用不同 ID）
// PRODUCT_BUNDLE_IDENTIFIER=com.your_company.your_app.dev

// 覆盖 App Icon（若三包使用不同图标）
// ASSETCATALOG_COMPILER_APPICON_NAME=AppIconDev

---

9. 最低 iOS 版本

Podfile 已锁定 iOS 15.0：

platform :ios, '15.0'

若业务需要支持更低版本，修改此行并运行 pod install。同时在 Xcode → Target → Deployment Info → iOS Deployment Target 同步修改。

---

常见问题

pod install 报 CocoaPods could not find compatible versions

pod repo update          # 更新本地 CocoaPods 源
pod install --repo-update

Xcode 打开 .xcodeproj 而非 .xcworkspace

必须打开 .xcworkspace，否则 CocoaPods 的依赖不会加载：

open ios/Runner.xcworkspace   # ✓ 正确
# 不要 open ios/Runner.xcodeproj  ✗

真机运行报 Untrusted Developer

设备 → 设置 → 通用 → VPN 与设备管理 → 找到 Developer App → 信任。

Archive 失败，报 Provisioning profile doesn't include the entitlement

在 Apple Developer Portal 重新生成 Provisioning Profile（选中全部所需 Entitlements），重新下载安装。

Flutter build 报 The iOS deployment target is set to xxx, but the range of supported deployment targets is

更新 Podfile 中的 platform :ios 版本，运行 pod install，并在 Xcode Target → Deployment Info 同步修改。

模拟器运行正常，真机崩溃（SecureStorage 相关）

iOS 模拟器的 Keychain 行为与真机不同。确认 Xcode → Target → Signing & Capabilities → 已添加 Keychain Sharing Capability（脚手架默认不需要，但某些系统版本可能要求）。