Flutter: 项目部署 — ShopApp 上线发布

上线不是终点——是持续交付的起点。

📋 前置知识：需要先掌握以下内容

第27课：项目开发 — ShopApp 功能实现

1. 你将学到

构建优化：Tree Shaking / 代码拆分 / 资源压缩 / R8 混淆
Android 部署：签名密钥 + App Bundle + Google Play 上架
iOS 部署：证书配置 + TestFlight + App Store 审核
Web 部署：Firebase Hosting + PWA + SEO 优化
运维监控：Crashlytics 崩溃收集 + Performance 网络追踪 + App Center 分发

2. 一个上线即崩溃的故事

(1) 痛点：开发时正常，上线后崩溃率 5%

Bob 花了 4 个月开发 ShopApp，上线第一天崩溃率 5%。原因：Android R8 混淆把 Firestore 序列化类名抹掉了（反序列化失败）；iOS 缺少相机权限描述被审核拒绝；Web 版首页加载 8 秒（未做代码拆分）。紧急修复 + 重新审核又花了 2 周。

(2) 构建优化 + 发布前检查清单的解法

上线前执行构建优化（混淆规则、代码拆分、资源压缩）+ 发布检查清单（权限、签名、ProGuard 规则、TestFlight 预审），确保首次上线质量。

(3) 收益：首次上线崩溃率 < 0.1%

Bob 用检查清单后，第二个项目首次上线崩溃率 0.08%，审核一次通过，Web 首屏 1.5 秒。

3. 构建优化

(1) ▶ 示例

TEXT 📖 仅展示

> **输出：** 在本地 Flutter SDK（Flutter 3.x / Dart 3.x）运行。Piston 服务器未安装 Flutter，请在本机 `flutter run` 实操对照。实际 UI/状态会因平台略有差异。

：Android ProGuard / R8 规则

PROGUARD

# flutter_proguard_rules.pro

# Keep Firestore model classes (used by json_serializable)
-keepclassmembers class com.shopapp.**.model.** {
  <fields>;
}

# Keep freezed generated classes
-keep class com.shopapp.**.**.freezed.dart { *; }

# Keep Firebase classes
-keep class io.flutter.plugins.firebase.** { *; }
-keep class com.google.firebase.** { *; }

# Keep Stripe SDK
-keep class com.stripe.android.** { *; }

# Keep Google Sign-In
-keep class com.google.android.gms.auth.** { *; }

# Remove logging in release
-assumenosideeffects class android.util.Log {
  public static *** d(...);
  public static *** v(...);
  public static *** i(...);
}

TEXT 📖 仅展示

> **输出：** 在本地 Flutter SDK（Flutter 3.x / Dart 3.x）运行。Piston 服务器未安装 Flutter，请在本机 `flutter run` 实操对照。实际 UI/状态会因平台略有差异。

(2) ▶ 示例

TEXT 📖 仅展示

> **输出：** 在本地 Flutter SDK（Flutter 3.x / Dart 3.x）运行。Piston 服务器未安装 Flutter，请在本机 `flutter run` 实操对照。实际 UI/状态会因平台略有差异。

：Flutter 构建配置

YAML

# pubspec.yaml build optimization
flutter:
  uses-material-design: true
  # Exclude unused locales
  generate: true

# android/app/build.gradle
android {
    buildTypes {
        release {
            shrinkResources true
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
            signingConfig signingConfigs.release
        }
    }
    // Split per ABI to reduce APK size
    splits {
        abi {
            enable true
            reset()
            include 'armeabi-v7a', 'arm64-v8a', 'x86_64'
            universalApk false
        }
    }
}

(3) 构建优化对比

优化项	优化前	优化后	节省
APK 大小 (arm64)	28 MB	12 MB	57%
Web 首屏加载	8.2 s	1.5 s	82%
Dart 代码体积	6.4 MB	2.1 MB	67%
启动时间 (cold)	3.5 s	1.8 s	49%

4. Android 部署

(1) ▶ 示例

TEXT 📖 仅展示

> **输出：** 在本地 Flutter SDK（Flutter 3.x / Dart 3.x）运行。Piston 服务器未安装 Flutter，请在本机 `flutter run` 实操对照。实际 UI/状态会因平台略有差异。

：签名密钥配置

BASH

# Generate signing keystore
keytool -genkey -v -keystore shopapp-release.jks -keyalg RSA -keysize 2048 -validity 10000 -alias shopapp

# Create key.properties
cat > android/key.properties << 'EOF'
storePassword=STORE_PASSWORD
keyPassword=KEY_PASSWORD
keyAlias=shopapp
storeFile=../shopapp-release.jks
EOF

TEXT 📖 仅展示

> **输出：** 在本地 Flutter SDK（Flutter 3.x / Dart 3.x）运行。Piston 服务器未安装 Flutter，请在本机 `flutter run` 实操对照。实际 UI/状态会因平台略有差异。

(2) ▶ 示例

TEXT 📖 仅展示

> **输出：** 在本地 Flutter SDK（Flutter 3.x / Dart 3.x）运行。Piston 服务器未安装 Flutter，请在本机 `flutter run` 实操对照。实际 UI/状态会因平台略有差异。

：build.gradle 签名集成

GROOVY

// android/app/build.gradle
def keystoreProperties = new Properties()
def keystorePropertiesFile = rootProject.file('key.properties')
if (keystorePropertiesFile.exists()) {
    keystoreProperties.load(new FileInputStream(keystorePropertiesFile))
}

android {
    signingConfigs {
        release {
            keyAlias keystoreProperties['keyAlias']
            keyPassword keystoreProperties['keyPassword']
            storeFile keystoreProperties['storeFile'] ? file(keystoreProperties['storeFile']) : null
            storePassword keystoreProperties['storePassword']
        }
    }
    buildTypes {
        release {
            signingConfig signingConfigs.release
        }
    }
}

TEXT 📖 仅展示

> **输出：** 在本地 Flutter SDK（Flutter 3.x / Dart 3.x）运行。Piston 服务器未安装 Flutter，请在本机 `flutter run` 实操对照。实际 UI/状态会因平台略有差异。

(3) ▶ 示例

TEXT 📖 仅展示

> **输出：** 在本地 Flutter SDK（Flutter 3.x / Dart 3.x）运行。Piston 服务器未安装 Flutter，请在本机 `flutter run` 实操对照。实际 UI/状态会因平台略有差异。

：构建 App Bundle 并上传

BASH

# Build App Bundle (recommended over APK for Play Store)
flutter build appbundle --release --obfuscate --split-debug-info=build/debug-info

# Upload to Google Play Console
# Option 1: Manual via Play Console UI
# Option 2: Fastlane
cd android && fastlane supply --aab ../build/app/outputs/bundle/release/app-release.aab --track internal

TEXT 📖 仅展示

> **输出：** 在本地 Flutter SDK（Flutter 3.x / Dart 3.x）运行。Piston 服务器未安装 Flutter，请在本机 `flutter run` 实操对照。实际 UI/状态会因平台略有差异。

(4) Android 发布检查清单

#	检查项	状态
1	签名密钥已生成并备份	☐
2	key.properties 不在版本控制中	☐
3	ProGuard 规则覆盖所有第三方 SDK	☐
4	versionCode / versionName 已更新	☐
5	权限声明最小化	☐
6	App Bundle 而非 APK 上传	☐
7	商店截图 + 描述已准备	☐
8	隐私政策 URL 已配置	☐

5. iOS 部署

(1) ▶ 示例

TEXT 📖 仅展示

> **输出：** 在本地 Flutter SDK（Flutter 3.x / Dart 3.x）运行。Piston 服务器未安装 Flutter，请在本机 `flutter run` 实操对照。实际 UI/状态会因平台略有差异。

：Info.plist 权限配置

XML

<!-- ios/Runner/Info.plist -->
`<key>`NSCameraUsageDescription</key>
`<string>`ShopApp needs camera access to scan product barcodes.</string>
`<key>`NSPhotoLibraryUsageDescription</key>
`<string>`ShopApp needs photo access to upload product reviews.</string>
`<key>`NSLocationWhenInUseUsageDescription</key>
`<string>`ShopApp uses location for local delivery estimates.</string>
`<key>`CFBundleURLTypes</key>
`<array>`
  `<dict>`
    `<key>`CFBundleURLSchemes</key>
    `<array>`
      `<string>`com.googleusercontent.apps.YOUR_CLIENT_ID</string>
    </array>
  </dict>
</array>

(2) ▶ 示例

TEXT 📖 仅展示

> **输出：** 在本地 Flutter SDK（Flutter 3.x / Dart 3.x）运行。Piston 服务器未安装 Flutter，请在本机 `flutter run` 实操对照。实际 UI/状态会因平台略有差异。

：Fastlane iOS 发布

RUBY

# ios/fastlane/Fastfile
default_platform(:ios)

platform :ios do
  desc "Build and upload to TestFlight"
  lane :beta do
    build_app(
      workspace: "Runner.xcworkspace",
      scheme: "Runner",
      export_method: "app-store",
      include_bitcode: false,
      export_options: {
        compileBitcode: false,
        provisioningProfiles: {
          "com.shopapp.app" => "match AppStore com.shopapp.app"
        }
      }
    )
    upload_to_testflight(
      skip_waiting_for_build_processing: true
    )
  end

  desc "Submit to App Store review"
  lane :release do
    beta
    deliver(
      submit_for_review: true,
      automatic_release: true,
      force: true,
      metadata_path: "./metadata"
    )
  end
end

TEXT 📖 仅展示

> **输出：** 在本地 Flutter SDK（Flutter 3.x / Dart 3.x）运行。Piston 服务器未安装 Flutter，请在本机 `flutter run` 实操对照。实际 UI/状态会因平台略有差异。

(3) iOS 审核常见拒绝原因

拒绝原因	解决方案
缺少权限描述	Info.plist 添加 NS*UsageDescription
支付未用 IAP（虚拟商品）	虚拟商品用 StoreKit，实物用 Stripe
登录强制绑定社交账号	提供邮箱/密码登录选项
WebView 包装应用	确保原生功能 > 50%
元数据不完整	补全年龄分级、隐私政策 URL

6. Web 部署

(1) ▶ 示例

TEXT 📖 仅展示

> **输出：** 在本地 Flutter SDK（Flutter 3.x / Dart 3.x）运行。Piston 服务器未安装 Flutter，请在本机 `flutter run` 实操对照。实际 UI/状态会因平台略有差异。

：Firebase Hosting 配置

JSON

// firebase.json
{
  "hosting": {
    "public": "build/web",
    "ignore": ["firebase.json", "**/.*", "**/node_modules/**"],
    "rewrites": [
      { "source": "**", "destination": "/index.html" }
    ],
    "headers": [
      {
        "source": "**/*.@(js|css|wasm)",
        "headers": [
          { "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }
        ]
      },
      {
        "source": "**/*.@(jpg|jpeg|gif|png|svg|webp|ico)",
        "headers": [
          { "key": "Cache-Control", "value": "public, max-age=604800" }
        ]
      },
      {
        "source": "/index.html",
        "headers": [
          { "key": "Cache-Control", "value": "no-cache" }
        ]
      }
    ]
  }
}

(2) ▶ 示例

TEXT 📖 仅展示

> **输出：** 在本地 Flutter SDK（Flutter 3.x / Dart 3.x）运行。Piston 服务器未安装 Flutter，请在本机 `flutter run` 实操对照。实际 UI/状态会因平台略有差异。

：Web 构建与部署

BASH

# Build web with CanvasKit renderer (better performance)
flutter build web --release --web-renderer canvaskit --pwa-strategy offline_first

# Deploy to Firebase Hosting
firebase deploy --only hosting

# Or deploy to custom server with Nginx
scp -r build/web/* user@server:/var/www/shopapp/

TEXT 📖 仅展示

> **输出：** 在本地 Flutter SDK（Flutter 3.x / Dart 3.x）运行。Piston 服务器未安装 Flutter，请在本机 `flutter run` 实操对照。实际 UI/状态会因平台略有差异。

(3) Web 性能优化对比

优化策略	首屏时间	LCP	FID
未优化 (HTML renderer)	8.2 s	7.8 s	180 ms
CanvasKit renderer	3.1 s	2.8 s	45 ms
+ Code split + lazy	1.5 s	1.2 s	30 ms
+ PWA + Service Worker	0.8 s (repeat)	0.5 s	15 ms

7. 运维监控

(1) ▶ 示例

TEXT 📖 仅展示

> **输出：** 在本地 Flutter SDK（Flutter 3.x / Dart 3.x）运行。Piston 服务器未安装 Flutter，请在本机 `flutter run` 实操对照。实际 UI/状态会因平台略有差异。

：Crashlytics 集成

DART

import 'package:flutter/material.dart';
import 'package:firebase_core/firebase_core.dart';
import 'package:firebase_crashlytics/firebase_crashlytics.dart';
import 'package:firebase_auth/firebase_auth.dart';
import 'dart:ui' show PlatformDispatcher;

// ⚙️ 依赖：firebase_core: ^2.0.0, firebase_crashlytics: ^3.0.0, firebase_auth: ^4.0.0
// DefaultFirebaseOptions / ShopApp 来自 ShopApp 项目

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp(options: DefaultFirebaseOptions.currentPlatform);

  // Crashlytics
  FlutterError.onError = FirebaseCrashlytics.instance.recordFlutterFatalError;
  PlatformDispatcher.instance.onError = (error, stack) {
    FirebaseCrashlytics.instance.recordError(error, stack, fatal: true);
    return true;
  };

  // Pass all uncaught errors to Crashlytics
  await FirebaseCrashlytics.instance.setCrashlyticsCollectionEnabled(true);

  // Set user identifier for crash reports
  FirebaseAuth.instance.authStateChanges().listen((user) {
    if (user != null) {
      FirebaseCrashlytics.instance.setUserIdentifier(user.uid);
    }
  });

  // Custom keys for context
  FirebaseCrashlytics.instance.setCustomKey('app_version', '1.0.0');
  FirebaseCrashlytics.instance.setCustomKey('environment', 'production');

  runApp(const ShopApp());
}

TEXT 📖 仅展示

> **输出：** 在本地 Flutter SDK（Flutter 3.x / Dart 3.x）运行。Piston 服务器未安装 Flutter，请在本机 `flutter run` 实操对照。实际 UI/状态会因平台略有差异。

(2) ▶ 示例

TEXT 📖 仅展示

> **输出：** 在本地 Flutter SDK（Flutter 3.x / Dart 3.x）运行。Piston 服务器未安装 Flutter，请在本机 `flutter run` 实操对照。实际 UI/状态会因平台略有差异。

：Performance Monitoring

DART

import 'package:dio/dio.dart';
import 'package:firebase_performance/firebase_performance.dart';

// ⚙️ 依赖：firebase_performance: ^0.9.0, dio: ^5.0.0（添加到 dependencies）

class ShopPerformance {
  static final _perf = FirebasePerformance.instance;

  static Future<void> trackProductLoad(String productId) async {
    final trace = _perf.newTrace('product_load');
    trace.putAttribute('product_id', productId);
    await trace.start();
    try {
      // ... load product ...
    } finally {
      await trace.stop();
    }
  }

  static Future<void> trackSearch(String query, int results) async {
    final trace = _perf.newTrace('search');
    trace.putAttribute('query', query);
    trace.putMetric('results_count', results);
    await trace.start();
    await trace.stop();
  }

  static Future<void> trackCheckout(double total) async {
    final trace = _perf.newTrace('checkout');
    trace.putMetric('order_total_cents', (total * 100).toInt());
    await trace.start();
    await trace.stop();
  }
}

// HTTP performance auto-tracking with Dio
class PerformanceInterceptor extends Interceptor {
  @override
  void onRequest(RequestOptions options, RequestInterceptorHandler handler) {
    options.extra['trace'] = FirebasePerformance.instance.newHttpMetric(
      options.uri.toString(), HttpMethod.Post);
    (options.extra['trace'] as HttpMetric).start();
    handler.next(options);
  }

  @override
  void onResponse(Response response, ResponseInterceptorHandler handler) {
    final trace = response.requestOptions.extra['trace'] as HttpMetric?;
    trace?.httpResponseCode = response.statusCode;
    trace?.stop();
    handler.next(response);
  }

  @override
  void onError(DioException err, ErrorInterceptorHandler handler) {
    final trace = err.requestOptions.extra['trace'] as HttpMetric?;
    trace?.httpResponseCode = err.response?.statusCode;
    trace?.stop();
    handler.next(err);
  }
}

TEXT 📖 仅展示

> **输出：** 在本地 Flutter SDK（Flutter 3.x / Dart 3.x）运行。Piston 服务器未安装 Flutter，请在本机 `flutter run` 实操对照。实际 UI/状态会因平台略有差异。

8. 完整示例：发布前自动化检查脚本

DART

// tool/release_check.dart
import 'dart:io';

// 纯 Dart 脚本，无 Flutter 依赖，用 dart run tool/release_check.dart 运行

enum Platform { android, ios, web }

class ReleaseChecker {
  static Future<bool> run(Platform platform) async {
    final results = <String, bool>{};

    results['version_updated'] = _checkVersionUpdated();
    results['changelog_updated'] = _checkChangelog();
    results['no_debug_print'] = _checkNoDebugPrint();
    results['proguard_rules'] = platform == Platform.android ? _checkProguard() : true;
    results['info_plist'] = platform == Platform.ios ? _checkInfoPlist() : true;
    results['privacy_policy'] = _checkPrivacyPolicy();
    results['signing_config'] = _checkSigningConfig(platform);
    results['test_pass'] = await _runTests();
    results['analyze_pass'] = await _runAnalyze();

    final allPass = results.values.every((v) => v);
    if (!allPass) {
      print('Release check FAILED:');
      results.forEach((k, v) { if (!v) print('  ✗ $k'); });
    } else {
      print('All release checks PASSED!');
    }
    return allPass;
  }

  static bool _checkVersionUpdated() {
    // Compare current pubspec.yaml version with last git tag
    return true; // Simplified
  }

  static bool _checkChangelog() => File('CHANGELOG.md').existsSync();

  static bool _checkNoDebugPrint() {
    // Grep for debugPrint / print() in lib/
    return true; // Simplified
  }

  static bool _checkProguard() => File('android/app/proguard-rules.pro').existsSync();

  static bool _checkInfoPlist() {
    final plist = File('ios/Runner/Info.plist').readAsStringSync();
    return plist.contains('NSCameraUsageDescription') && plist.contains('NSPhotoLibraryUsageDescription');
  }

  static bool _checkPrivacyPolicy() => true;

  static bool _checkSigningConfig(Platform platform) {
    if (platform == Platform.android) return File('android/key.properties').existsSync();
    return true; // iOS uses Xcode managed signing
  }

  static Future<bool> _runTests() async {
    final result = await Process.run('flutter', ['test']);
    return result.exitCode == 0;
  }

  static Future<bool> _runAnalyze() async {
    final result = await Process.run('flutter', ['analyze']);
    return result.exitCode == 0;
  }
}

void main(List<String> args) async {
  final platform = switch (args.firstOrNull) {
    'android' => Platform.android,
    'ios' => Platform.ios,
    'web' => Platform.web,
    _ => Platform.android,
  };
  final pass = await ReleaseChecker.run(platform);
  exit(pass ? 0 : 1);
}

TEXT 📖 仅展示

> **输出：** 在本地 Flutter SDK（Flutter 3.x / Dart 3.x）运行。Piston 服务器未安装 Flutter，请在本机 `flutter run` 实操对照。实际 UI/状态会因平台略有差异。

9. 部署流程总览

graph TD
    CODE[Source Code] --> ANALYZE[flutter analyze]
    ANALYZE --> TEST[flutter test]
    TEST --> CHECK{Release Check}
    CHECK -->|FAIL| FIX[Fix Issues]
    FIX --> ANALYZE
    CHECK -->|PASS| BUILD[flutter build]
    BUILD --> ANDROID[Android: AAB → Play Console]
    BUILD --> IOS[iOS: IPA → TestFlight → App Store]
    BUILD --> WEB[Web: Firebase Hosting]
    ANDROID --> MONITOR[Crashlytics + Performance]
    IOS --> MONITOR
    WEB --> MONITOR
    MONITOR --> ITERATE[Iterate & Release Next Version]

TEXT 📖 仅展示

> **输出：** 在本地 Flutter SDK（Flutter 3.x / Dart 3.x）运行。Piston 服务器未安装 Flutter，请在本机 `flutter run` 实操对照。实际 UI/状态会因平台略有差异。

❓ 常见问题

Q App Bundle 和 APK 有什么区别？

A AAB 是 Google Play 的发布格式，按设备 ABI/密度自动拆分，下载体积更小。APK 是完整安装包，用于侧载分发。

Q iOS 审核一般要多久？

A 首次提交 2-5 天，后续更新 1-2 天。被拒绝后修复重新提交需额外 1-3 天。

Q Web 版 Flutter 支持 SEO 吗？

A Flutter Web 是 SPA，搜索引擎难以索引内容。解决方案：1) 用 SSR（dart2js + server）；2) 预渲染关键页面；3) 补充静态落地页。

Q 混淆后 Crashlytics 堆栈看不懂怎么办？

A 构建时用 --split-debug-info 保存符号表，Crashlytics 上传 deobfuscation 文件（Android）或 dSYM（iOS）即可还原堆栈。

Q 热更新 / Code Push 支持 Flutter 吗？

A Flutter 原生不支持代码热更新。可用 shorebird.dev 实现部分代码推送（Android），iOS 仍需 App Store 审核。

Q 多平台同时发布怎么管理版本？

A 统一 pubspec.yaml version，用 CI/CD 矩阵构建（GitHub Actions：android + ios + web 三个 job 并行）。

Q 上线后崩溃率多少算正常？

A 优秀 < 0.1%，良好 < 0.5%，需关注 > 1%。Crashlytics 提供实时崩溃率仪表盘。

📖 小节

构建优化：R8 混淆 + ABI 拆分 + CanvasKit 渲染器，APK 减 57%、Web 首屏减 82%
Android：签名密钥 → App Bundle → Play Console → 内测/公测/正式
iOS：Info.plist 权限 → Fastlane → TestFlight → App Store 审核
Web：Firebase Hosting + PWA + Service Worker + CDN 缓存策略
运维：Crashlytics 崩溃收集 + Performance 网络追踪 + 自动化发布检查

📝 作业

基础题（难度⭐）：配置 Android 签名密钥 + ProGuard 规则，构建 Release App Bundle 并验证大小优化。
进阶题（难度⭐⭐）：配置 Crashlytics + Performance Monitoring，模拟崩溃和慢请求，验证监控数据上报。
挑战题（难度⭐⭐⭐）：编写完整的 CI/CD 管线（GitHub Actions）：analyze → test → release check → build (android + ios + web) → deploy，实现一键多平台发布。

← 上一课 | 回到目录

Web-Tutorial 技术团队

由多位开发者共同维护的编程教程平台。每篇教程由对应领域的开发者编写和审核，确保内容准确可靠。如发现任何问题，欢迎向我们反馈。

关于我们

Flutter: 项目部署 — ShopApp 上线发布

1. 你将学到

2. 一个上线即崩溃的故事

(1) 痛点：开发时正常，上线后崩溃率 5%

(2) 构建优化 + 发布前检查清单的解法

(3) 收益：首次上线崩溃率 < 0.1%

3. 构建优化

(1) ▶ 示例

(2) ▶ 示例

(3) 构建优化对比

4. Android 部署

(1) ▶ 示例

(2) ▶ 示例

(3) ▶ 示例

(4) Android 发布检查清单

5. iOS 部署

(1) ▶ 示例

(2) ▶ 示例

(3) iOS 审核常见拒绝原因

6. Web 部署

(1) ▶ 示例

(2) ▶ 示例

(3) Web 性能优化对比

7. 运维监控

(1) ▶ 示例

(2) ▶ 示例

8. 完整示例：发布前自动化检查脚本

9. 部署流程总览

❓ 常见问题

📖 小节

📝 作业

🙏 帮我们做得更好