docs: 新增完整文档体系（setup-project / setup-android / setup-ios / CLAUDE.md）

2026-05-14 13:04:51 +08:00
parent bb07828234
commit a266323905
5 changed files with 1065 additions and 169 deletions
@@ -0,0 +1,243 @@
+# 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（脚手架默认不需要，但某些系统版本可能要求）。