Dart 3 迁移指南

Dart 3 是一个主要版本，为 Dart 引入了新的核心功能：记录、模式和类修饰符。

除了这些新功能之外，Dart 3 还包含一些可能破坏现有代码的变更。

本指南将帮助您解决升级到 Dart 3后可能遇到的任何迁移问题。

下面列出的潜在破坏性变更分为两类

• 未版本化变更：这些变更会影响升级到 Dart 3.0 SDK 或更高版本后的任何 Dart 代码。无法“关闭”这些变更。

• 版本化变更：这些变更仅在包或应用的语言版本设置为 >= Dart 3.0 时应用。语言版本是从pubspec.yaml 文件中的 sdk 下限约束派生而来。 像这样的 SDK 约束不应用 Dart 3 版本化变更

  yaml

  environment:
    sdk: '>=2.14.0 <3.0.0'

  但像这样的 SDK 约束会应用

  yaml

  environment:
    sdk: '>=3.0.0 <4.0.0'

要使用新的 Dart 3 功能，您必须将语言版本更新到 3.0。 这使您可以同时获得 Dart 3 版本化变更。

许多使用 Dart 2.12 或更高版本进行空安全的包和应用可能向后兼容 Dart 3。 对于 SDK 约束下限为 2.12.0 或更高的任何包来说，这是可能的。

Dart 的 pub 工具允许解析，即使上限限制为低于 3.0.0 的版本也是如此。 例如，具有以下约束的包将被允许使用 Dart 3.x SDK 进行解析，因为当较低约束为 2.12 或更高时，pub 会将上限约束 <3.0.0 重新解释为 <4.0.0

environment:
  sdk: '>=2.14.0 <3.0.0'           # This is interpreted as '>=2.14.0 <4.0.0'

这允许开发者将 Dart 3 健全的空安全与已经支持 2.12 空安全的包一起使用，而无需进行第二次迁移，除非代码受到任何其他 Dart 3 变更的影响。

要了解您的源代码是否受到任何 Dart 3 变更的影响，请使用以下步骤

$ dart --version    # Make sure this reports 3.0.0 or higher.
$ dart pub get      # This should resolve without issues.
$ dart analyze      # This should pass without errors.

如果 pub get 步骤失败，请尝试升级您的依赖项，看看更新的版本是否可能支持 Dart 3

$ dart pub upgrade
$ dart analyze      # This should pass without errors.

或者，如果需要，也包括主要版本升级

$ dart pub upgrade --major-versions
$ dart analyze      # This should pass without errors.

Dart 2.12 在两年多前引入了空安全。 在 Dart 2.12 中，用户需要使用 pubspec 设置启用空安全。 在 Dart 3 中，空安全是内置的；您无法关闭它。

这是一个未版本化 变更，适用于所有 Dart 3 代码。

在没有空安全支持的情况下开发的包在解析 pub get 的依赖项时会导致问题

$ dart pub get

Because pkg1 doesn't support null safety, version solving failed.
The lower bound of "sdk: '>=2.9.0 <3.0.0'" must be 2.12.0 or higher to enable null safety.

使用语言版本注释选择低于 2.12 的任何语言版本来选择退出空安全的库将导致分析或编译错误

$ dart analyze .
Analyzing ....                         0.6s

  error • lib/pkg1.dart:1:1 • The language version must be >=2.12.0. 
  Try removing the language version override and migrating the code.
  • illegal_language_version_override

$ dart run bin/my_app.dart
../pkg1/lib/pkg1.dart:1:1: Error: Library doesn't support null safety.
// @dart=2.9
^^^^^^^^^^^^

在开始任何 Dart 3 迁移之前，请确保您的应用或包已 100% 迁移以启用空安全。 这需要 Dart 2.19 SDK，而不是 Dart 3 SDK。 要了解如何首先迁移您的应用或包以支持空安全，请查看空安全迁移指南。

由于历史原因，命名的可选参数可以使用 : 或 = 来指定其默认值。 在 Dart 3 中，仅允许使用 = 语法。

这是一个版本化 变更，仅适用于语言版本 3.0 或更高版本。

Dart 分析会产生如下错误

line 2 • Using a colon as a separator before a default value is no longer supported.

从使用冒号更改

int someInt({int x: 0}) => x;

更改为使用等号

int someInt({int x = 0}) => x;

此迁移可以手动完成，也可以使用 dart fix 自动化完成

$ dart fix --apply --code=obsolete_colon_for_default_value

在 Dart 3 之前，任何 class 都可以用作 mixin，只要它没有声明的构造函数，并且除了 Object 之外没有超类。

在 Dart 3 中，在语言版本 3.0 或更高版本的库中声明的类不能用作 mixin，除非标记为 mixin。 此限制适用于任何尝试将该类用作 mixin 的库中的代码，而与后一个库的语言版本无关。

这是一个版本化 变更，仅适用于语言版本 3.0 或更高版本。

类似这样的分析错误

Mixin can only be applied to class.

当既不是 mixin class 也不是 mixin 的类在 with 子句中使用时，分析器会生成此诊断信息。

确定该类是否旨在用作 mixin。

如果该类定义了一个接口，请考虑使用 implements。

Dart 3.0 将 switch case 解释为模式而不是常量表达式。

这是一个版本化 变更，仅适用于语言版本 3.0 或更高版本。

在 switch case 中找到的大多数常量表达式都是有效的模式，具有相同的含义（命名常量、字面量等）。 这些行为将相同，并且不会出现任何症状。

少数不是有效模式的常量表达式将触发invalid_case_patterns lint。

您可以通过在 case 模式前加上 const 来恢复到原始行为，这样它就不再被解释为模式

case const [1, 2]:
case const {'k': 'v'}:
case const {1, 2}:
case const Point(1, 2):

您可以使用 dart fix 或从您的 IDE 运行快速修复来解决此破坏性变更。

如果 continue 语句的目标标签不是循环（for、do 和 while 语句）或 switch 成员，Dart 3 会报告编译时错误。

这是一个版本化 变更，仅适用于语言版本 3.0 或更高版本。

您将看到如下错误

The label used in a 'continue' statement must be defined on either a loop or a switch member.

如果更改行为是可以接受的，请更改 continue 以定向到有效的标记语句，该语句必须附加到 for、do 或 while 语句。

如果您想保留行为，请将 continue 语句更改为 break 语句。 在以前版本的 Dart 中，未定向到循环或 switch 成员的 continue 语句的行为类似于 break。

破坏性变更 #49529：核心库已清理，以删除已弃用多年的 API。 以下 API 在 Dart 核心库中不再存在。

这是一个未版本化 变更，适用于所有 Dart 3 代码。

• 移除了已弃用的 List 构造函数，因为它不是空安全的。 使用列表字面量（例如，空列表使用 []，类型化空列表使用 <int>[]）或 List.filled。 这仅影响非空安全代码，因为空安全代码已经无法使用此构造函数。
• 移除了 int.parse、double.parse 和 num.parse 上已弃用的 onError 参数。 请改用 tryParse 方法。
• 移除了已弃用的 proxy 和 Provisional 注解。 原始的 proxy 注解在 Dart 2 中无效，而 Provisional 类型和 provisional 常量仅在 Dart 2.0 开发过程中内部使用。
• 移除了已弃用的 Deprecated.expires getter。 请改用 Deprecated.message。
• 移除了已弃用的 CastError 错误。 请改用 TypeError。
• 移除了已弃用的 FallThroughError 错误。 以前抛出此错误的 fall-through 类型在 Dart 2.0 中已成为编译时错误。
• 移除了已弃用的 NullThrownError 错误。 此错误永远不会从空安全代码中抛出。
• 移除了已弃用的 AbstractClassInstantiationError 错误。 在 Dart 2.0 中，调用抽象类的构造函数已成为编译时错误。
• 移除了已弃用的 CyclicInitializationError。 循环依赖不再在空安全代码中运行时检测。 此类代码将以其他方式失败，可能出现 StackOverflowError。
• 移除了已弃用的 NoSuchMethodError 默认构造函数。 请改用 NoSuchMethodError.withInvocation 命名构造函数。
• 移除了已弃用的 BidirectionalIterator 类。 现有的双向迭代器仍然可以工作，它们只是没有共享的超类型将其锁定为向后移动的特定名称。

• 移除了已弃用的 DeferredLibrary 类。 请改用 deferred as 导入语法。

• 移除了已弃用的 MAX_USER_TAGS 常量。 请改用 maxUserTags。
• 移除了已弃用的 Metrics、Metric、Counter 和 Gauge 类，因为它们自 Dart 2.0 以来已损坏。

• 如先前宣布的那样，已移除 Document 和 HtmlDocument 中已弃用的 registerElement 和 registerElement2 方法。 有关详细信息，请参阅 #49536。

• Random 接口只能实现，不能扩展。

• 更新 NetworkProfiling 以适应 vm_service:11.0.0 中引入的新 String ID

Dart 分析（例如，在您的 IDE 中，或在 dart analyze/flutter analyze 中）将失败，并显示如下错误

error line 2 • Undefined class 'CyclicInitializationError'.

手动迁移以不再使用这些 API。

Dart 3 支持新的类修饰符，这些修饰符可以限制类的功能。 它们已应用于核心库中的许多类。

这是一个版本化 变更，仅适用于语言版本 3.0 或更高版本。

• 以下声明只能实现，不能扩展

  • StreamConsumer
  • StreamIterator
  • StreamTransformer
  • MultiStreamController

  这些声明都不包含任何要继承的实现。 它们被标记为 interface 以表明它们仅用作接口。

• Function 类型不能再被实现、扩展或混入。 自 Dart 2.0 以来，为了向后兼容性，允许编写 implements Function，但它没有任何效果。 在 Dart 3.0 中，Function 类型是 final 的，不能被子类型化，从而防止代码错误地假设它可以工作。

• 以下声明只能实现，不能扩展

  • Comparable
  • Exception
  • Iterator
  • Pattern
  • Match
  • RegExp
  • RegExpMatch
  • StackTrace
  • StringSink

  这些声明都不包含任何要继承的实现。 它们被标记为 interface 以表明它们仅用作接口。

• 以下声明不能再被实现或扩展

  • MapEntry
  • OutOfMemoryError
  • StackOverflowError
  • Expando
  • WeakReference
  • Finalizer

  MapEntry 值类受到限制，以便稍后进行优化。 其余类与平台紧密耦合，不打算被子类化或实现。

• 以下接口不能再被扩展，只能实现

  • Queue

• 以下实现类不能再被实现

  • LinkedList
  • LinkedListEntry

• 以下实现类不能再被实现或扩展

  • HasNextIterator（也已弃用。）
  • HashMap
  • LinkedHashMap
  • HashSet
  • LinkedHashSet
  • DoubleLinkedQueue
  • ListQueue
  • SplayTreeMap
  • SplayTreeSet

从历史上看，Dart 团队为格式化代码 (dartfmt)、分析代码 (dartanalyzer) 等提供了许多较小的开发者工具。 在 Dart 2.10（2020 年 10 月），我们引入了一个新的统一 Dart 开发者工具，即 dart 工具。

这是一个未版本化 变更，适用于所有 Dart 3 代码。

在 Dart 3 中，这些较小的工具不存在，并且已被新的组合 dart 工具取代。

使用 dart 工具中提供的新子命令

以下空安全迁移命令已被移除，因为 Dart 3 不支持没有空安全的代码

• dart migrate
• dart pub upgrade --null-safety
• dart pub outdated --mode=null-safety

这是一个未版本化 变更，适用于所有 Dart 3 代码。

这些命令将失败。

使用 Dart 2.19 来迁移到空安全。

分析器配置选项，用于启用更严格的检查已更改。

这是一个未版本化 变更，适用于所有 Dart 3 代码。

以前的配置选项将失败，并显示如下警告

The option 'implicit-casts' is no longer supported.
Try using the new 'strict-casts' option.

替换分析器配置的这部分

analyzer:
  strong-mode:
    implicit-casts: false
    implicit-dynamic: false

替换为

analyzer:
  language:
    strict-casts: true
    strict-raw-types: true

• 已弃用的 Observatory 默认情况下已隐藏。 我们建议使用 DevTools。
• 命令 dart format fix 已被 dart fix 取代 #1153。
• SDK 中捆绑的 Dart Web 编译器快照文件已清理 #50700。
• dart format 的输出对于 某些代码 发生了一些变化。
• 结束 Windows 上旧版 pub-cache 位置的向后兼容性。 在 Dart 3 之前，%APPDATA%\Pub\Cache 是 pub-cache 的回退位置。 从 Dart 3 开始，默认的 pub-cache 位于 %LOCALAPPDATA%\Pub\Cache。 如果您已将全局激活的包添加到您的 PATH，请考虑更新 PATH 以包含 %LOCALAPPDATA%\Pub\Cache\bin。

这是一个未版本化 变更，适用于所有 Dart 3 代码。

除非另有说明，否则本网站上的文档反映了 Dart 3.7.1。 页面上次更新于 2024-12-10。 查看源代码 或 报告问题。