Back to Details

dart-sdk-changelog

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Dart SDK Changelog & Version Feature Guide (Dart 1.x to Modern Dart 3.x)

Dart SDK 变更日志与版本特性指南（Dart 1.x 至现代 Dart 3.x）

This skill provides an authoritative, structured guide to Dart language features, core library APIs, tooling changes, version requirements, experimental feature flags (
--enable-experiment
), static metaprogramming (Macros & Augmentations), and legacy modernization runbooks sourced directly from the official Dart SDK CHANGELOG.
本技能提供一份权威、结构化的指南，涵盖Dart语言特性、核心库API、工具变更、版本要求、实验特性标志（
--enable-experiment
）、静态元编程（Macros & Augmentations）以及遗留代码现代化手册，所有内容均直接源自官方Dart SDK CHANGELOG。

🎯 Parent Guide: How to Find the 
minSdk
for Any Dart Feature or API

🎯 核心指南：如何查找任意Dart特性或API的
minSdk

When writing or reviewing Dart code, selecting the correct minimum SDK lower bound (
minSdk
) in 
pubspec.yaml
is essential to ensure syntax and core APIs compile across target environments.
在编写或审核Dart代码时，在
pubspec.yaml
中选择正确的最低SDK下限（
minSdk
）至关重要，这能确保语法和核心API在目标环境中正常编译。

1. Language Version vs. SDK Version

1. 语言版本 vs. SDK版本

  • Language Version (
    major.minor
    )    : In 
    pubspec.yaml
    , the lower bound of 
    environment.sdk
    (for example 
    ^3.13.0
    or 
    >=3.12.0 <4.0.0
    ) dictates which language grammar and compiler semantics are enabled.
    • Patch numbers (
      .1
      , 
      .2
      ) do not affect language grammar.
    • Using a Dart 3.13 feature (like Primary Constructors) requires 
      sdk: '^3.13.0'
      .
  • Core Library APIs: Methods and classes (for example 
    Future.pause
    , 
    List.unmodifiableOf
    ) are added in specific SDK versions.
  • Per-file override: A file can specify 
    // @dart = 3.12
    on line 1 to force an earlier language version.
  • 语言版本（
    major.minor
    ）    ：在
    pubspec.yaml
    中，
    environment.sdk
    的下限（例如
    ^3.13.0
    或
    >=3.12.0 <4.0.0
    ）决定了启用的语言语法和编译器语义。
    • 补丁版本（
      .1
      、
      .2
      ）不会影响语言语法。
    • 使用Dart 3.13的特性（如主构造函数）需要设置
      sdk: '^3.13.0'
      。
  • 核心库API：方法和类（例如
    Future.pause
    、
    List.unmodifiableOf
    ）是在特定SDK版本中新增的。
  • 单文件覆盖：文件的第1行可以指定
    // @dart = 3.12
    ，强制使用更早的语言版本。

2. Fast 
minSdk
Language Feature Matrix

2. 快速查询
minSdk
的语言特性矩阵

Feature / SyntaxMinimum SDKExample SyntaxReference
Primary Constructors
3.13.0
class Point(var int x, var int y);
/ 
this : assert(...)
3.13 Guide
Constructor Keyword Shorthands
3.13.0
new(this.x);
/ 
factory clone(...) => ...;
3.13 Guide
Private Named Parameters
3.12.0
Point({required this._x, required this._y});
3.12 Guide
Wildcard Variables (
_
)
3.7.0
var (_, b) = pair;
/ 
void fn(int _, int _)
3.7 Guide
Type Inference Using Bounds
3.7.0
Inferred types respect type parameter bounds3.7 Guide
Digit Separators
3.6.0
1_000_000
, 
0x4000_0000
, 
0.000_001
3.6 Guide
Extension Types
3.3.0
extension type Meters(int value) {}
3.0-3.5 Guide
Private Field Promotion
3.2.0
if (_privateFinalField != null) { ... }
3.0-3.5 Guide
Records (Tuples)
3.0.0
(int, String) pair = (1, 'a');
3.0-3.5 Guide
Pattern Matching & Destructuring
3.0.0
var (a, b) = pair;
/ 
switch (val) { case ... }
3.0-3.5 Guide
Switch Expressions
3.0.0
var s = switch (e) { 0 => 'a', _ => 'b' };
3.0-3.5 Guide
If-Case Statements & Elements
3.0.0
if (json case {'id': int id}) ...
3.0-3.5 Guide
Sealed Classes & Exhaustiveness
3.0.0
sealed class State {}
3.0-3.5 Guide
Class Modifiers (
base
, 
interface
, 
final
)
3.0.0
interface class Api {}
/ 
final class Token {}
3.0-3.5 Guide
100% Sound Null Safety Enforced
3.0.0
Non-null-safe mode disallowed3.0-3.5 Guide
Super-Initializer Parameters
2.17.0
SubClass(super.name, {super.key});
Dart 2 Milestones
Enhanced Enums
2.17.0
enum Status { ok(200); final int c; const Status(this.c); }
Dart 2 Milestones
Named Arguments Anywhere
2.17.0
fn(1, named: 'a', 2);
Dart 2 Milestones
Constructor Tear-Offs
2.15.0
List.filled
, 
Point.new
Dart 2 Milestones
Triple-Shift Operator (
>>>
)
2.14.0
int result = a >>> b;
Dart 2 Milestones
Generic Type Aliases (
typedef
)
2.13.0
typedef JsonMap = Map<String, dynamic>;
Dart 2 Milestones
Sound Null Safety (
?
, 
late
, 
!
)
2.12.0
Sound static non-nullable typesDart 2 Milestones
Extension Methods
2.7.0
extension on String { ... }
Dart 2 Milestones
Spread Operators (
...
, 
...?
)
2.3.0
[...list1, ...?maybeList]
Dart 2 Milestones
Collection 
if
and 
for
2.3.0
[if (cond) a, for (var x in l) x * 2]
Dart 2 Milestones
Sound Type System & Optional 
new
2.0.0
Static sound types replace dynamic checksDart 2 Milestones
👉 For deep-dive and verification procedures, see How to Find minSdk and the Full Version Matrix.
特性/语法最低SDK版本示例语法参考文档
主构造函数（Primary Constructors）
3.13.0
class Point(var int x, var int y);
/ 
this : assert(...)
3.13指南
构造函数关键字简写（Constructor Keyword Shorthands）
3.13.0
new(this.x);
/ 
factory clone(...) => ...;
3.13指南
私有命名参数（Private Named Parameters）
3.12.0
Point({required this._x, required this._y});
3.12指南
通配符变量（
_
）
3.7.0
var (_, b) = pair;
/ 
void fn(int _, int _)
3.7指南
使用边界进行类型推断（Type Inference Using Bounds）
3.7.0
推断类型遵循类型参数边界3.7指南
数字分隔符（Digit Separators）
3.6.0
1_000_000
, 
0x4000_0000
, 
0.000_001
3.6指南
扩展类型（Extension Types）
3.3.0
extension type Meters(int value) {}
3.0-3.5指南
私有字段提升（Private Field Promotion）
3.2.0
if (_privateFinalField != null) { ... }
3.0-3.5指南
记录（Records，即元组）
3.0.0
(int, String) pair = (1, 'a');
3.0-3.5指南
模式匹配与解构（Pattern Matching & Destructuring）
3.0.0
var (a, b) = pair;
/ 
switch (val) { case ... }
3.0-3.5指南
Switch表达式（Switch Expressions）
3.0.0
var s = switch (e) { 0 => 'a', _ => 'b' };
3.0-3.5指南
If-Case语句与元素（If-Case Statements & Elements）
3.0.0
if (json case {'id': int id}) ...
3.0-3.5指南
密封类与穷尽性检查（Sealed Classes & Exhaustiveness）
3.0.0
sealed class State {}
3.0-3.5指南
类修饰符（
base
、
interface
、
final
）
3.0.0
interface class Api {}
/ 
final class Token {}
3.0-3.5指南
强制100%可靠空安全
3.0.0
不允许非空安全模式3.0-3.5指南
超初始化参数（Super-Initializer Parameters）
2.17.0
SubClass(super.name, {super.key});
Dart 2里程碑
增强枚举（Enhanced Enums）
2.17.0
enum Status { ok(200); final int c; const Status(this.c); }
Dart 2里程碑
任意位置的命名参数（Named Arguments Anywhere）
2.17.0
fn(1, named: 'a', 2);
Dart 2里程碑
构造函数剥离（Constructor Tear-Offs）
2.15.0
List.filled
, 
Point.new
Dart 2里程碑
三位移位运算符（
>>>
）
2.14.0
int result = a >>> b;
Dart 2里程碑
泛型类型别名（
typedef
）
2.13.0
typedef JsonMap = Map<String, dynamic>;
Dart 2里程碑
可靠空安全（
?
、
late
、
!
）
2.12.0
可靠的静态非空类型Dart 2里程碑
扩展方法（Extension Methods）
2.7.0
extension on String { ... }
Dart 2里程碑
展开运算符（
...
、
...?
）
2.3.0
[...list1, ...?maybeList]
Dart 2里程碑
集合
if
和
for
2.3.0
[if (cond) a, for (var x in l) x * 2]
Dart 2里程碑
可靠类型系统与可选
new
关键字
2.0.0
静态可靠类型替代动态检查Dart 2里程碑
👉 如需深入了解和验证步骤，请查看如何查找minSdk和完整版本矩阵。

⚡ Subskill Spotlights

⚡ 子技能亮点

Subskill: Augmentations & Static Metaprogramming (Macros)

子技能：增强功能（Augmentations）与静态元编程（Macros）

  • Augmentation Syntax: Declare 
    augment class
    , 
    import augment
    , and wrap methods using 
    augmented()
    .
  • Macro Phases: Understand Type, Declaration, and Definition macro execution in the analysis server.
  • In-Memory Code Gen: Eliminate 
    build_runner
    with zero-disk 
    .g.dart
    pollution. 👉 Read the full Macros & Augmentations Guide.
  • 增强语法：声明
    augment class
    、
    import augment
    ，并使用
    augmented()
    包裹方法。
  • 宏阶段：了解分析服务器中Type、Declaration和Definition宏的执行流程。
  • 内存代码生成：无需
    build_runner
    ，避免磁盘上生成
    .g.dart
    文件造成污染。 👉 阅读完整的Macros与增强功能指南。

Subskill: Experimental Features & Compiler Flags (
--enable-experiment
)

子技能：实验特性与编译器标志（
--enable-experiment
）

  • Enabling Experiments: Configure 
    analysis_options.yaml
    (
    analyzer.enable-experiment
    ), CLI flags (
    dart --enable-experiment=...
    ), and VS Code settings.
  • Release Pipeline: Understand the graduation path across Beta preview, Stable-gated, and Stable-ungated tiers. 👉 Read the full Experimental Features Guide.
  • 启用实验特性：配置
    analysis_options.yaml
    （
    analyzer.enable-experiment
    ）、CLI标志（
    dart --enable-experiment=...
    ）和VS Code设置。
  • 发布流程：了解实验特性从Beta预览版、稳定版 gated 到稳定版 ungated 的升级路径。 👉 阅读完整的实验特性指南。

Subskill: Rescuing Legacy Codebases (Dart 1.x & Pre-2.12 to Modern Dart)

子技能：修复遗留代码库（从Dart 1.x & 2.12之前版本升级到现代Dart）

  • Sound Null Safety Migration: Transform 
    @required
    annotations, uninitialized nullable fields, and defensive runtime assertions.
  • Dependency Upgrades: Modernize 
    pubspec.yaml
    environment bounds and replace deprecated legacy packages (
    pedantic
    , 
    tuple
    , etc.). 👉 Read the full Legacy Codebase Rescue Guide.
  • 可靠空安全迁移：转换
    @required
    注解、未初始化的可空字段和防御性运行时断言。
  • 依赖升级：更新
    pubspec.yaml
    的环境约束，替换已废弃的遗留包（如
    pedantic
    、
    tuple
    等）。 👉 阅读完整的遗留代码库修复指南。

📚 Table of Contents (TOC) & Version Archive

📚 目录（TOC）与版本档案

Release / GuideFocus AreaKey AdditionsReference Document
Macros & AugmentationsMetaprogramming
augment
, 
augmented()
, 
import augment
, 
@JsonCodable()
, 3-phase macro pipeline		Macros & Augmentations Guide
Experimental FeaturesCompiler Flags
--enable-experiment
, Beta preview vs stable-gated release tiers, graduation matrix		Experiments Guide
Legacy RescueMigration RunbookDart 1.x/2.x to Modern 3.x modernization pipeline, null-safety bridge, package replacementsRescue Guide
Dart 3.14FFI & JS Interop
NativeFinalizer.callback
, fast primitive JS array conversions		3.14 Reference
Dart 3.13Language & RuntimePrimary constructors, 
this
constructor body, 
new
/
factory
shorthands, 
Future.pause
, synchronous isolates		3.13 Reference
Dart 3.12Language & ToolingPrivate named parameters (
Point({this._x})
), 
RegExp
spans, 
dart run <pkg>@<ver>
3.12 Reference
Dart 3.11Platform & PubWindows Unix domain sockets, Workspace globs (
pkgs/*
), 
dart pub cache gc
3.11 Reference
Dart 3.10Extensibility & CLIAnalyzer plugins stable, Hooks (native assets) stable, 
dart install
, 
@Deprecated
constructors		3.10 Reference
Dart 3.9Analysis & PubAOT analysis server, git tag version solving, null-safety assumptions in flow analysis3.9 Reference
Dart 3.8Formatter & DocsDoc imports (
@docImport
), tall formatter trailing comma preservation, 
Iterable.withIterator
3.8 Reference
Dart 3.7Language & FormatterWildcard variables (
_
), inference using bounds, tall style formatter default, legacy web deprecations		3.7 Reference
Dart 3.6Language & PubDigit separators (
1_000_000
), Pub workspaces, 
dart pub bump
3.6 Reference
Dart 3.0 – 3.5Foundation & Major FeaturesRecords, Patterns, Switch Expressions, Sealed Classes, Class Modifiers, Extension Types, Field Promotion, Wasm3.0–3.5 Reference
Dart 2.0 – 2.19Historical MilestonesSound Null Safety (2.12), Enhanced Enums & Super-Params (2.17), Extension Methods (2.7), Spreads (2.3), Sound Type System (2.0)Dart 2 Milestones
版本/指南重点领域主要新增内容参考文档
Macros与增强功能元编程
augment
、
augmented()
、
import augment
、
@JsonCodable()
、三阶段宏流水线		Macros与增强功能指南
实验特性编译器标志
--enable-experiment
、Beta预览版与稳定版 gated 发布层级、升级矩阵		实验特性指南
遗留代码修复迁移手册Dart 1.x/2.x到现代3.x的现代化流程、空安全过渡、包替换修复指南
Dart 3.14FFI与JS互操作
NativeFinalizer.callback
、快速原始JS数组转换		3.14参考文档
Dart 3.13语言与运行时主构造函数、
this
构造函数体、
new
/
factory
简写、
Future.pause
、同步隔离		3.13参考文档
Dart 3.12语言与工具私有命名参数（
Point({this._x})
）、
RegExp
跨度、
dart run <pkg>@<ver>
3.12参考文档
Dart 3.11平台与PubWindows Unix域套接字、工作区通配符（
pkgs/*
）、
dart pub cache gc
3.11参考文档
Dart 3.10扩展性与CLI分析器插件稳定、Hooks（原生资产）稳定、
dart install
、
@Deprecated
构造函数		3.10参考文档
Dart 3.9分析与PubAOT分析服务器、Git标签版本解析、流分析中的空安全假设3.9参考文档
Dart 3.8格式化工具与文档文档导入（
@docImport
）、纵向格式化保留尾随逗号、
Iterable.withIterator
3.8参考文档
Dart 3.7语言与格式化工具通配符变量（
_
）、使用边界进行推断、默认纵向格式化、遗留Web功能废弃		3.7参考文档
Dart 3.6语言与Pub数字分隔符（
1_000_000
）、Pub工作区、
dart pub bump
3.6参考文档
Dart 3.0 – 3.5基础与主要特性记录、模式、Switch表达式、密封类、类修饰符、扩展类型、字段提升、Wasm3.0–3.5参考文档
Dart 2.0 – 2.19历史里程碑可靠空安全（2.12）、增强枚举与超参数（2.17）、扩展方法（2.7）、展开运算符（2.3）、可靠类型系统（2.0）Dart 2里程碑

🛠️ Recommended Runbooks

🛠️ 推荐操作手册

1. Working with Augmentations & Macros

1. 使用增强功能与Macros

  1. Review Macros & Augmentations Guide.
  2. Wire original files with 
    import augment 'foo.g.dart';
    and augmentation files with 
    augment library 'foo.dart';
    .
  3. Use 
    augment class
    , 
    augment void method()
    , and call 
    augmented()
    to wrap original logic.
  1. 查看Macros与增强功能指南。
  2. 在原始文件中添加
    import augment 'foo.g.dart';
    ，在增强文件中添加
    augment library 'foo.dart';
    。
  3. 使用
    augment class
    、
    augment void method()
    ，并调用
    augmented()
    包裹原有逻辑。

2. Working with Experimental Feature Flags

2. 使用实验特性标志

  1. Check if the feature has already graduated to stable in the active SDK before adding a flag.
  2. If experimental, configure 
    analysis_options.yaml
    under 
    analyzer.enable-experiment: [name]
    .
  3. Pass 
    --enable-experiment=name
    to 
    dart run
    , 
    dart test
    , 
    flutter run
    , and 
    flutter test
    .
  4. Ensure experimental code is isolated so production packages remain publishable on pub.dev.
  1. 在添加标志前，检查该特性在当前SDK中是否已升级到稳定版。
  2. 如果是实验特性，在
    analysis_options.yaml
    的
    analyzer.enable-experiment: [name]
    下进行配置。
  3. 在
    dart run
    、
    dart test
    、
    flutter run
    和
    flutter test
    中传递
    --enable-experiment=name
    参数。
  4. 确保实验代码被隔离，以便生产包可以在pub.dev上发布。

3. Modernizing / Rescuing a Legacy Codebase

3. 现代化/修复遗留代码库

  1. Check current language version from 
    pubspec.yaml
    environment block.
  2. If pre-2.12, read the Legacy Rescue Guide.
  3. Execute the 4-stage pipeline: syntax cleanup → sound null safety → dependency bump (
    sdk: ^3.5.0
    or 
    ^3.13.0
    ) → Dart 3 modernization.
  1. 从
    pubspec.yaml
    的环境块中查看当前语言版本。
  2. 如果是2.12之前的版本，请阅读遗留代码修复指南。
  3. 执行四阶段流程：语法清理 → 可靠空安全迁移 → 依赖升级（
    sdk: ^3.5.0
    或
    ^3.13.0
    ）→ Dart 3现代化。

4. Answering "What's New in Dart X.Y"

4. 回答“Dart X.Y版本有什么新特性”

  1. Identify the requested version.
  2. Read the corresponding reference document under 
    references/
    .
  3. Provide:
    • Language syntax changes with before/after code snippets.
    • Core library additions (
      dart:core
      , 
      dart:async
      , 
      dart:io
      , 
      dart:js_interop
      , 
      dart:isolate
      , 
      dart:ffi
      ).
    • Tooling and CLI features (
      dart analyze
      , 
      dart format
      , 
      dart pub
      , 
      dart build
      ).
    • Breaking changes and migration instructions.
  1. 确定用户请求的版本。
  2. 阅读
    references/
    下对应的参考文档。
  3. 提供：
    • 语言语法变更，包含变更前后的代码片段。
    • 核心库新增内容（
      dart:core
      、
      dart:async
      、
      dart:io
      、
      dart:js_interop
      、
      dart:isolate
      、
      dart:ffi
      ）。
    • 工具与CLI特性（
      dart analyze
      、
      dart format
      、
      dart pub
      、
      dart build
      ）。
    • 破坏性变更与迁移说明。

5. Answering "How to find minSdk for X"

5. 回答“如何查找X的minSdk”

  1. Check the Language Feature Matrix and How to Find minSdk Guide.
  2. Specify the exact lower bound SDK constraint for 
    pubspec.yaml
    (for example 
    sdk: '^3.13.0'
    ).
  3. Explain if the feature is a language grammar feature (requiring language version update) or a core library API.
  4. Show how to verify using 
    dart analyze
    .
  1. 查看语言特性矩阵和如何查找minSdk指南。
  2. 指定
    pubspec.yaml
    中确切的SDK下限约束（例如
    sdk: '^3.13.0'
    ）。
  3. 说明该特性是语言语法特性（需要更新语言版本）还是核心库API。
  4. 展示如何使用
    dart analyze
    进行验证。