app scaffold

2026-08-17 15:29:55 +08:00
commit 681688dfae
301 changed files with 18414 additions and 0 deletions
@@ -0,0 +1,76 @@
+# 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 看不出关系。