flutter-template/docs/setup-project.md

项目配置指南

阅读顺序建议：先跑起来（Step 1–2），再按需配置后续步骤。 Android / iOS 平台专属配置见 setup-android.md / setup-ios.md。

---

前提条件

工具	最低版本	说明
Flutter SDK	3.41.0	flutter.dev/get-started
Android Studio	Meerkat 2024.3	含 Android SDK API 34
Xcode	16.0	仅 iOS 开发需要（macOS 专属）
CocoaPods	1.15+	sudo gem install cocoapods

flutter doctor   # 确认 Android toolchain + Xcode 全绿后再继续

---

Step 1 — 克隆 + 安装依赖 + 代码生成

git clone https://gitea.example.com/your-org/your-project.git  # TODO: 替换真实地址
cd your-project

flutter pub get        # 拉取所有依赖（约 1 分钟）
make gen               # 生成 .g.dart / .freezed.dart（约 1 分钟）
make gen-i18n          # 生成 lib/i18n/strings.g.dart（秒级）

如果 make gen 报错，确认 dart 在 PATH 中：dart --version

---

Step 2 — 立即运行（无需后端）

dart-defines/dev.json 默认开启 Mock 模式（USE_MOCK=true），App 使用 assets/fixtures/ 下的预设 JSON 响应，不需要任何后端服务即可运行。

make run-dev

期望结果：

• ✅ App 启动，显示登录页（手机号 + SMS/密码双模式）
• ✅ 点击"发送验证码"→ 自动填入 123456（Mock 响应）
• ✅ 输入任意手机号 + 123456 登录 → 跳转 Home 占位页
• ✅ 进入 Dev Panel（Talker 日志面板可正常显示请求日志）

flutter analyze 输出约 103 条 info 提示，这是正常的（全为风格建议，0 errors）。

---

Step 3 — 填入 API 路径

编辑 lib/core/config/api_paths.dart，将所有空字符串替换为实际后端路径：

// 示例（sa-token 后端）
static const String authLoginSms  = '/sys/auth/sms-login';
static const String authLoginPwd  = '/sys/auth/password-login';
static const String authSmsSend   = '/sys/auth/send-sms';
static const String authLogout    = '/sys/auth/logout';
static const String authRefresh   = '/sys/auth/refresh-token';
static const String userProfile   = '/sys/user/profile';
static const String crashReport   = '/sys/crash-report';
static const String errorReport   = '/sys/error-report';
// ... 其余路径按业务填写

---

Step 4 — 配置环境变量（连接真实后端）

dart-defines 字段说明

JSON 键	作用	dev 默认	必须填写时机
ENV	环境名（dev/test/release）	dev	通常不改
API_BASE_URL	临时覆盖 baseUrl	空	见下方说明
USE_MOCK	开启 Mock 模式	true	连真实后端时改 false
INTERNAL_BUILD	显示 Dev Panel	true	通常不改
SENTRY_DSN	Sentry 上报地址	空	prod 上线前
PINNED_FINGERPRINTS	SSL 证书指纹	空	正式上线前
RSA_PUBLIC_KEY	密码加密公钥	空	登录加密时

方式 A：修改 api_config.dart（推荐，永久生效）

编辑 lib/core/config/api_config.dart：

return switch (Env.name) {
  'dev'     => 'http://192.168.1.100:8080',           // ← 改为 dev 服务器
  'test'    => 'https://staging.your-domain.com',     // ← 改为 staging 服务器
  'release' => 'https://api.your-domain.com',         // ← 改为生产服务器
  _         => 'http://192.168.1.100:8080',
};

同时将 dart-defines/dev.json 中的 USE_MOCK 改为 false。

方式 B：临时覆盖（调试私有环境）

flutter run --flavor dev \
  --dart-define-from-file=dart-defines/dev.json \
  --dart-define=API_BASE_URL=http://192.168.1.200:8080 \
  --dart-define=USE_MOCK=false

配置 RSA 公钥（密码加密）

若后端使用 RSA 加密传输密码，从后端获取公钥后填入各环境 JSON：

# 从 Java 后端 PEM 文件提取 Base64 DER（去掉 header/footer，合并为单行）
cat server-public.key | grep -v "BEGIN\|END" | tr -d '\n'

将结果填入 dart-defines/dev.json / staging.json / prod.json 的 RSA_PUBLIC_KEY 字段。

若后端不需要 RSA 加密，修改 auth_repository_impl.dart 的 loginWithPassword 方法，将明文密码直接传入（或使用 HTTPS 保护）。

配置 SSL 证书指纹（生产必须）

# 获取服务器证书 SHA-256 指纹
echo | openssl s_client -connect api.your-domain.com:443 2>/dev/null \
  | openssl x509 -fingerprint -sha256 -noout \
  | sed 's/SHA256 Fingerprint=//'

将结果填入 dart-defines/prod.json 的 PINNED_FINGERPRINTS 字段（多个指纹用逗号分隔）。

配置生产环境（prod.json）

cp dart-defines/prod.json.template dart-defines/prod.json
# 编辑 prod.json，填入 Sentry DSN / 证书指纹 / RSA 公钥

prod.json 已在 .gitignore 中，不会被提交。CI/CD 通过 secret 注入。

---

Step 5 — 修改包名（业务项目必须）

Android

android/app/build.gradle.kts → defaultConfig.applicationId：

defaultConfig {
    applicationId = "com.your_company.your_app"   // ← 修改
}
productFlavors {
    create("dev") {
        applicationIdSuffix = ".dev"
        resValue("string", "app_name", "YourApp Dev")  // ← 修改
    }
    create("staging") {
        applicationIdSuffix = ".staging"
        resValue("string", "app_name", "YourApp Beta") // ← 修改
    }
    create("prod") {
        resValue("string", "app_name", "YourApp")      // ← 修改
    }
}

iOS

打开 Xcode（必须用 .xcworkspace）：

open ios/Runner.xcworkspace

Runner Target → General → Bundle Identifier → 修改为实际 ID。

pubspec.yaml + Dart 导入路径

# pubspec.yaml
name: your_app_name   # ← 修改

批量替换代码中的 package 名：

# macOS / Linux
find lib -name "*.dart" -exec sed -i '' \
  's/package:sunny_mochi/package:your_app_name/g' {} \;

# Windows PowerShell
Get-ChildItem -Path lib -Recurse -Filter "*.dart" | ForEach-Object {
  (Get-Content $_.FullName) -replace 'sunny_mochi', 'your_app_name' |
  Set-Content $_.FullName
}

替换后运行 make gen 重新生成，确认 flutter analyze 无错误。

---

Step 6 — 平台专属配置

需求	文档
Android 签名 / Flavor 验证 / 发布包	setup-android.md
iOS Scheme / CocoaPods / 证书 / Archive	setup-ios.md

---

常见问题

症状	原因	解决
make gen 报错 dart: command not found	Dart 不在 PATH	export PATH="$PATH:/path/to/flutter/bin"
build_runner 报 analyzer 版本冲突	dependency_overrides 被修改	恢复 drift: 2.31.0 和 json_serializable: 6.13.0
App 启动后立即跳登录页	正常（未配置 token）	用 Mock 登录验证，或连后端后正式登录
Mock 登录后 Home 显示占位文字	正常（脚手架默认）	实现 routes.dart 中 HomeRoute 的 build
flutter analyze 显示 103 issues	正常（全为 info 级别）	0 errors 即通过，info 为风格建议
连接后端但请求无响应	api_config.dart 仍是占位 URL	修改 api_config.dart 三套 baseUrl
iOS 真机崩溃，模拟器正常	SecureStorage Keychain 权限	确认 Signing & Capabilities 配置正确