Flutter Cross Toolchain

在一台 macOS 设备上，用一个命令生成 Flutter 的 Android、macOS、Linux 和 Windows 发布产物。

它不替换 Dart 前端，也不依赖 JIT。Dart 代码仍由 Flutter 自带的 frontend_server 生成 kernel，发布版由 macOS 上运行的 gen_snapshot 编译成目标架构 AOT ELF；Linux/Windows 原生 Runner 在 GitHub Actions 对应系统上预构建，之后按 Flutter engine revision 下载和复用。换句话说，昂贵且受宿主系统限制的 C++/CMake/MSVC 构建被移出了日常发包路径。

当前支持

目标	默认架构	构建方式
Android	arm64	macOS 上执行官方 flutter build apk
macOS	arm64	macOS 上执行官方 flutter build macos
Linux	x86_64	macOS 上交叉 AOT + 预构建 Linux Runner
Windows	x86_64	macOS 上交叉 AOT + 预构建 Windows Runner

CLI 还定义了 Linux/Windows arm64 target triple，供以后上传自定义 arm64 pack；仓库自带的预构建工作流目前生成 x86_64 pack。

安装

dart pub global activate --source path /path/to/flutter_cross_toolchain
flutter_cross targets
flutter_cross doctor --project /path/to/your_app

将 flutter_cross.example.json 复制到 Flutter 应用根目录为 flutter_cross.json，并把 repository 改成你运行目标包工作流的 GitHub 仓库：

{
  "repository": "YOUR_GITHUB_OWNER/flutter-cross-toolchain",
  "output": "build/flutter_cross",
  "targetFile": "lib/main.dart"
}

也可以不创建配置文件，直接传 --repository owner/repo。

构建

四个平台一起构建：

flutter_cross build \
  --project /path/to/your_app \
  --repository owner/flutter-cross-toolchain

只构建某个目标：

flutter_cross build -p /path/to/your_app -t linux
flutter_cross build -p /path/to/your_app -t windows
flutter_cross build -p /path/to/your_app -t android,macos

常用发布参数：

flutter_cross build -p /path/to/your_app \
  --dart-define=API_ENV=production \
  --obfuscate \
  --split-debug-info=build/symbols

默认输出：

build/flutter_cross/
├── aarch64-linux-android/
├── aarch64-apple-darwin/
├── x86_64-unknown-linux-gnu/
└── x86_64-pc-windows-msvc/

首次 Linux/Windows 构建会按当前 Flutter SDK 的 engine.stamp 自动下载：

flutter-cross-darwin-x64-<target-triple>.tar.gz
flutter-cross-darwin-x64-<target-triple>.tar.gz.sha256

发布 tag 固定为 engine-<engine-revision>。revision 不一致时 CLI 会拒绝使用，避免 Dart VM/AOT ABI 混用。也可完全离线使用本地包：

flutter_cross build -p app -t linux --no-fetch \
  --pack x86_64-unknown-linux-gnu=/packs/linux

生成目标包

1. 把本项目推送到 GitHub。
2. 在 Actions 中运行 Build Flutter target packs。
3. flutter_ref 填应用正在使用的 Flutter tag 或 branch。
4. 第一次可保持 publish=false 检查 Actions artifact；确认后用 publish=true 发布到 engine-REVISION release。

工作流分别在 Intel macOS、Ubuntu 和 Windows Runner 上：

• 从同一 Flutter ref 获取完全一致的 engine revision；
• 取 macOS x64 release gen_snapshot，分别放入 Flutter tools 期望的 Linux/Windows engine artifact 路径；
• 把目标 Runner 构建使用的 runtime、headers 和 ICU 等 engine artifacts 一并封装，满足 flutter assemble 的完整输入；
• 编译无插件的通用 Linux/Windows release Runner；
• 生成 pack.json、tar.gz 和 SHA-256 文件；
• 可选上传到 GitHub Release。

Apple Silicon 构建机需要 Rosetta 2，因为当前包中的 AOT 编译器是 macOS x86_64 可执行文件：

softwareupdate --install-rosetta --agree-to-license

依赖边界

这个方案支持纯 Dart 包、Flutter assets、字体、Dart compile-time defines，以及不需要改 Runner 的代码。平台插件包含 C/C++、CMake、CocoaPods、Gradle 或 MSVC 代码时：

• Android/macOS 仍按 Flutter 官方方式构建，插件可正常参与；
• Linux/Windows 默认通用 Runner 不包含你的原生插件；请把依赖替换成纯 Dart/FFI 方案，或修改工作流，让 Runner 工程携带并预构建这些插件，再发布自己的目标包。

FFI 动态库也必须提前提供目标系统版本并作为 asset/安装文件一起分发。最终代码签名、公证、安装包（DMG/MSIX/deb/rpm）属于产物之后的发布步骤，本工具当前输出可运行 bundle/APK/.app，不代替签名基础设施。

命令

flutter_cross targets
flutter_cross doctor [--strict]
flutter_cross fetch  --target <target>
flutter_cross build  --target <target>
flutter_cross pack verify --path <dir> --target <target> --engine-revision <rev>

使用 flutter_cross <command> --help 查看全部选项。

实现原理与 target pack 协议分别见 docs/architecture.md 和 docs/target-pack-v1.md。

安全与可复现性

• 每个 pack 同时校验 schema、target triple、host triple 与 engine revision。
• 下载后强制校验同名 .sha256。
• pack 只覆盖 Flutter cache 中明确列出的目标 engine artifact 目录。
• 每份产物写入 flutter_cross_build.json，记录 target、engine revision 和 UTC 构建时间。

开源协议

Flutter Cross Toolchain 自有代码采用 BSD 3-Clause 协议，与 Flutter 上游保持一致。Target pack 中的 Flutter、Dart 和其他第三方组件仍遵循各自的 协议，详见 THIRD_PARTY_NOTICES.md。重新分发二进制 产物时应保留包内的许可与 notices 文件。