$FLUTTER_ROOT/bin/cache/flutter.version.json 替換 $FLUTTER_ROOT/version

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。

因此，一個類似這樣的檔案

3.33.0-1.0.pre-1070

被一個類似這樣的檔案所取代

{
  "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 生成指令碼

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

在 172601 中被更新為

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 不再被髮出的功能

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 的示例