如何使用 Codemagic 构建一套完整的 Flutter CI/CD 流程：从代码质量检测环节到自动化应用发布流程

测试完成后，lcov会解析由flutter test --coverage生成的代码覆盖率报告，并提取出具体的行覆盖百分比。如果这个百分比低于70%，构建过程就会失败，并会显示明确的错误信息。这个阈值需要你的团队共同确定，但对于大多数项目来说，70%确实是一个合理的标准。

发布流程

Codemagic内置了电子邮件通知功能。你不需要在CI日志中编写echo命令，只需在工作流程中指定接收邮件的人选，Codemagic就会负责发送通知。无论是成功还是失败的情况，都会被及时告知。

Android构建流程

Android构建流程通过使用Codemagic的环境变量组和条件脚本，在同一个工作流程定义中处理三种不同的环境。具体来说，它会根据触发构建的分支不同，而采取不同的操作方式。

  android-pipeline:
    name: Android构建与发布
    max_build_duration: 60
    instance_type: linux_x2

    triggering:
      events:
        - push
      branch_patterns:
        - pattern: develop
          include: true
        - pattern: staging
          include: true
        - pattern: production
          include: true

    environment:
      flutter: stable
      android_signing:
        - android_keystore
      groups:
        - staging_secrets
        - production_secrets
        - firebase_credentials
        - sentrycredentials

    scripts:
      - name: 安装依赖项
        script: flutter pub get

      - name: 确定当前环境
        script: |
          BRANCH=$(git rev-parse --abbrev-ref HEAD)
          if [ "$BRANCH" = "develop" ]; then
            echo "ENV=dev" >>> $CM_ENV
          elif [ "$BRANCH" = "staging" ]; then
            echo "ENV=staging" >>> $CM_ENV
          else
            echo "ENV=production" >>> $CM_ENV
          fi

      - name: 生成环境配置文件
        script: |
          if [ "$ENV" = "dev" ]; then
            ./scripts/generate_config.sh dev "https://dev.api.example.com" "dev_dummy_key"
          elif [ "$ENV" = "staging" ]; then
            ./scripts/generate_config.sh staging "\(STAGING_BASE_URL)STAGING_API_KEY"
          else
            ./scripts/generate_config.sh production "$(PROD_BASE_URL)PROD_API_KEY"
          fi

      - name: 构建Android应用程序
        script: |
          if [ "$ENV" = "production" ]; then
            flutter build appbundle --release \
              --obfuscate \
              --split-debug-info=build/symbols
          else
            flutter build appbundle --release
          fi

      - name: 将应用发布到Firebase App Distribution平台
        script: |
          if [ "$ENV" = "dev" ] || [ "$ENV" = "staging" ]; then
            firebase appdistribution:distribute \
              build/app/outputs/bundle/release/app-release.aab \
              --app "$FIREBASEANDROID_APP_ID" \
              --groups "$FIREBASE_groups" \
              --token "$FIREBASE_TOKEN"
          fi

      - name: 提交应用到Play Store
        script: |
          if [ "$ENV" = "production" ]; then
            echo "$GOOGLE_PLAY_SERVICE_ACCOUNT_JSON" > /tmp/service_account.json
            flutter pub global activate fastlane 2>/dev/null || true
            fastlane supply \
              --aab build/app/outputs/bundle/release/app-release.aab \
              --json_key /tmp/service_account.json \
              --package_name com.your.package \
              --track production
          fi

      - name: 上传Sentry符号文件
        script: |
          if [ "$ENV" = "production" ]; then
            ./scripts/upload_symbols.sh $(git rev-parse --short HEAD)
          fi

    artifacts:
      - build/app/outputs/bundle/release/app-release.aab
      - build/symbols“

    publishing:
      email:
        recipients:
          - your-team@example.com
        notify:
          success: true
          failure: true

以下是各部分的功能及其设计原因。

android_signing

这是Codemagic最实用的功能之一。无需手动解码Base64格式的密钥库并将其写入脚本文件中，您可以直接将密钥库文件上传到Codemagic的加密存储系统中，具体路径为“Teams → Code signing identities → Android keystores”。您只需为该密钥库指定一个参考名称（例如android_keystore），Codemagic会在构建脚本运行之前自动完成解码、存储以及生成key.properties文件的工作。

这一设计有效避免了与签名相关的各种构建错误。

groups

Codemagic允许您在团队设置的环境变量部分将各类敏感信息组织成不同的组。您无需单独声明每条敏感信息，而是可以通过引用这些组来使用它们。这里使用的组包括：

• staging_secrets：包含STAGING_BASE_URL和STAGING_API_KEY

• production_secrets：包含PROD_BASE_URL和PROD_API_KEY

• firebase_credentials：包含FIREBASE_TOKEN、FIREBASE_ANDROID_APP_ID和FIREBASE_groups

• sentrycredentials：包含SENTRY_AUTH_TOKEN、SENTRY_ORG和SENTRY_Project

通过$CM_ENV进行环境变量检测

Codemagic通过$CM_ENV变量提供了一个特殊的文件路径。如果您在该文件中写入KEY=VALUE这样的内容，那么这个变量将在同一构建过程中的所有后续脚本步骤中被使用。这就是如何将分支名称转换成其他流程组件能够识别的环境变量的。

构建阶段的区分

生产环境的构建会使用--obfuscate和这两个参数；而开发环境和测试环境的构建则会省略这些参数，以便加快编译速度并使本地堆栈跟踪信息更易于阅读。

Firebase应用的发布流程

Firebase CLI负责将开发环境和测试环境的构建版本分发给测试人员。由于Codemagic的Linux服务器上已经预装了Node.js，因此如果您还没有安装Firebase CLI，可以通过npm install -g firebase-tools来安装它；之后也可以通过npx命令来使用它。

应用提交到Play Store

生产环境的应用程序包会通过Fastlane的supply命令上传到Play Store。服务账户的相关信息会从环境变量中读取并保存到一个临时文件中，然后直接传递给Fastlane。请将com.your.package替换为您实际的应用程序ID。

artifacts

“Artifacts”部分用于指定在构建完成后需要保留哪些文件。这些文件可以在Codemagic的构建监控界面中下载获得。此外，调试符号也会被保存在这里，这样在需要重新执行自动化构建流程时，就可以方便地使用这些调试信息了。

iOS构建流程

在Codemagic平台上，iOS项目的构建过程充分展现了该平台的优势。在通用运行环境中进行苹果代码签名时，需要经过一系列复杂的操作，包括使用`security`命令、导入证书以及配置发布配置文件等。而Codemagic通过其内置的签名集成功能，能够自动完成所有这些步骤。

  ios-pipeline:
    name: iOS构建与发布
    max_build_duration: 90
    instance_type: mac_mini_m2

    triggering:
      events:
        - push
      branch_patterns:
        - pattern: develop
          include: true
        - pattern: staging
          include: true
        - pattern: production
          include: true

    environment:
      flutter: stable
      ios_signing:
        distribution_type: app_store
        bundle_identifier: com.your.bundle.id
      groups:
        - staging_secrets
        - production_secrets
        - app_store_credentials
        - sentrycredentials

    scripts:
      - name: 安装依赖项
        script: flutter pub get

      - name: 安装Fastlane相关依赖项
        script: |
          cd ios
          gem install bundler --user-install
          bundle install

      - name: 判断当前环境
        script: |
          BRANCH=$(git rev-parse --abbrev-ref HEAD)
          if [ "$BRANCH" = "develop" ]; then
            echo "ENV=dev" >> $CM_ENV
          elif [ "$BRANCH" = "staging" ]; then
            echo "ENV=staging" >>&> $CM_ENV
          else
            echo "ENV=production" >>&> $CM_ENV
          fi

      - name: 生成环境配置文件
        script: |
          if [ "$ENV" = "dev" ]; then
            ./scripts/generate_config.sh dev "https://dev.api.example.com" "dev_dummy_key"
          elif [ "$ENV" = "staging" ]; then
            ./scripts/generate_config.sh staging "$(STAGING_BASE_URL)STAGING_API_KEY"
          else
            ./scripts/generate_config.sh production "$(PROD_BASE_URL)PROD_API_KEY"
          fi

      - name: 构建iOS版本（开发环境，不进行代码签名）
        script: |
          if [ "$ENV" = "dev" ]; then
            flutter build ios --release --no-codesign
          fi

      - name: 在Staging环境中构建并上传至TestFlight
        script: |
          if [ "$ENV" = "staging" ]; then
            flutter build ipa --release \
              --export-options-plist=/Users/builder/export_options.plist
            cd ios && bundle exec fastlane beta
          fi

      - name: 在Production环境中构建并发布至App Store
        script: |
          if [ "$ENV" = "production" ]; then
            flutter build ipa --release \
              --obfuscate \
              --split-debug-info=build/symbols \
              --export-options-plist=/Users/builder/export_options.plist
            cd ios && bundle exec fastlane release
          fi

      - name: 上传Sentry所需的符号文件
        script: |
          if [ "$ENV" = "production" ]; then
            ./scripts/upload_symbols.sh $(git rev-parse --short HEAD)
          fi

    artifacts:
      - build/ios/ipa/*.ipa
      - build/symbols/**
      - /tmp/xcodebuild_logs/*.log

    publishing:
      app_store_connect:
        api_key: $APP_STORE_CONNECT_PRIVATE_KEY
        key_id: $APPSTORE_CONNECT_KEY_IDENTIFIER
        issuer_id: $APP STORE_CONNECT_ISSUER_ID
        submit_to_testflight: true
        submit_to_app_store: false
      email:
        recipients:
          - your-team@example.com
        notify:
          success: true
          failure: true

以下是Android开发流程与iOS开发流程之间的不同之处，以及原因说明。

mac_mini_m2

iOS项目的构建需要使用Xcode，因此必须运行在macOS系统上。Codemagic提供了基于Apple Silicon技术的Mac Mini设备。对于Flutter项目和Xcode的开发任务来说，这些设备比基于Intel处理器的机器要快得多，而且Codemagic会根据需求自动配置这些设备，用户无需进行任何基础设施管理。

ios_signing

ios_signing这一环节实际上替代了传统的密钥链设置流程。用户只需将分发证书和配置文件上传到Codemagic的系统中，然后在团队设置中指定相关参数。distribution_type: app_store表示使用App Store的分发签名机制，而bundle_identifier则用于将证书与具体的应用程序关联起来。在脚本执行之前，Codemagic会自动在构建机器上安装这些证书和配置文件。

整个过程中不需要手动运行任何security命令，也不需要创建密钥链或进行Base64解码操作，所有这些步骤都由Codemagic内部完成。

flutter build ipa

在iOS平台上，构建后的输出文件为.ipa格式，而不是.aab格式。当使用flutter build ipa命令并提供相应的export options plist文件时，Xcode会根据该plist文件中的指令来处理签名和打包工作。Codemagic会根据用户设置的ios_signing参数自动生成这个plist文件，并将其保存在/Users/builder/export_options.plist路径下。

Fastlane工作流

Codemagic会通过Bundler将Fastlane工具安装到ios/目录中，然后根据当前环境自动选择相应的工作流程。beta工作流程用于将构建结果上传到TestFlight平台，而release工作流程则用于将应用提交到App Store。

publishing.app_store_connect

Codemagic内置了与App Store Connect平台对接的功能。用户只需在配置文件中指定API凭证，其余步骤都由Codemagic自动完成。submit_to_testflight: true这个选项表示构建完成后，测试版本会自动推送到TestFlight平台上；而对于正式发布版本，则需要将submit_to_app_store参数设置为true。

Xcode日志作为构建结果

路径/tmp/xcodebuild_logs/*.log中存储的原始Xcode构建日志可以作为可下载的文件被保存下来。当iOS项目的构建失败时，如果Codemagic控制面板显示的错误信息不够详细，这些日志就能帮助用户找到问题的真正原因。

环境变量与保密信息的配置方法

所有保密信息都可以在Codemagic的“团队”→“环境变量”设置中进行配置。请将这些信息按逻辑分类，以便在YAML配置文件中清晰地引用它们。

staging_secrets组

production_secrets组

firebase_credentials组

app_store_credentials组

sentry_credentials组

对于Android代码签名，请直接将你的密钥库上传到“Teams → Code signing identities → Android keystores”中，而不要将其存储为环境变量。

对于iOS，請将你的分发证书和配置文件上传到“Teams → Code signing identities → iOS certificates”中。

端到端流程

当完整的codemagic.yaml配置就绪后，下面就是典型发布周期中各项操作的完整流程。

开发人员完成某个功能的开发后，会向develop分支提交一个Pull Request。Codemagic会检测到这个请求事件，并在Linux服务器上触发pr-quality-gate工作流程。质量检查脚本会执行格式化、分析、测试以及代码覆盖率检查。如果有任何环节失败，Codemagic会将构建结果标记为失败状态，并向团队发送电子邮件，此时该Pull Request还不能被视为已通过审核。开发人员修复问题后，Codemagic会重新运行检查流程，只有当所有测试都通过后，该Pull Request才会继续进入后续处理阶段。

一旦Pull Request被合并到develop分支中，android-pipeline和ios-pipeline这两个流程会同时启动。它们都会将develop分支作为源代码分支，将其映射到开发环境，插入临时配置信息，生成未签名的发布版本文件，然后将其上传到Firebase App Distribution平台。测试人员可以在合并操作完成后的几分钟内立即使用这些可安装的构建版本进行测试。

develop分支被合并到staging分支后，同样的两个平台构建流程会再次被执行。这一次，系统中会插入真实的配置信息，比如staging环境的API地址和加密密钥。Android版本的软件会使用Codemagic自动管理的密钥库进行签名处理；iOS版本的软件则会通过Fastlane的beta通道上传到TestFlight平台。Codemagic内置的App Store Connect发布工具会负责完成TestFlight上的上传流程。这样一来，质量保障团队就可以使用这些经过正确签名和配置的staging版本来进行测试了。

staging环境被提升为production环境后，构建流程会进入发布模式。此时系统会使用生产环境的配置信息；Android版本的软件在打包时会去除调试符号，并将这些符号保存到build/symbols文件夹中；iOS版本的软件则会在构建过程中启用混淆处理，然后通过flutter build ipa命令生成IPA文件。这两个平台的构建流程都会调用upload_symbols.sh脚本，该脚本会使用当前的提交哈希值来确保Sentry发布的版本与实际发布的代码完全一致。Android应用的包会通过Fastlane上传到Play Store；iOS应用的IPA文件则会通过Codemagic内置的发布工具上传到App Store Connect。团队会收到相应的成功通知。