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](setup-project.md) 的 Step 1–4

---

## 1. 安装 CocoaPods 依赖

```bash
cd ios
pod install
cd ..
```

首次执行会拉取依赖，耗时 5–15 分钟（取决于网络）。成功后生成：
- `ios/Pods/` 目录（gitignore，不提交）
- `ios/Podfile.lock`（版本锁定，**应提交**）

> 如果 `pod install` 卡住，检查 CocoaPods 源：
> ```bash
> pod repo update
> ```

---

## 2. 验证基础构建

```bash
# 无签名编译验证（不需要 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 打开**）：

```bash
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](https://developer.apple.com/account) 创建：
   - 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. 真机运行

```bash
# 确认设备已连接
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

```bash
# 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 示例）

```ruby
# 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`：

```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：

```ruby
platform :ios, '15.0'
```

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

---

## 常见问题

### `pod install` 报 `CocoaPods could not find compatible versions`

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

### Xcode 打开 `.xcodeproj` 而非 `.xcworkspace`

必须打开 `.xcworkspace`，否则 CocoaPods 的依赖不会加载：
```bash
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（脚手架默认不需要，但某些系统版本可能要求）。