conti-retail-app/app/ios/FLAVORS.md

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 里把

   <key>CFBundleDisplayName</key>
   <string>Retail</string>
   

   改成

   <key>CFBundleDisplayName</key>
   <string>$(APP_DISPLAY_NAME)</string>
   

   改完必须先做完第 3 步：APP_DISPLAY_NAME 只在三份 flavor xcconfig 里 定义，没接上就是空的桌面名。

6. 验证：

   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 看不出关系。