概述

#

flutter 工具将不再输出 $FLUTTER_ROOT/version 元数据文件,只会输出 $FLUTTER_ROOT/bin/cache/flutter.version.json

依赖 $FLUTTER_ROOT/version 存在的工具和构建脚本需要更新。

背景

#

在 2023 年$FLUTTER_ROOT/bin/cache/fluttter.version.json 被添加为一个较新的文件格式,用于替换 $FLUTTER_ROOT/version

因此,一个类似这样的文件

version
3.33.0-1.0.pre-1070

被一个类似这样的文件所取代

flutter.version.json
json
{
  "frameworkVersion": "3.33.0-1.0.pre-1070",
  "channel": "master",
  "repositoryUrl": "unknown source",
  "frameworkRevision": "be9526fbaaaab9474e95d196b70c41297eeda2d0",
  "frameworkCommitDate": "2025-07-22 11:34:11 -0700",
  "engineRevision": "be9526fbaaaab9474e95d196b70c41297eeda2d0",
  "engineCommitDate": "2025-07-22 18:34:11.000Z",
  "engineContentHash": "70fb28dde094789120421d4e807a9c37a0131296",
  "engineBuildDate": "2025-07-22 11:47:42.829",
  "dartSdkVersion": "3.10.0 (build 3.10.0-15.0.dev)",
  "devToolsVersion": "2.48.0",
  "flutterVersion": "3.33.0-1.0.pre-1070"
}

同时生成这两个文件会造成技术债务。

迁移指南

#

大多数 Flutter 开发者不解析或使用此文件,但自定义工具或 CI 配置可能会。

例如,Flutter 团队自己的 api.flutter.dev 生成脚本

post_processe_docs.dart
dart
final File versionFile = File('version');
final String version = versionFile.readAsStringSync();

172601 中被更新为

dart
final File versionFile = File(path.join(checkoutPath, 'bin', 'cache', 'flutter.version.json'));
final String version = () {
  final Map<String, Object?> json =
      jsonDecode(versionFile.readAsStringSync()) as Map<String, Object?>;
  return json['flutterVersion']! as String;
}();

临时选择退出 $FLUTTER_ROOT/version 不再被发出的功能

sh
flutter config --no-enable-omit-legacy-version-file

时间线

#

已发布到版本:3.33.0-1.0.pre-1416
稳定版发布:尚未发布

在此更改落地后的一个稳定版发布中,--no-enable-omit-legacy-version-file 将被移除。

参考资料

#

相关问题

  • 问题 171900,其中 FLUTTER_ROOT/version 被列入移除计划

相关 PR

  • PR 124558,其中 flutter.version.json 被添加为新格式
  • PR 172601,一个将脚本迁移到使用 flutter.version.json 的示例