dart-migration-versioning

管理 Dart 语言版本

目录

• 核心指南
• 配置与覆盖
• 工作流
• 示例
• 重大变更参考
• 相关技能

核心指南

• 在开始任何迁移或重构之前，先检查 pubspec.yaml 中的当前语言版本要求。
• 执行主要依赖项或 SDK 升级之前，先查阅重大变更日志。
• 渐进式迁移期间，使用 @dart = <version> 将特定文件固定到较旧版本（例如，将大型项目迁移到新的语言功能，如健全的空安全）。
• 了解版本推导规则：软件包的默认语言版本严格由 pubspec.yaml 中 SDK 约束的下限决定。补丁版本不会引入新的语言功能。

配置与覆盖

全局软件包版本控制

修改 pubspec.yaml 中的 environment.sdk 约束，为整个软件包设置默认语言版本。

单个库的版本选择

使用特定注释语法，为单个文件覆盖软件包级语言版本。

• 将 @dart 字符串放在 // 注释中（不要使用 /// 或 /*）。
• 确保该注释出现在文件中的任何 Dart 代码之前。
• 升级软件包其余部分时，使用此机制保持旧代码的兼容性。

工作流

任务进度：渐进式语言版本迁移

将项目升级到包含重大变更的 Dart 新主版本或次版本时，使用此工作流。

• 分析当前状态：在当前版本上运行 dart analyze，确保基线干净。
• 检查约束：检查 pubspec.yaml，确定当前 SDK 约束的下限。
• 查看重大变更：查阅目标版本的重大变更参考。
• 更新 SDK 约束：将 pubspec.yaml 中 environment.sdk 的下限修改为目标版本。
• 运行依赖解析：执行 dart pub get。
• 识别问题：运行 dart analyze。
• 应用有条件的修复逻辑：
  • 如果文件较小或易于重构：立即修复重大变更带来的问题，以符合新语言版本的要求。
  • 如果文件较复杂或属于大型旧版模块的一部分：在文件顶部插入 // @dart = <previous_version>，推迟迁移。
• 运行验证程序：执行 dart test 和 dart analyze -> 查看错误 -> 修复剩余问题。

示例

设置软件包语言版本

# pubspec.yaml
name: my_package
environment:
  # This sets the default language version to Dart 3.3
  sdk: '>=3.3.0 <4.0.0'

应用单个库的覆盖设置

// @dart = 2.19
// The above comment pins this specific file to Dart 2.19, 
// even if the pubspec.yaml specifies Dart 3.0+.

import 'dart:math';

void legacyFunction() {
  // Legacy code implementation
}

重大变更参考

展开查看 Dart 关键重大变更（版本 2.12 - 3.11）

Dart 3.11.0

• Wasm 编译：导入 dart:js_util 或 package:js 的代码会导致编译错误。迁移到 dart:js_interop。
• 分析器：已弃用 avoid_null_checks_in_equality_operators、prefer_final_parameters 和 use_if_null_to_convert_nulls_to_bools lint 规则。

Dart 3.10.0

• SDK：dart CLI 与 Dart VM 现已成为独立的可执行文件（dartvm）。已移除对 IA32 平台的支持。
• Wasm 编译：dartify 会将 JS Promise 对象转换为 Dart Future 对象，而不是 JSValue。

Dart 3.7.0

• 语言：名为 _ 的局部变量和参数不再绑定，无法访问。
• 库：旧版 Web 库（dart:html、dart:js 等）已正式弃用。迁移到 package:web 和 dart:js_interop。

Dart 3.5.0

• 运行时：Dart VM 不再支持不健全的空安全。已移除 --no-sound-null-safety CLI 选项。

### Dart 3.0.0（重大破坏性变更） - **语言**：严格强制执行空安全。现在，`switch` 分支会被解释为模式。 - **混入**：默认情况下，不再能将 Dart 3.0+ 库中的类声明用作混入。 - **核心**：`Iterable`、`ListMixin`、`SetMixin` 和 `MapMixin` 现在是混入类。

Dart 2.12.0

• 语言：默认启用健全的空安全。

相关技能

• dart-web-development
• dart-static-analysis