Flutter SDK 依赖版本固定机制：深入解析 bin/internal 目录的版本钉扎与缓存引导

Flutter 仓库中 bin/internal 目录下的文件负责为整个 Flutter SDK 钉扎（pin）各类依赖的精确版本，它决定了你的 SDK 会从 CI 制品库拉取哪一份引擎构建、哪一套 Dart SDK、哪一版 Gradle Wrapper 与字体资源。本文基于仓库中的 bin/internal/README.md 及其配套脚本源码，讲清每个 .version 文件的作用、引擎版本的三级确定逻辑，以及版本钉扎如何驱动 bin/cache 的下载与原子化更新，读完你可以独立排查 Flutter SDK 缓存引导（bootstrap）与版本解析问题。

一、bin/internal 目录的定位：SDK 依赖的版本清单

按 bin/internal/README.md 的定义：

The files in this directory specifies pinned versions of various dependencies of the flutter SDK.

即：该目录下的文件集中声明了 Flutter SDK 所依赖的各项组件的固定版本。当前仓库中该目录实际包含以下内容（可通过 bin/internal/ 目录查看）：

文件	类型	当前内容/作用
engine.version	版本钉扎（条件存在）	控制引擎编译制品的位置，见下文详解
flutter_packages.version	版本钉扎	f9b3954a...，测试用 flutter/packages 仓库的提交 SHA
canvaskit.version	版本钉扎	61aeJQ9laGfEFF_...，Web 端 CanvasKit 渲染库的制品标识
fuchsia-linux.version	版本钉扎	zvsXvTuk-...，Fuchsia/Linux 测试机固件标识
gradle_wrapper.version	制品路径	flutter_infra_release/gradle-wrapper/fd5c1f2c.../gradle-wrapper.tgz
material_fonts.version	制品路径	flutter_infra_release/flutter/fonts/3012db47.../fonts.zip
ios-deploy.version、libimobiledevice.version、libimobiledeviceglue.version、libplist.version、libusbmuxd.version、libzip.version、openssl.version	版本钉扎	各为一个提交 SHA，分别固定 iOS 部署工具、libimobiledevice 及其配套库、libzip、OpenSSL 等第三方组件版本
content_aware_hash.sh / content_aware_hash.ps1	脚本	计算“内容感知”的引擎哈希（Linux/macOS 与 Windows 各一份）
last_engine_commit.sh / .ps1	脚本	辅助脚本，用于从仓库状态推演引擎版本
update_dart_sdk.sh / .ps1	脚本	按引擎版本下载并解压 Dart SDK 到 bin/cache/dart-sdk
update_engine_version.sh / .ps1	脚本	根据仓库状态写出 bin/cache/engine.stamp 与 engine.realm
shared.sh / shared.bat	脚本	bin/flutter、bin/dart 入口共用的引导与升级逻辑
exit_with_errorlevel.bat	脚本	Windows 批处理错误码传递辅助

可以看出，.version 文件存在两种形态：一种是提交哈希/制品标识（如 flutter_packages.version 的完整 SHA），另一种直接是制品库内的相对路径（如 gradle_wrapper.version、material_fonts.version 指向 flutter_infra_release/... 下的 tgz/zip）。每种脚本都同时提供 .sh 与 .ps1 版本，脚本头部注释（如 content_aware_hash.sh 的 NOTE 块）明确要求两份实现保持逻辑一致，以保证跨平台行为统一。

二、engine.version：决定“引擎构建从哪里来”

README 对 engine.version 的说明是全文核心：

The bin/internal/engine.version file controls where to find compiled artifacts of the engine. These artifacts are compiled in the Merge Queue for every commit in the flutter repository.

两个要点：

1. 它决定引擎编译制品的查找位置——引擎（Flutter Engine）与配套 Dart SDK 的编译产物并不随 flutter/flutter 仓库分发，而是发布在 CI 制品库中，engine.version 的值就是这份制品在库中的“键”。
2. 制品由 Merge Queue 为每个进入主干的提交编译——也就是说主干上每一个 commit 都有对应的一份引擎构建可供拉取，这把“SDK 仓库状态”与“引擎二进制”绑定成了确定性关系。

值得注意的一个细节：在主干（main）分支的检出中，engine.version 并不是一个被 git 跟踪的文件（当前仓库的 bin/internal/ 目录下即不存在该文件）。它只在用户发布的 stable/beta 分支中才作为被跟踪文件存在。这一机制在 update_engine_version.sh 中体现得非常清楚，版本确定按以下优先级链执行：

# 1. 环境变量强制指定（CI 等场景临时使用某份引擎制品）
if [ -n "${FLUTTER_PREBUILT_ENGINE_VERSION}" ]; then
  ENGINE_VERSION="${FLUTTER_PREBUILT_ENGINE_VERSION}"

# 2. bin/internal/engine.version 是 git 跟踪文件（用户发布的
#    stable/beta 分支，发布版有固定引擎制品版本），优先于 git 哈希
elif [ -n "$(git -C "$FLUTTER_ROOT" ls-files bin/internal/engine.version)" ]; then
  ENGINE_VERSION="$(< "$FLUTTER_ROOT/bin/internal/engine.version")"

# 3. 兜底：用内容感知哈希推演当前分支对应的主干版本
else
  ENGINE_VERSION=$("$FLUTTER_ROOT/bin/internal/content_aware_hash.sh")
fi

确定后，脚本把结果原子地写入两个 stamp 文件（update_engine_version.sh）：

• bin/cache/engine.stamp ← 引擎制品构建所用的提交 SHA；
• bin/cache/engine.realm ← 可选的 realm（来自 FLUTTER_REALM 环境变量，用于区分 presubmit 构建等不同的制品分区）。

写入使用“临时文件 + 原子 mv”避免并行 flutter 进程间的竞态（脚本 L67 注释）。

2.1 内容感知哈希：主干分支如何找到自己的引擎构建

兜底路径调用的 content_aware_hash.sh 是整个机制中最巧妙的部分。它只对一小撮“影响引擎构建”的文件做哈希：

# DEPS: tracks third party dependencies related to building the engine
# engine: all the code in the engine folder
TRACKEDFILES=(DEPS engine bin/internal/release-candidate-branch.version)

然后以 git ls-tree $BASEREF -- DEPS engine ... | git hash-object --stdin（content_aware_hash.sh）生成一个内容哈希。其关键设计在 BASEREF 的选取上（content_aware_hash.sh）：

• 默认基于 HEAD：主干分支（main/master/stable/beta）、GitHub 合并队列分支、release candidate 分支、浅克隆、CI（LUCI_CONTEXT 存在且无当前分支）等场景直接哈希 HEAD；
• 本地开发分支基于 merge-base：如果你在自己的功能分支上开发，脚本会取当前分支与 upstream/origin 的 master 或 main 的合并基点来哈希。这样做的目的是——你在本地怎么改 engine/ 目录下的代码，都不影响 SDK 拉取引擎制品的哈希，避免“每次改引擎代码就要重建整个世界”（脚本 L31-L33 注释原话）。

由于该哈希只覆盖 DEPS、engine 等文件，只修改框架代码（packages/ 下）不会改变引擎版本，SDK 会继续复用同一份引擎构建——这正是“内容感知”命名的含义。

三、engine.stamp 如何驱动 Dart SDK 下载

bin/flutter 每次启动时，shared.sh 中的 upgrade_flutter() 函数会执行引导序列：先调用 update_engine_version.sh 刷新 engine.stamp，再按条件调用 update_dart_sdk.sh 拉取 Dart SDK（shared.sh）。整个下载 URL 的拼装在 update_dart_sdk.sh：

DART_SDK_BASE_URL="${FLUTTER_STORAGE_BASE_URL:-https://storage.googleapis.com}${ENGINE_REALM:+/$ENGINE_REALM}"
DART_SDK_URL="$DART_SDK_BASE_URL/flutter_infra_release/flutter/$ENGINE_VERSION/$DART_ZIP_NAME"

由此可以看到 engine.version（最终落入 engine.stamp）如何成为下载 URL 的路径段：<制品基址>/flutter_infra_release/flutter/<引擎版本>/dart-sdk-<系统>-<架构>.zip。这里有两个对使用者重要的可调项：

• FLUTTER_STORAGE_BASE_URL：替换制品基址，这是国内镜像加速的原理；脚本失败提示中也专门提到了镜像场景；
• FLUTTER_HOST_ARCH：覆盖宿主机架构探测。默认探测逻辑中，macOS 通过 sysctl -n hw.optional.arm64 判断（以规避 Rosetta 下 uname -m 失真，见 update_dart_sdk.sh），Linux 下区分 x86_64/riscv64/arm64。

下载后的安装同样是原子化的：先解压到 bin/cache/dart-sdk.tmp，用 find ... chmod 恢复权限位，把旧 SDK 挪到 dart-sdk.old 再 mv 新 SDK 就位，最后写 bin/cache/engine-dart-sdk.stamp 记录版本（update_dart_sdk.sh）。脚本开头的版本比对条件（L28）意味着只有 engine.stamp 与 engine-dart-sdk.stamp 不一致时才真正下载——这解释了为什么切换分支后首次 flutter 命令可能触发重新下载，而同一版本内重复运行则完全跳过。

四、flutter_packages.version：让测试确定性的下游版本钉扎

README 的第二段专门解释了 flutter_packages.version：

The bin/internal/flutter_packages.version file specifies the version of the flutter/packages repository to be used for testing. The flutter/packages repository isn't an upstream dependency of flutter/flutter; it is only used as part of the test suite for verification, and the pinned version here makes sure that tests are deterministic at each flutter/flutter commit.

三个事实要点：

1. 它不是上游依赖：flutter/packages 不是 flutter/flutter 的构建输入，只参与测试套件；
2. 用途是校验：在 flutter/flutter 的每个提交处，用同一份 packages 代码跑分析/测试，保证结果可复现（确定性）；
3. 钉的是提交 SHA：当前值为 f9b3954a113d6274e460bc3b41e775ce4917f38a。

CI 侧的消费方是 dev/bots/suite_runners/run_flutter_packages_tests.dart：flutterPackagesRunner() 先把 flutter/packages 克隆到临时目录，再通过 getFlutterPackagesVersion() 读取 bin/internal/flutter_packages.version 并 git checkout 到该提交，最后执行 flutter_plugin_tools.dart analyze --downgrade（L16-L56、L69-L84）。--downgrade 参数刻意拉取最旧可解析依赖，把 flutter/flutter 与依赖新版本发布带来的波动隔离开——与该文件“每个 flutter 提交对应固定 packages 版本”的钉扎语义互为补充。

五、其余版本文件的共同模式

除上述两个文件外，目录内其余 .version 文件遵循同样的“单一文件、单一版本、被工具链消费”的模式：

• gradle_wrapper.version / material_fonts.version：直接记录制品库相对路径（flutter_infra_release/gradle-wrapper/<sha>/gradle-wrapper.tgz、flutter_infra_release/flutter/fonts/<sha>/fonts.zip）。flutter create 生成项目时所用的 Gradle Wrapper、以及 SDK 缓存中的 Material 字体，都从这些钉扎位置获取。dev/tools/repackage_gradle_wrapper.sh 等脚本参与了该制品的重新打包流程。
• ios-deploy.version、libimobiledevice.version 等一组 SHA：固定 iOS 设备调试/部署依赖（ios-deploy、libimobiledevice 及 usbmuxd/plist 依赖库）和 libzip、OpenSSL 的构建提交，保证不同机器上 bin/cache 里缓存的第三方二进制完全一致。
• canvaskit.version：固定 Web 端 CanvasKit 渲染库的制品标识；fuchsia-linux.version：固定 Fuchsia/Linux 测试设备固件标识。

对使用者的实际意义在于：所有这些值共同把“一个 flutter/flutter 提交”映射为“一份确定的完整 SDK 内容”。只要你不手动改动这些文件，同两个相同提交的检出在任何机器上拉取到的引擎、Dart SDK、Gradle Wrapper、字体都将逐字节一致。

六、适用前提与常见排查点

结合脚本源码，使用这套机制时需要注意的前提：

1. 必须是 git 检出：shared.sh 在启动时校验 git 可用且 FLUTTER_ROOT/.git 存在，否则直接报错退出；内容感知哈希也完全建立在 git 对象之上。
2. 需要网络与 curl/unzip：update_dart_sdk.sh 缺少 curl 或 unzip 时会给出平台对应的安装建议并终止。
3. 可用的环境变量：FLUTTER_PREBUILT_ENGINE_VERSION（强制指定引擎制品版本，CI 场景）、FLUTTER_STORAGE_BASE_URL（制品基址/镜像）、FLUTTER_HOST_ARCH（架构覆盖）、FLUTTER_REALM（制品分区）。
4. 并行安全：upgrade_flutter 通过文件描述符 7 上的 flock/shlock/mkdir 三级降级锁避免多个 flutter 进程并发下载互踩（shared.sh）；engine.stamp 写入也用了临时文件加原子 mv。
5. 跨平台一致性义务：每个 .sh 脚本都要求与同名 .ps1 保持逻辑一致，这是维护该目录时需要遵守的隐含约束。

引擎制品的更宏观背景可进一步参考仓库内的 docs/tool/Engine-artifacts.md（update_engine_version.sh 的注释亦指向该文档），以及 engine/ 目录本身与 DEPS 文件——它们正是内容感知哈希的输入。

小结

bin/internal 目录是 Flutter SDK 的“版本宪法”：engine.version（或其主干分支下的内容感知哈希兜底）把每个 flutter 提交与 Merge Queue 编译出的引擎构建一一绑定，update_engine_version.sh 与 update_dart_sdk.sh 据此从 flutter_infra_release 制品库完成 Dart SDK 的确定性下载与原子替换；flutter_packages.version 则以同样的钉扎思想把测试对象锁定到固定的 packages 提交。理解这套机制，是理解 Flutter SDK 自举（bin/flutter 首次运行时的自动初始化）与 CI/制品体系之间的衔接的关键。