Flutter 基础体系 · 第 74/80 篇。示例基于当前稳定 Flutter 与 Dart 3 语言能力；Android、iOS、桌面和 Web 差异会明确说明。

Flutter CI/CD：分析、测试、签名、构建、商店上传和回滚

Flutter CI/CD 不是把 flutter build 放进脚本就结束了。一个可审计的移动端交付流程至少要回答以下问题：

哪些代码和依赖允许进入构建？
静态分析和测试如何阻止缺陷继续流转？
Android 与 iOS 的签名材料分别由谁、在哪里、以什么形式使用？
构建产物如何与源码、版本号和构建环境对应？
商店上传成功是否等于用户已经安装？
线上出现问题时，是停止发布、回退服务端，还是重新发布旧版本？

本文以 Flutter 项目为主线，覆盖 Android、iOS、Web、Windows、macOS 和 Linux 的差异。示例使用 Dart 3 语言能力和当前稳定版 Flutter 的常规命令；具体 SDK 版本、Xcode、Android Gradle Plugin、商店接口和第三方 CI Action 仍应在项目中显式固定。

一、先定义 CI/CD：从提交到用户安装的状态机

**CI（Continuous Integration，持续集成）**是：每次合并或提交都自动执行一致的验证，使问题尽早暴露。验证对象包括源代码、依赖解析、静态分析、单元测试、Widget 测试、集成测试和构建可行性。

**CD（Continuous Delivery/Deployment，持续交付/持续部署）**通常有两个含义：

Continuous Delivery：产物已经构建、签名并准备好，可以由人批准后上传或发布。
Continuous Deployment：通过自动化流程直接上传、提交审核或发布到目标环境。

移动端发布通常更接近“持续交付”，因为 Apple App Store 审核、Google Play 发布控制和用户设备更新都不完全由 CI 系统决定。

一个简化的状态流如下：

flowchart LR
    A[提交或合并请求] --> B[固定 Flutter/Dart/依赖]
    B --> C[格式检查与静态分析]
    C --> D[单元与 Widget 测试]
    D --> E[集成测试]
    E --> F[未签名或调试构建]
    F --> G[签名构建]
    G --> H[产物校验与归档]
    H --> I{人工批准}
    I -->|否| J[保留产物，等待处理]
    I -->|是| K[上传测试轨道或 TestFlight]
    K --> L[灰度或分阶段发布]
    L --> M[监控崩溃、性能和业务指标]
    M --> N{是否异常}
    N -->|否| O[扩大发布范围]
    N -->|是| P[暂停发布或发布回退版本]

这条链路中，“构建成功”只说明编译和打包完成；它不证明测试充分、签名正确、商店接受、用户能够升级，也不证明线上行为正确。

1. 版本、提交和产物必须能够互相追溯

Flutter 的 pubspec.yaml 中通常包含：

version: 2.4.0+173

这里：

2.4.0 是用户可见版本，通常对应 Android 的 versionName 和 iOS 的 CFBundleShortVersionString。
173 是构建版本，通常对应 Android 的 versionCode 和 iOS 的 CFBundleVersion。

对于一次发布，至少应建立如下映射：

Git commit SHA
    -> Flutter/Dart/Java/Kotlin/Xcode 版本
    -> pubspec.lock
    -> versionName/versionCode
    -> 签名产物 SHA-256
    -> 商店上传记录

如果只在产物名称中写 app-release.apk，多个构建会互相覆盖，发布事故后无法判断用户安装的到底是哪一份文件。更可靠的产物名称类似：

app-android-arm64-2.4.0+173-githash.aab
app-ios-2.4.0+173-githash.ipa

产物文件名不是安全证明。CI 还应计算哈希：

sha256sum build/app/outputs/bundle/release/app-release.aab

预期输出是一行十六进制 SHA-256 值。它只能证明下载的文件与归档文件相同，不能证明文件本身没有恶意代码，因此仍需结合构建日志、提交记录和签名验证。

二、依赖和环境固定：分析之前先消除“机器差异”

CI 中最常见的隐性问题不是 Dart 代码，而是“本地机器和构建机器不是同一个环境”。Flutter 项目至少涉及：

Flutter SDK 和 Dart SDK；
pubspec.yaml、pubspec.lock；
Android SDK、Build Tools、JDK、Gradle 和 Android Gradle Plugin；
macOS 上的 Xcode、CocoaPods 和证书；
Windows、Linux、macOS 桌面平台的原生工具链。

应用项目通常应提交 pubspec.lock，使 CI 使用与开发机一致的依赖解析结果。库项目通常不以同样方式固定最终使用者的依赖版本，这是应用和可复用包的语义差异。

建议在 CI 开始阶段输出环境信息：

set -euxo pipefail

flutter --version
dart --version
flutter doctor -v
git rev-parse HEAD
git status --short

set -e 使命令失败时立即退出，-u 使未定义变量报错，pipefail 使管道中任一命令失败都能让整体失败。Windows Runner 需要使用 PowerShell 等价语法，不能直接假设 Bash 存在。

依赖安装通常使用：

flutter pub get

flutter pub get 会根据 pubspec.yaml 和锁文件解析依赖，并生成或更新 .dart_tool 目录。若 CI 使用缓存，应缓存 Pub 下载目录或 CI 工具提供的依赖缓存，但缓存键必须包含操作系统、Flutter 版本和锁文件哈希。否则可能复用不兼容的编译产物或错误的依赖解析结果。

不要把 flutter pub upgrade 放进普通发布流水线。upgrade 可能改变锁文件，使同一提交在不同时间得到不同依赖；依赖升级应由单独的变更提交完成，再经过验证后合并。

三、静态分析：在运行程序之前验证代码约束

1. 格式化不是静态分析

格式化只负责将源代码转换为统一排版；静态分析则在不运行应用的情况下检查类型、未使用代码、空安全约束、API 使用错误、Lint 规则和部分潜在缺陷。

CI 中常见写法：

dart format --output=none --set-exit-if-changed .
flutter analyze

其中：

dart format 检查格式是否与 Dart formatter 的结果一致；
--set-exit-if-changed 表示如果 formatter 会修改文件，则返回非零退出码；
flutter analyze 使用 Flutter 项目上下文运行 Dart analyzer，并检查 Flutter 相关代码。

先本地格式化，再让 CI 检查：

dart format .

这条命令会修改文件，因此不应在 CI 中“自动修改后继续构建”，否则 CI 工作区中的代码和提交内容不一致，测试结果无法对应 Git 提交。

2. `analysis_options.yaml` 决定分析边界

项目可以在 analysis_options.yaml 中启用 Flutter 推荐规则或自定义规则。例如：

include: package:flutter_lints/flutter.yaml

linter:
  rules:
    avoid_print: true
    prefer_final_locals: true

规则的作用有不同层次：

编译错误和类型错误通常会阻止构建；
lint 通常是警告或提示，是否让它失败取决于规则和 CI 策略；
某些规则属于团队风格，不应被误认为 Flutter 框架的运行时保证。

如果团队要求“任何 analyzer issue 都失败”，应在 CI 中确认当前 Flutter/Dart 版本的命令行为，而不要仅凭某个版本的默认配置推断。版本升级可能新增 analyzer 规则，使原本通过的流水线突然失败；因此 Flutter 升级应作为可审查的依赖变更。

3. 分析失败的诊断顺序

当 flutter analyze 失败时，先区分三类问题：

解析或类型错误：例如导入不存在的库、调用不存在的方法、可空值直接赋给非空变量。这类错误通常必然影响编译。
规则问题：例如 avoid_print、命名或文档规则。它们需要判断是修复代码还是调整规则。
环境问题：依赖没有获取、生成代码未生成、Flutter SDK 版本不匹配。

例如生成代码项目可能需要先执行代码生成工具；但生成步骤必须固定工具版本，并把生成结果是否提交到仓库的策略说清楚。不能因为本地曾运行过生成器，就假设 CI 工作区中一定存在生成文件。

四、测试：不同测试验证不同失败路径

1. 测试层次和因果关系

Flutter 测试不能用一类测试替代全部验证：

单元测试验证纯 Dart 逻辑，例如价格计算、状态转换、序列化。
Widget 测试验证 Widget 树、布局、手势、文本和状态更新。
集成测试验证真实应用进程、路由、插件、平台通道和设备行为。
端到端测试通常是对集成测试的业务化称呼，重点是从用户入口走到业务结果。

测试越接近真实设备，覆盖的系统因素越多，速度和稳定性通常越差。正确做法不是只选一种，而是让低成本测试承担大多数确定性逻辑，让少量集成测试验证跨组件边界。

运行普通测试：

flutter test --coverage

--coverage 通常生成 coverage/lcov.info。它是覆盖率原始数据，不等于质量分数。覆盖率只表示某些代码路径被执行过，并不能证明断言有意义。

一个可运行的纯 Dart 测试示例：

// lib/cart_total.dart
double cartTotal(List<double> prices, {double discount = 0}) {
  if (prices.any((price) => price < 0)) {
    throw ArgumentError('price must not be negative');
  }
  if (discount < 0 || discount > 1) {
    throw ArgumentError('discount must be between 0 and 1');
  }

  final subtotal = prices.fold<double>(0, (sum, price) => sum + price);
  return subtotal * (1 - discount);
}

// test/cart_total_test.dart
import 'package:flutter_test/flutter_test.dart';
import 'package:example/cart_total.dart';

void main() {
  test('applies discount to subtotal', () {
    expect(cartTotal([10, 20], discount: 0.1), closeTo(27, 0.000001));
  });

  test('rejects negative price', () {
    expect(
      () => cartTotal([-1]),
      throwsA(isA<ArgumentError>()),
    );
  });
}

执行：

flutter test test/cart_total_test.dart

输入是测试文件，预期输出是所有测试通过且进程退出码为 0。第一条测试验证计算结果，第二条测试验证非法输入不会静默产生错误金额；如果只测正常路径，负数边界可能进入生产环境。

2. Widget 测试的异步和布局边界

Widget 测试使用测试 binding 构造 Widget 树，并通过 pump 推进帧：

testWidgets('shows title', (tester) async {
  await tester.pumpWidget(
    const MaterialApp(
      home: Scaffold(
        body: Text('Dashboard'),
      ),
    ),
  );

  expect(find.text('Dashboard'), findsOneWidget);
});

这里的 pumpWidget 会将 Widget 树挂载到测试环境，find.text 查询树中的文本节点。若被测 Widget 在 initState 中启动异步操作，通常还需要：

await tester.pumpAndSettle();

但 pumpAndSettle 会等待动画和异步任务稳定；如果代码存在无限动画、定时器或持续流，它可能超时。此时应使用有限次数的 pump，或者在测试中注入可控的时钟和数据源，而不是无限增加超时时间。

Widget 测试默认不是完整真实设备测试。插件的原生实现、权限弹窗、真实键盘、GPU 差异和部分平台行为，必须由设备或模拟器上的集成测试验证。

3. 集成测试的设备前提

Flutter 官方集成测试通常放在 integration_test/，并由设备运行：

flutter test integration_test

该命令能否成功取决于 CI 是否有可用设备、模拟器或浏览器，以及项目使用的插件是否支持目标平台。典型失败包括：

没有启动 Android Emulator；
iOS 模拟器运行在非 macOS Runner；
所需插件没有在 Web 或桌面实现；
网络、推送、相机等真实服务不可用；
测试依赖固定屏幕尺寸，却在不同设备上运行。

因此集成测试前应先检查：

flutter devices

预期至少显示一个目标设备。若没有设备，测试命令失败不是业务代码失败，而是测试基础设施未满足前置条件。

不要把真实生产密钥、生产数据库和真实支付环境直接交给集成测试。更安全的方式是使用测试后端、隔离账户和可清理的数据；否则测试重试可能重复下单或修改真实用户状态。

五、签名：构建可安装包的身份和完整性机制

签名是使用私钥对应用或其元数据生成密码学证明，使平台能够验证：

产物来自某个开发者或组织；
产物在签名后没有被篡改；
更新包满足平台规定的身份连续性。

签名不是加密。用户仍能运行应用并访问大部分资源，签名主要解决来源认证、完整性和更新授权。

1. Android 签名

Android 发布通常使用：

密钥库（keystore）；
密钥别名（alias）；
私钥密码和密钥库密码；
Gradle 的 release signing 配置；
Google Play App Signing（如果项目加入该机制）。

实际发布时常见两层密钥：

Upload key：CI 用于上传构建产物；
App signing key：Google Play 用于向用户分发最终 APK。

启用 Play App Signing 后，CI 通常不直接持有最终分发密钥，但 upload key 仍需保护。若项目未使用托管签名，丢失最终签名密钥可能导致无法对已有安装包进行正常更新。

一种常见的 Android 配置方式是让 android/key.properties 指向密钥库：

storePassword=***
keyPassword=***
keyAlias=upload
storeFile=/secure/path/upload-keystore.jks

该文件不能提交到 Git。Gradle 脚本读取它后，将 release variant 的签名配置绑定到对应 keystore。不同 Flutter 模板可能使用 build.gradle 或 build.gradle.kts，字段写法不同，不能把 Groovy 片段机械复制到 Kotlin DSL。

CI 中更安全的流程是：

将 keystore 作为 CI Secret File 或受保护的加密变量提供；
在临时工作区写入文件；
通过环境变量生成 key.properties；
构建完成后删除临时文件；
禁止在日志中打印密码和文件内容。

例如，Base64 只是传输编码，不是加密：

printf '%s' "$ANDROID_KEYSTORE_B64" | base64 --decode > "$RUNNER_TEMP/upload.jks"

如果 CI 日志、缓存或构建机器被读取，Base64 内容同样会泄露私钥。真正的保护依赖 CI Secret 存储、最小权限、短生命周期凭据、受控 Runner 和审计。

2. iOS 签名

iOS 发布签名涉及 Apple Developer 账号、Bundle Identifier、证书、Provisioning Profile、Entitlements 和 Xcode 的代码签名过程。与 Android 不同，iOS 发布构建通常必须在 macOS 上使用 Xcode 工具链完成。

主要概念包括：

Bundle Identifier：应用身份，例如 com.example.shop；
Signing Certificate：签名证书及其私钥；
Provisioning Profile：将 App ID、证书、设备或发布方式、Entitlements 绑定起来；
Entitlements：能力声明，例如 Push Notifications、Associated Domains；
Team ID：开发者团队身份。

Flutter 的命令可以触发 iOS 构建：

flutter build ipa --release

实际导出过程仍由 Xcode 的签名和归档工具完成。若需要固定导出行为，可提供 ExportOptions.plist：

flutter build ipa \
  --release \
  --export-options-plist=ios/ExportOptions-AppStore.plist

ExportOptions.plist 中的 method、签名方式、团队信息和 profile 映射必须与项目的 Apple 配置一致；不能从别的 Bundle Identifier 直接复制。

常见错误及原因：

No profiles for ... were found：没有匹配 Bundle Identifier 的 profile；
Provisioning profile doesn't include ... entitlement：启用的能力与 profile 不一致；
Signing certificate ... is not trusted：CI Keychain 没有导入证书链或私钥；
本地成功、CI 失败：本地使用了 Xcode 自动管理签名，而 CI 没有对应账号访问权限。

CI 可以选择：

在临时 Keychain 中导入证书和私钥；
导入匹配的 provisioning profile；
使用受控的签名服务或成熟发布工具；
使用 Xcode 的自动签名，但为 CI 提供安全的 App Store Connect API 访问方式。

无论哪种方式，证书私钥和 profile 都不应写入仓库。Apple 证书也有有效期，流水线应在过期前通过监控或定期验证发现问题。

3. Web 与桌面平台没有统一的“商店签名”

Flutter Web 通常构建为静态资源：

flutter build web --release

输出目录通常是 build/web。它没有 Android APK 那种平台安装签名；完整性和发布身份由 HTTPS、服务器发布权限、对象存储签名、CDN 和部署系统保护。Web 还必须考虑：

--base-href 与部署路径；
浏览器缓存和 Service Worker；
SPA 路由回退；
Web Renderer 和浏览器兼容性；
静态资源原子发布。

桌面构建命令依平台而异：

flutter build windows --release
flutter build macos --release
flutter build linux --release

桌面发布通常涉及安装包制作、操作系统代码签名和分发渠道：

macOS 可能需要 Developer ID 签名与 notarization；
Windows 可能需要代码签名证书和安装器；
Linux 的分发格式和签名方式取决于发行渠道。

因此不能把移动端的 keystore 或 provisioning profile 方案套用于 Web 和桌面。

六、构建：选择正确的产物和构建模式

Flutter 中常见构建模式为：

debug：开发调试，包含调试能力，不适合商店发布；
profile：用于性能分析，通常不能作为生产发布包；
release：面向真实用户，启用发布优化。

1. Android：优先理解 APK 与 AAB 的区别

flutter build appbundle --release

通常生成 Android App Bundle（.aab）。AAB 是提交给 Google Play 的发布格式，商店可以根据设备 ABI、屏幕密度和语言生成更合适的 APK。

flutter build apk --release

生成 APK，适合侧载、内部分发或某些非 Play 渠道。若只需要特定架构，可以使用：

flutter build apk --release --split-per-abi

这会产生多个 ABI 产物。它减少单个 APK 体积，但分发系统必须选择正确 ABI；错误地把 arm64-v8a 包发给不兼容设备会导致无法安装或运行。

发布构建必须确认：

release variant 确实使用 release signing；
applicationId 与商店应用一致；
versionCode 大于当前商店已接受的版本；
最小 SDK、目标 SDK、NDK 和插件要求满足；
必要的混淆、资源压缩和崩溃符号文件已经归档。

如果启用 R8/ProGuard，混淆可能改变类名，导致崩溃堆栈难以阅读。对应的 mapping 文件必须与构建版本绑定保存，否则线上崩溃无法正确反混淆。

2. iOS：IPA 不是“上传成功”的同义词

flutter build ipa --release

该命令构建并导出 .ipa，但它不代表：

Apple 已接受上传；
App Store 审核已通过；
用户已经可以下载；
远程配置和服务端接口兼容。

构建后应检查版本信息、Bundle Identifier、签名身份和导出方式。对于 App Store Connect，上传常通过 Xcode Organizer、Transporter、xcrun altool 的替代工具链或第三方发布工具完成；具体命令会随 Xcode 和 Apple 工具变化，不能在没有验证工具版本的情况下固定一条“永远有效”的命令。

3. 用 flavor 区分环境，而不是在运行时猜环境

Flutter 支持通过 flavor 产生不同环境构建，例如：

flutter build appbundle \
  --release \
  --flavor production \
  -t lib/main_production.dart

入口文件可以分别注入 API 地址、日志级别或功能配置：

import 'package:flutter/material.dart';

const apiBaseUrl = String.fromEnvironment(
  'API_BASE_URL',
  defaultValue: 'https://api.example.com',
);

void main() {
  runApp(const MyApp());
}

构建时传入：

flutter build apk --release \
  --dart-define=API_BASE_URL=https://staging.example.com

--dart-define 将值编译进应用。它适合非敏感配置，不适合密码、私钥或永久访问令牌，因为用户可以从应用中提取或观察这些值。真正的秘密应留在服务端或受保护的运行时配置系统中。

七、一个可执行的 CI 验证阶段

以下 Bash 脚本适合放入 Linux Runner 的验证阶段：

#!/usr/bin/env bash
set -euo pipefail

echo "== Environment =="
flutter --version
dart --version

echo "== Dependencies =="
flutter pub get

echo "== Formatting =="
dart format --output=none --set-exit-if-changed .

echo "== Static analysis =="
flutter analyze

echo "== Tests =="
flutter test --coverage

echo "== Debug build smoke check =="
flutter build apk --debug

每一步的意义不同：

flutter pub get 确认依赖可以解析；
格式检查确认提交没有未格式化代码；
flutter analyze 发现静态问题；
flutter test 验证 Dart 和 Widget 行为；
Debug 构建验证 Android 工程、插件和资源能够完成编译。

最后一步不能替代 release 构建。Debug 与 release 在签名、编译优化、资源处理和部分条件分支上不同，因此正式发布前仍必须运行 release 构建。

发布分支可以增加：

flutter build appbundle --release
sha256sum build/app/outputs/bundle/release/app-release.aab

若项目同时发布 iOS，应把 iOS 构建放到 macOS Runner；若发布 Web 或桌面，应按目标平台拆分 Job，而不是在 Linux Job 中假设所有平台都能交叉构建。

八、将流水线拆成 Job：并发、依赖和故障传播

一个合理的流水线不必所有任务串行。静态分析、单元测试和部分平台构建可以并发；签名构建和上传必须等待验证完成。

flowchart TD
    A[Checkout] --> B[依赖解析]
    B --> C[Analyze]
    B --> D[Unit/Widget Test]
    B --> E[Android Debug Build]
    C --> F[Release Gate]
    D --> F
    E --> F
    F --> G[Android Signed AAB]
    F --> H[iOS Signed IPA]
    G --> I[Artifact Verification]
    H --> I
    I --> J[Manual Approval]
    J --> K[Store Upload]

这里的 Gate 是质量门禁：只要任一必需 Job 失败，后续签名和上传 Job 就不应执行。原因不是节省时间，而是避免把一个已知失败的提交包装成看似合法的发布版本。

并发时要注意两个问题：

多个 Job 不应同时修改同一个工作区或同一个版本文件；
同一发布版本不能被两个流水线并发上传，否则可能出现相同 versionCode、相同 iOS 构建号或商店 API 冲突。

可以使用 CI 的 concurrency/group 机制，以“应用 + 发布版本”为锁。上传 Job 还应设置环境保护规则和人工审批。

产物归档的最小内容

一个可审计的发布产物不只有 .aab 或 .ipa，还应包括：

app-release.aab
sha256.txt
commit.txt
flutter-version.txt
pubspec.lock
mapping.txt                 # 若启用 Android 混淆
dSYMs 或符号文件             # iOS/原生崩溃分析需要时
build-metadata.json

build-metadata.json 可以记录：

{
  "commit": "abc123...",
  "version": "2.4.0+173",
  "flutter": "fixed-in-ci",
  "channel": "stable",
  "target": "android"
}

不要在其中写入签名密码、API Token 或服务端密钥。

九、商店上传：上传、审核、发布和安装是四个状态

移动商店流程至少有四个不同状态：

构建完成：本地产生了合法产物；
上传成功：商店接收了文件；
审核或自动检查通过：商店允许该版本进入可发布状态；
用户可获得并安装：发布范围、地区、设备兼容性和更新策略都允许用户获取。

把这四者混为一谈会导致错误判断。例如上传成功后，iOS 版本仍可能等待审核；Android 版本上传到 internal testing 轨道，也不会自动进入 production。

1. Android 商店发布

Android 常见轨道包括 internal、closed、open 和 production。发布时必须处理：

package name；
versionCode 单调递增；
AAB 签名；
Google Play Developer API 凭据；
轨道、国家/地区和发布状态；
release notes；
staged rollout 百分比。

如果当前线上是 versionCode=172，新版本使用 173。构建 173 上传后发现问题，不能重新上传另一个内容不同但仍为 173 的包；通常需要生成 174。这也是为什么构建编号不能简单使用当前时间截断或在多个分支中随意复用。

上传成功后的校验应通过商店 API 或管理控制台确认，而不是只看本地命令退出码。还应核对：

包名是否正确
轨道是否正确
versionCode 是否正确
发布状态是否为草稿、审核中或已发布
目标地区和百分比是否符合预期

2. App Store Connect

iOS 上传需要 App Store Connect 身份。现代自动化通常使用 App Store Connect API Key，而不是把 Apple 账号密码放进 CI。API Key 至少包含 Key ID、Issuer ID 和私钥文件，并应限制权限、设置有效期和轮换机制。

上传后仍需等待 App Store Connect 处理构建。处理完成后，构建才能被选择到 TestFlight 或 App Store 版本中。常见失败路径包括：

Bundle Identifier 不匹配；
CFBundleVersion 重复；
缺少隐私声明或权限说明；
签名和 Entitlements 不一致；
上传成功但构建仍在处理；
版本已提交审核，无法直接替换为另一个构建。

因此 iOS 上传 Job 需要有“等待处理并查询状态”的阶段，并对超时、拒绝和重复构建分别处理。

3. Web 和桌面发布

Web 的“上传商店”通常变成部署静态资源：

flutter build web --release --base-href /app/

随后将 build/web 发布到 Web Server、对象存储或 CDN。回滚重点是：

保留旧资源目录；
使用版本化目录和原子切换；
正确设置缓存头；
处理 Service Worker 旧缓存；
确保 HTML 与 JS/CSS 资源版本匹配。

如果只覆盖同一目录中的部分文件，浏览器可能拿到新 HTML 和旧 JS，或相反，产生难以复现的白屏。版本化目录加原子切换比“直接 rsync 覆盖生产目录”更容易恢复。

桌面发布通常上传安装器到下载站、包仓库或平台商店，回滚能力取决于渠道是否允许重新指定旧版本以及客户端更新器是否支持降级。很多更新器出于安全原因禁止降级，因此回滚常常意味着发布一个修复版本，而不是让用户安装旧版本。

十、回滚：回退发布状态，而不是简单恢复 Git 分支

回滚是让用户和系统恢复到已知可接受状态。它可能作用于不同层面：

服务端代码回滚；
远程配置或功能开关回滚；
Android/iOS 发布轨道停止或调整；
移动端重新发布一个修复包；
Web/桌面产物切回旧版本。

这些动作的速度和风险不同。移动端二进制一旦安装到用户设备，服务端可以立刻回滚，但客户端本身不会凭空消失。

1. 用版本集合表达可升级关系

设当前用户安装版本为 $v_u$ ，商店允许安装的版本集合为 $R$ ，新发布版本为 $v_n$ 。用户能否更新，不仅取决于新包是否存在，还取决于平台升级规则：

\text{可更新}(v_u, v_n) = (v_n > v_u) \land (v_n \in R) \land \text{兼容}(设备, v_n)

其中：

$v_n > v_u$ 表示 Android versionCode 或 iOS build number 满足平台的升级顺序；
$v_n \in R$ 表示该版本已经对该用户群体可见；
兼容 包括 ABI、系统版本、地区、设备能力和商店策略。

这解释了两个常见事实：

把旧版本重新上传，若构建号没有递增，商店通常拒绝；
即使停止新版本的灰度发布，已经安装新版本的用户也不会自动降级。

2. Android 的回滚路径

假设 173 出现严重崩溃：

立即暂停或停止 173 的 staged rollout，防止更多用户获得它；
通过服务端开关关闭受影响功能，若客户端支持远程配置；
检查 172 是否仍可供未更新用户获取；
修复代码并构建 174；
上传 174，先进入内部或小范围测试；
通过验证后逐步扩大 174 的发布比例。

如果 173 已经覆盖大量用户，通常不能依赖商店将其降级到 172。应发布 174，并在服务端保持对 173 的兼容，直到用户完成升级。

3. iOS 的回滚路径

iOS 的处理更受 App Store 审核和版本状态限制：

若版本处于分阶段发布，暂停后续扩散；
若版本尚未发布，取消或调整待发布状态；
若已上线，通常通过提交新的修复版本，而不是让用户直接安装旧 build；
在修复版本审核期间，用服务端开关、降级接口响应或兼容协议减小影响。

如果客户端与服务端协议不兼容，服务端不能只回滚到旧代码而忽略新客户端。生产协议应尽量采用向后兼容设计，例如新增字段可选、旧字段保留一段时间、服务端同时接受多个客户端版本。

4. Web 的回滚路径

Web 可以更快回滚，因为用户每次访问可能重新获取资源：

build/web-2.4.0+173/
build/web-2.3.9+168/
current -> build/web-2.4.0+173/

发生故障时，将 current 原子切换到旧目录。切换后仍需处理 CDN 缓存和 Service Worker；如果旧 HTML 引用的资源已经被删除，回滚仍会白屏。因此旧版本资源必须保留，直到确认所有缓存和访问路径都已过期。

十一、发布验证：从“命令成功”到“用户路径成功”

发布 Job 结束后，还应执行产物和环境验证。

Android

可使用 Android 工具检查包信息：

apkanalyzer manifest application-id build/app/outputs/bundle/release/app-release.aab

具体工具路径取决于 Android SDK 安装方式。应核对：

application ID；
version name/code；
minSdk/targetSdk；
是否包含预期 ABI 和资源；
签名是否由预期证书产生。

AAB 的最终分发 APK 由 Google Play 生成，因此本地 APK 检查不能完全替代 Play 设备兼容性测试。

iOS

在 macOS 上可通过 Xcode 工具检查归档和签名，例如使用 codesign 或 xcrun 相关命令。检查目标包括：

Bundle Identifier；
Team 和签名身份；
Entitlements；
构建号；
导出方式；
必要的符号文件是否归档。

命令名称和参数会随 Xcode 版本变化，CI 镜像应固定并在升级时重新验证。

启动冒烟测试

安装到测试设备后，至少验证：

应用可以启动
首屏资源可加载
登录或测试账户可用
核心导航可用
API 连接指向正确环境
崩溃上报能收到该版本
推送、深链、权限流程符合目标平台行为

“上传成功”不能代替这些验证，因为商店只验证包格式、签名、元数据和部分政策要求，不验证你的核心业务流程。

十二、故障诊断：先定位阶段，再判断责任边界

发布失败时，日志中应先定位它属于哪个阶段：

阶段	典型表现	首要检查
依赖解析	`pub get` 失败	SDK、锁文件、网络、私有源凭据
静态分析	analyzer issue	类型错误、lint、生成代码
测试	assertion 或 timeout	测试数据、异步等待、设备状态
Android 构建	Gradle、JDK、签名错误	JDK/AGP、SDK、keystore、variant
iOS 构建	profile、certificate、Xcode 错误	Bundle ID、Keychain、Entitlements
上传	版本重复、权限拒绝	API 凭据、包名、构建号、轨道
线上运行	崩溃、白屏、接口错误	符号文件、版本映射、服务端兼容性

诊断时应保留完整但脱敏的日志。密码、API Key、私钥、JWT 和用户数据不能通过 echo、异常堆栈或上传附件泄露。

常见误解

误解一：flutter analyze 通过就说明代码正确。
静态分析不执行网络、数据库、布局交互或原生插件行为，因此仍需测试和真实设备验证。

误解二：测试覆盖率高就说明发布安全。
覆盖率可能只是执行了代码，没有验证错误结果。高覆盖率测试同样可能全部断言错误。

误解三：Debug 能运行，Release 就一定能运行。
Release 会使用不同的签名、优化、资源和编译条件；混淆、权限、配置文件和初始化顺序问题可能只在 Release 出现。

误解四：上传成功就已经发布。
上传、处理、审核、分阶段发布和用户安装是不同状态。

误解五：回滚就是把 Git reset 到上一个提交。
Git 回退只改变源代码分支，不会撤销已安装的移动端二进制，也不会自动恢复服务端数据和外部副作用。

十三、生产取舍：自动化边界必须明确

自动化程度越高，重复操作越少，但错误发布的影响面也越大。一个较稳妥的边界是：

每次合并请求自动执行格式、分析、单元测试和 Widget 测试；
主分支自动构建未签名或受控签名的测试产物；
发布分支自动构建正式产物并归档；
上传到内部测试轨道可以自动化；
生产发布设置人工审批、并发锁和变更记录；
灰度扩大依赖崩溃率、启动成功率、关键业务指标和人工观察。

这不是 Flutter 规范强制要求，而是由移动商店的不可逆发布特性决定的经验性控制。团队可以选择完全自动部署，但必须同时具备明确的发布暂停机制、服务端降级能力、可追溯产物和经过演练的恢复路径。

最终，可靠的 Flutter CI/CD 应满足四个可验证条件：

\text{可靠交付} = \text{可重复构建} + \text{可验证行为} + \text{受保护签名} + \text{可执行恢复}

其中“可重复构建”保证同一提交不会因环境漂移产生不可解释的差异；“可验证行为”要求分析、测试和设备验证覆盖真实失败路径；“受保护签名”保证平台接受的身份和更新链路没有被泄露；“可执行恢复”则保证故障发生后不仅能发现，还能停止扩散并恢复用户可用状态。

系列导航与关联阅读

系列入口：Flutter 完整学习路线：从 Dart 与 Widget 到多端架构和应用发布
上一篇：Flutter Crash 诊断：错误捕获、符号化、版本、Breadcrumb 和隐私
下一篇：Flutter Android 发布：Gradle、签名、Flavor、AAB、权限和混淆

官方资料

本文依据 Flutter 与 Dart 官方文档重新梳理；正文与示例由 WR BLOG 编写。