yixiong/flutter-template

Template

Fork 0

Files

T

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

2026-05-14 13:04:51 +08:00

6.7 KiB

Raw Blame History

项目配置指南（所有开发者必读）

本文档覆盖从克隆脚手架到可以运行第一个 dev 包所需的全部步骤。
Android 和 iOS 的平台专属配置请分别参阅 setup-android.md 和 setup-ios.md。

前提条件

工具	最低版本	安装方式
Flutter SDK	3.41.0	flutter.dev
Dart SDK	3.7.0	随 Flutter 一起安装
Android Studio	Meerkat (2024.3)	developer.android.com
Xcode	16.0	Mac App Store（仅 iOS 开发需要）
CocoaPods	1.15+	`sudo gem install cocoapods`
make	系统内置	macOS/Linux 自带；Windows 用 Git Bash 或 WSL

验证安装：

flutter --version   # 应显示 ≥ 3.41.0
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          # 拉取所有依赖
make gen                 # 生成 .g.dart / .freezed.dart（约 1 分钟）
make gen-i18n            # 生成 lib/i18n/strings.g.dart

注意：如果 make gen 报错 build_runner 找不到，请先确认 dart 在 PATH 中：
dart --version

Step 2 — 填入项目 API 路径

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

// 示例（sa-token + Spring Boot）
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/sys-user/app/userInfo';
// ... 其余路径按业务填写

所有 datasource 文件通过 ApiPaths.xxx 引用路径，严禁字符串字面量散落。

Step 3 — 配置环境变量（dart-defines）

3.1 开发环境（dev.json）

# 直接编辑，此文件可提交（含占位符，无真实密钥）
nano dart-defines/dev.json

需填入的字段：

{
  "ENV": "dev",
  "USE_MOCK": "true",          // true = 使用 Mock Adapter（不调真实服务）
  "INTERNAL_BUILD": "true",    // true = 显示 Dev Panel 入口
  "SENTRY_DSN": "",            // dev 通常留空
  "PINNED_FINGERPRINTS": "",   // 证书指纹（dev 可留空跳过 SSL 绑定）
  "API_BASE_URL": "http://192.168.1.100:8080",  // TODO: 实际 dev 服务器
  "RSA_PUBLIC_KEY": "MIIBIjANBg..."              // TODO: 后端 RSA 公钥（Base64 DER）
}

3.2 测试环境（staging.json）

{
  "ENV": "test",
  "USE_MOCK": "false",
  "INTERNAL_BUILD": "true",
  "SENTRY_DSN": "",
  "PINNED_FINGERPRINTS": "",
  "API_BASE_URL": "https://staging.your-domain.com",  // TODO
  "RSA_PUBLIC_KEY": "MIIBIjANBg..."                    // TODO
}

3.3 生产环境（prod.json）

cp dart-defines/prod.json.template dart-defines/prod.json
nano dart-defines/prod.json

{
  "ENV": "prod",
  "USE_MOCK": "false",
  "INTERNAL_BUILD": "false",
  "SENTRY_DSN": "https://xxx@sentry.io/yyy",   // TODO: Sentry 项目 DSN
  "PINNED_FINGERPRINTS": "AA:BB:CC:...",        // TODO: 服务器证书 SHA-256 指纹
  "API_BASE_URL": "https://api.your-domain.com",// TODO
  "RSA_PUBLIC_KEY": "MIIBIjANBg..."             // TODO
}

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

获取 RSA 公钥

后端一般提供 RSA 公钥的 Base64 DER 编码。若后端使用 sa-token + RSA：

# Java 后端：从 public.key 文件提取（去掉 PEM header/footer，拼接成单行）
cat public.key | grep -v "BEGIN\|END" | tr -d '\n'

获取证书 SHA-256 指纹

# 方法 1：openssl（推荐）
echo | openssl s_client -connect api.your-domain.com:443 2>/dev/null \
  | openssl x509 -fingerprint -sha256 -noout \
  | sed 's/SHA256 Fingerprint=//'

# 方法 2：Chrome → 锁图标 → 证书 → 指纹

Step 4 — 验证首次运行

# 方式 1：使用 Mock（推荐首次验证，不需要后端服务）
# 确保 dart-defines/dev.json 中 USE_MOCK=true
make run-dev

# 方式 2：连接真实后端
# 确保 dart-defines/dev.json 中 USE_MOCK=false + API_BASE_URL 已填入
make run-dev

期望结果：

APP 启动，显示登录页（手机号 + SMS/密码双模式）
右上角（或侧滑）可进入 Dev Panel（Talker 日志面板）
flutter analyze 输出 103 issues found（均为 info 级别，0 errors）

Step 5 — 更新包名（业务项目必须）

脚手架默认包名为 com.example.sunny_mochi，接手后必须替换：

Android

编辑 android/app/build.gradle.kts：

// dev Flavor
applicationId = "com.your_company.your_app.dev"

// staging Flavor
applicationId = "com.your_company.your_app.staging"

// prod / release
defaultConfig {
    applicationId = "com.your_company.your_app"
}

iOS

在 Xcode 中修改 Bundle Identifier（见 setup-ios.md Step 3）。

pubspec.yaml + Dart 导入路径

name: your_app_name   # 修改后所有 import 路径也需要更新

批量替换导入：

# 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 重新生成后确认无编译错误。

Step 6 — 平台专属配置

Android（签名 / Flavor 验证 / 发布包构建）→ setup-android.md
iOS（Xcode Scheme / CocoaPods / 证书 / Archive）→ setup-ios.md

常见问题

`build_runner` 生成失败，报 analyzer 版本冲突

确认 pubspec.yaml 中的 dependency_overrides：

dependency_overrides:
  drift: 2.31.0
  json_serializable: 6.13.0

若被修改，恢复后重跑 flutter pub get && make gen。

App 启动后 token 丢失 / 每次重启都跳登录

SecureStorage 在 iOS Simulator 上可能行为异常。请在真机测试，或检查 Keychain Sharing 是否开启。

Mock 模式下请求崩溃 `Unable to load asset`

检查 assets/fixtures/ 下是否有对应的 JSON 文件，且 pubspec.yaml 中的 assets: 包含了对应子目录。

`flutter analyze` 报错（非 info 级别）

先运行 make gen 确保生成文件是最新的，再重新 analyze。

6.7 KiB Raw Blame History Unescape Escape