dart-migration-versioning

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Dart Version Management and Migration

Dart版本管理与迁移

Goal

目标

Manages Dart language versioning, resolves breaking changes during SDK upgrades, and applies per-library version overrides to facilitate gradual migrations. Assumes a standard Dart or Flutter environment with access to

pubspec.yaml

and source files. Related Skills:

dart-web-development

dart-static-analysis

管理Dart语言版本控制，解决SDK升级过程中的破坏性变更问题，应用库级别的版本覆盖以支持渐进式迁移。假设使用标准Dart或Flutter环境，可访问

pubspec.yaml

和源文件。相关技能：

dart-web-development

、

dart-static-analysis

。

Decision Logic

决策逻辑

When tasked with upgrading a Dart project or fixing version-related compilation errors, follow this evaluation path:

Identify Target SDK: Determine the target Dart SDK version.
Check Current Version: Read
```
pubspec.yaml
```
to find the current lower bound SDK constraint.
Evaluate Breaking Changes: Cross-reference the version jump with the breaking changes log.
- If migrating to >= 3.0.0: Sound null safety is strictly enforced.
- If migrating web libraries to >= 3.3.0: Legacy
```
dart:html
```
  and
```
dart:js
```
  are deprecated/removed.
Determine Migration Strategy:
- Can the code be refactored immediately? -> Apply API migrations.
- Is the refactor too large or blocked? -> Pin specific files using
```
@dart = <version>
```
  to maintain older language semantics while upgrading the package.

当接到升级Dart项目或修复版本相关编译错误的任务时，遵循以下评估路径：

确定目标SDK： 明确目标Dart SDK版本。
检查当前版本： 读取
```
pubspec.yaml
```
找到当前的SDK约束下限。
评估破坏性变更： 对照版本跨度对应的破坏性变更日志进行核对。
- 如果升级到 >= 3.0.0版本： 严格强制启用Sound null safety机制。
- 如果将Web库升级到 >= 3.3.0版本： 旧版
```
dart:html
```
  和
```
dart:js
```
  已弃用/移除。
确定迁移策略：
- 代码是否可以立即重构？ -> 执行API迁移。
- 重构工作量过大或存在阻塞？ -> 使用
```
@dart = <version>
```
  标注指定文件，在升级包的同时保留旧版语言语义。

Instructions

操作指南

Verify Current Language Version Requirements Inspect the
```
pubspec.yaml
```
file to determine the default language version, which is dictated by the lower bound of the SDK constraint.
yaml
```
environment:
  sdk: '>=2.18.0 <3.0.0' # Defaults to Dart 2.18
```
Consult Breaking Change Logs Before performing major dependency or SDK upgrades, review the breaking changes for the target version. STOP AND ASK THE USER: "I am about to upgrade the SDK constraint to
```
<target_version>
```
. This includes breaking changes such as
```
<list_key_changes>
```
. Should I proceed with the upgrade and begin refactoring?"
Apply Per-Library Language Version Selection (Gradual Migration) If a specific file cannot be immediately migrated to the new language version (e.g., pending null safety migration or complex refactoring), pin the file to an older version.
- The
```
@dart
```
  string must be in a
```
//
```
  comment.
- It must appear before any Dart code in the file.
dart
```
// @dart = 2.19
import 'dart:math';

// Legacy code that relies on 2.19 semantics
void legacyFunction() {
  // ...
}
```

Migrate Deprecated Web and JS Interop Libraries (Dart 3.3+) If the project targets Dart 3.3+ or compiles to Wasm, legacy web libraries (

dart:html

dart:js

package:js

) will cause compilation errors. Migrate these to

package:web

and

dart:js_interop

dart

// BEFORE (Legacy)
import 'dart:html';
import 'package:js/js.dart';

@JS()
external void legacyJsFunction();

// AFTER (Modern)
import 'package:web/web.dart' as web;
import 'dart:js_interop';

@JS()
external void modernJsFunction();

void updateDom() {
  final div = web.document.createElement('div') as web.HTMLDivElement;
  div.text = 'Migrated';
  web.document.body?.append(div);
}

Validate-and-Fix Loop After updating the SDK constraint or modifying code, run static analysis to verify the migration.
bash
```
dart analyze
```
Fixing common post-upgrade errors:
- If
```
unnecessary_non_null_assertion
```
  or
```
invalid_null_aware_operator
```
  appears, remove the
```
!
```
  or
```
?.
```
  as type promotion has likely improved in the newer Dart version.
- If
```
dart:js_util
```
  or
```
dart:html
```
  throws Wasm compilation errors, return to Step 4.

核对当前语言版本要求 检查
```
pubspec.yaml
```
文件确定默认语言版本，该版本由SDK约束的下限决定。
yaml
```
environment:
  sdk: '>=2.18.0 <3.0.0' # 默认使用Dart 2.18
```
查阅破坏性变更日志 在执行重大依赖或SDK升级前，查看目标版本的破坏性变更说明。 请先询问用户： "我即将把SDK约束升级到
```
<target_version>
```
，本次升级包含以下破坏性变更：
```
<list_key_changes>
```
。请问我是否可以继续升级并开始重构代码？"
应用库级语言版本选择（渐进式迁移） 如果特定文件无法立即适配新的语言版本（例如待处理空安全迁移或复杂重构），可将该文件固定到旧版本。
- ```
@dart
```
  字符串必须放在
```
//
```
  注释中。
- 必须出现在文件内所有Dart代码之前。
dart
```
// @dart = 2.19
import 'dart:math';

// 依赖2.19版本语义的旧版代码
void legacyFunction() {
  // ...
}
```

迁移已弃用的Web和JS互操作库（Dart 3.3+） 如果项目目标版本为Dart 3.3+或需要编译为Wasm，旧版Web库（

dart:html

、

dart:js

、

package:js

）会引发编译错误，请将其迁移到

package:web

和

dart:js_interop

。

dart

// 改造前（旧版）
import 'dart:html';
import 'package:js/js.dart';

@JS()
external void legacyJsFunction();

// 改造后（新版）
import 'package:web/web.dart' as web;
import 'dart:js_interop';

@JS()
external void modernJsFunction();

void updateDom() {
  final div = web.document.createElement('div') as web.HTMLDivElement;
  div.text = 'Migrated';
  web.document.body?.append(div);
}

验证与修复循环 更新SDK约束或修改代码后，运行静态分析验证迁移结果。
bash
```
dart analyze
```
修复升级后常见错误：
- 如果出现
```
unnecessary_non_null_assertion
```
  或
```
invalid_null_aware_operator
```
  报错，移除
```
!
```
  或
```
?.
```
  即可，因为新版Dart的类型推导能力大概率已经得到优化。
- 如果
```
dart:js_util
```
  或
```
dart:html
```
  抛出Wasm编译错误，回到步骤4处理。

Constraints

约束规则

DO check current language version requirements in
```
pubspec.yaml
```
before making any syntax changes.
DO use
```
@dart = <version>
```
to pin specific files to older versions during migration if a full refactor is not requested.
DO consult breaking change logs before performing major dependency upgrades.
NEVER use
```
///
```
or
```
/* */
```
for the
```
@dart
```
version override comment; it must be
```
//
```
.
NEVER place the
```
@dart
```
comment after imports or code declarations.
NEVER attempt to use
```
dart:html
```
,
```
dart:js
```
, or
```
dart:js_util
```
when compiling to WebAssembly (
```
dart compile wasm
```
).
NEVER disable sound null safety in Dart 3.0+; the
```
--no-sound-null-safety
```
flag and unsound execution are completely removed.

进行任何语法变更前，必须先检查
```
pubspec.yaml
```
中的当前语言版本要求。
如果未要求全量重构，迁移过程中必须使用
```
@dart = <version>
```
将特定文件固定到旧版本。
执行重大依赖升级前必须查阅破坏性变更日志。
禁止使用
```
///
```
或
```
/* */
```
书写
```
@dart
```
版本覆盖注释，必须使用
```
//
```
。
禁止将
```
@dart
```
注释放在导入语句或代码声明之后。
编译为WebAssembly（
```
dart compile wasm
```
）时禁止使用
```
dart:html
```
、
```
dart:js
```
或
```
dart:js_util
```
。
Dart 3.0+版本中禁止禁用Sound null safety；
```
--no-sound-null-safety
```
参数和非健全执行模式已被完全移除。