# iOS flavor 手工配置步骤

**这一步必须在 macOS + Xcode 上做，命令行做不到。** Xcode 的 Build
Configuration 和 Scheme 存在 `Runner.xcodeproj/project.pbxproj` 里，那是一份
Xcode 自己维护的二进制风格文本，手写会在下一次 Xcode 打开时被改乱，出的问题
（"某个 target 的某个配置莫名其妙丢了"）极难排查。

所以这个仓库只提供三份 `.xcconfig`（`ios/Flutter/{Dev,Uat,Prod}.xcconfig`），
剩下的连线由第一个拿到 Mac 的人做一次，之后进 git。

> 08-build-flavors.md 已经把 iOS 侧列为**头号阻塞项**——目前团队没有可用的
> Mac 构建机，Apple 开发者账号也未确认。在那之前 iOS 只能跑默认配置。

## 步骤

1. 打开 `app/ios/Runner.xcworkspace`（不是 `.xcodeproj`）。

2. 选中项目 → **Info** → **Configurations**。此时应该有 `Debug` / `Release` /
   `Profile` 三条。对每一条点 `+` → **Duplicate ... Configuration**，复制成：

   | 原 | 复制为 |
   |---|---|
   | Debug | `Debug-dev`、`Debug-uat`、`Debug-prod` |
   | Release | `Release-dev`、`Release-uat`、`Release-prod` |
   | Profile | `Profile-dev`、`Profile-uat`、`Profile-prod` |

   一共 9 条。**名字必须完全是 `<原名>-<flavor>`**：`flutter run --flavor dev`
   就是靠这个命名约定找配置的，写成 `Debug-Dev` 都不行。

   做完之后把原来的 `Debug` / `Release` / `Profile` 删掉。

3. 每条配置的 Runner target 那一列，选对应的 xcconfig：
   `*-dev` → `Flutter/Dev.xcconfig`，`*-uat` → `Flutter/Uat.xcconfig`，
   `*-prod` → `Flutter/Prod.xcconfig`。

   > 注意：Flutter 生成的 `Debug.xcconfig` / `Release.xcconfig` 里
   > `#include "Generated.xcconfig"` 不能丢。三份 flavor 配置需要在开头补上
   > `#include "Debug.xcconfig"`（或 `Release.xcconfig`）——`flutter build` 靠
   > `Generated.xcconfig` 传 `FLUTTER_TARGET` 等参数，丢了会构建失败且报错
   > 信息完全指不到这里。

4. **Product → Scheme → Manage Schemes**，把 `Runner` 复制成 `dev` / `uat` /
   `prod` 三个 Scheme（名字就是 flavor 名），各自 Edit Scheme：
   - Run → Build Configuration → `Debug-<flavor>`
   - Profile → `Profile-<flavor>`
   - Archive → `Release-<flavor>`
   - 三个 Scheme 都要勾 **Shared**，否则不进 git，只有你自己的机器上有。

5. `Runner/Info.plist` 里把
   ```xml
   <key>CFBundleDisplayName</key>
   <string>Retail</string>
   ```
   改成
   ```xml
   <key>CFBundleDisplayName</key>
   <string>$(APP_DISPLAY_NAME)</string>
   ```
   **改完必须先做完第 3 步**：`APP_DISPLAY_NAME` 只在三份 flavor xcconfig 里
   定义，没接上就是空的桌面名。

6. 验证：
   ```bash
   cd app
   flutter build ios --flavor dev -t lib/main_dev.dart --dart-define-from-file=env/dev.json
   ```
   三个 flavor 各跑一次，确认桌面上能同时装下三个图标、名字不同。

## 已知的坑

- **CocoaPods 和 flavor 无关**：`Podfile` 不需要改，pod 是按 target 装的，
  不是按 configuration。但新增 configuration 后要跑一次 `pod install`，否则
  会报 `Unable to find a configuration named 'Debug-dev'`。
- **`--flavor` 和 `-t` 必须同时给**。只给 `--flavor dev` 会用默认的
  `lib/main.dart`——这个文件在本仓库里**不存在**（入口是 `main_dev.dart`），
  报错信息是找不到文件，和 flavor 看不出关系。