迁移到空安全

此页面描述了如何以及何时将您的代码迁移到空安全。以下是迁移您拥有的每个软件包的基本步骤

1. 等待 您依赖的软件包迁移。
2. 迁移 您的软件包代码，最好使用交互式迁移工具。
3. 静态分析 您的软件包代码。
4. 测试 以确保您的更改有效。
5. 如果软件包已在 pub.dev 上，发布 空安全版本作为预发布版本。

要非正式地了解使用迁移工具的体验，请观看此视频

如何将 Dart 软件包迁移到空安全

我们强烈建议按顺序迁移代码，首先迁移依赖关系图的叶子节点。例如，如果软件包 C 依赖于软件包 B，软件包 B 依赖于软件包 A，那么应该首先将 A 迁移到空安全，然后是 B，然后是 C。

尽管您可以 在您的依赖项支持空安全之前迁移，但当您的依赖项迁移时，您可能需要更改您的代码。例如，如果您预测一个函数将接受可空参数，但软件包将其迁移为不可空，那么传递可空参数将成为编译错误。

本节告诉您如何在空安全模式下使用 dart pub outdated 命令来检查和更新软件包的依赖项。这些说明假设您的代码在源代码控制下，以便您可以轻松撤消任何更改。

切换到 Dart SDK 的 2.19.6 版本。这包含在 Flutter 3.7.12 SDK 中。

检查您是否安装了 Dart 2.19.6

$ dart --version
Dart SDK version: 2.19.6

使用以下命令获取软件包依赖项的迁移状态

$ dart pub outdated --mode=null-safety

如果输出表明所有软件包都支持空安全，那么您可以开始迁移。否则，使用 Resolvable 列查找空安全版本（如果存在）。

这是一个简单软件包的输出示例。每个软件包的绿色复选标记版本都支持空安全

输出显示，软件包的所有依赖项都具有支持空安全的可解析预发布版本。

如果您的软件包的任何依赖项尚未支持空安全，我们鼓励您联系软件包所有者。您可以在 pub.dev 上的软件包页面上找到联系方式。

在迁移软件包代码之前，请将其依赖项更新为空安全版本

1. 运行 dart pub upgrade --null-safety 以升级到支持空安全的最新版本。注意： 此命令会更改您的 pubspec.yaml 文件。

2. 运行 dart pub get。

您的代码需要成为空安全的大部分更改都是容易预测的。例如，如果变量可以为 null，则其类型需要 ? 后缀。如果命名参数不应为可空，请将其标记为required 或为其指定默认值。

您有两种迁移选项

• 使用迁移工具，它可以为您进行大部分容易预测的更改。
• 手动迁移您的代码。

迁移工具接受一个包含非空安全 Dart 代码的软件包，并将其转换为空安全。您可以通过向 Dart 代码添加提示标记来指导工具的转换。

在启动工具之前，请确保您已准备就绪

• 使用 Dart SDK 的 2.19.6 版本。
• 使用 dart pub outdated --mode=null-safety 以确保所有依赖项都是空安全且最新的。

通过在包含软件包 pubspec.yaml 文件的目录中运行 dart migrate 命令来启动迁移工具

$ dart migrate

如果您的软件包已准备好迁移，则该工具会生成如下行

View the migration suggestions by visiting:

  http://127.0.0.1:60278/Users/you/project/mypkg.console-simple?authToken=Xfz0jvpyeMI%3D

在 Chrome 浏览器中访问该 URL，以查看交互式 UI，您可以在其中指导迁移过程

对于每个变量和类型注释，您都可以看到工具推断的空性。例如，在前面的屏幕截图中，该工具推断第 1 行中的 ints 列表（以前是 int 列表）是可空的，因此应该是 int? 列表。

要查看每个更改（或未更改）的原因，请在 Proposed Edits 窗格中单击其行号。原因将显示在 Edit Details 窗格中。

例如，考虑以下来自空安全之前的代码

var ints = const <int>[0, null];
var zero = ints[0];
var one = zero + 1;
var zeroOne = <int>[zero, one];

当此代码在函数外部时（在函数内部有所不同）的默认迁移是向后兼容的，但并不理想

var ints = const <int?>[0, null];
var zero = ints[0];
var one = zero! + 1;
var zeroOne = <int?>[zero, one];

通过单击 line 3 链接，您可以看到迁移工具添加 ! 的原因。因为您知道 zero 不可能为空，所以您可以改进迁移结果。

当分析推断出错误的空性时，您可以通过插入临时提示标记来覆盖其建议的编辑

• 在迁移工具的 Edit Details 窗格中，您可以使用 Add /*?*/ hint 和 Add /*!*/ hint 按钮插入提示标记。

  这些按钮会立即将注释添加到您的文件中，并且没有撤消。如果您不想要工具插入的提示，可以使用常用的代码编辑器将其删除。

• 您可以使用编辑器添加提示标记，即使工具仍在运行。由于您的代码尚未选择加入空安全，因此您无法使用新的空安全功能。但是，您可以进行诸如不依赖于空安全功能的代码重构之类的更改。

  完成代码编辑后，单击 Rerun from sources 以获取您的更改。

下表显示了您可以用来更改迁移工具建议的编辑的提示标记。

单个提示可能会在代码的其他地方产生连锁反应。在之前的示例中，在为 zero 分配其值的位置（第 2 行）手动添加 /*!*/ 标记会使迁移工具将 zero 的类型推断为 int 而不是 int?。这种类型更改可能会影响直接或间接使用 zero 的代码。

var zero = ints[0]/*!*/;

使用上述提示，迁移工具会更改其建议的编辑，如以下代码片段所示。第 3 行在 zero 之后不再有 !，并且在第 4 行中，zeroOne 被推断为 int 列表，而不是 int? 列表。

var ints = const <int?>[0, null];
var zero = ints[0];
var one = zero! + 1;
var zeroOne = <int?>[zero, one];

var ints = const <int?>[0, null];
var zero = ints[0]/*!*/;
var one = zero + 1;
var zeroOne = <int>[zero, one];

尽管我们建议一次性迁移所有内容，但有时这并不实际，尤其是在大型应用或软件包中。要选择退出文件或目录，请单击其绿色复选框。稍后，当您应用更改时，每个选择退出的文件都将保持不变，除了 2.9 版本注释。

有关增量迁移的更多信息，请参阅不健全的空安全。

请注意，只有完全迁移的应用和软件包才与 Dart 3 兼容。

当您喜欢迁移工具建议的所有更改时，请单击 Apply migration。迁移工具会删除提示标记并保存迁移后的代码。该工具还会更新 pubspec 中的最低 SDK 约束，这会将软件包选择加入空安全。

下一步是静态分析您的代码。如果它有效，那么测试您的代码。然后，如果您已在 pub.dev 上发布了您的代码，请发布空安全预发布版本。

如果您不想使用迁移工具，您可以手动迁移。

我们建议您首先迁移叶子库——不从软件包导入其他文件的库。然后迁移直接依赖于叶子库的库。最后迁移具有最多软件包内依赖项的库。

例如，假设您有一个 lib/src/util.dart 文件，它导入其他（空安全）软件包和核心库，但没有任何 import '<local_path>' 指令。考虑首先迁移 util.dart，然后迁移仅依赖于 util.dart 的简单文件。如果任何库具有循环导入（例如，A 导入 B，B 导入 C，C 导入 A），请考虑将这些库一起迁移。

要手动迁移软件包，请按照以下步骤操作

1. 编辑软件包的 pubspec.yaml 文件，将最低 SDK 约束设置为至少 2.12.0

   yaml

   environment:
     sdk: '>=2.12.0 <3.0.0'

2. 重新生成软件包配置文件

   $ dart pub get

   使用至少 2.12.0 的较低 SDK 约束运行 dart pub get 会将软件包中每个库的默认语言版本设置为至少 2.12，从而使它们全部选择加入空安全。

3. 在您的 IDE 中打开软件包。
   您可能会看到很多分析错误。没关系。

4. 迁移每个 Dart 文件的代码，使用分析器识别静态错误。
   通过根据需要添加 ?、!、required 和 late 来消除静态错误。

有关手动迁移代码的更多帮助，请参阅不健全的空安全。

更新您的软件包（在您的 IDE 中或在命令行中使用 dart pub get）。然后使用您的 IDE 或命令行对您的代码执行静态分析

$ dart pub get
$ dart analyze     # or `flutter analyze`

如果您的代码通过分析，请运行测试

$ dart test       # or `flutter test`

您可能需要更新期望空值的测试。

如果您需要对代码进行大量更改，那么您可能需要重新迁移它。如果是这样，请在使用迁移工具再次迁移之前，恢复您的代码更改。

我们鼓励您在迁移后尽快发布软件包——可能作为预发布版本

• 设置软件包版本以指示破坏性更改。
• 更新 SDK 约束和软件包依赖项。
• 发布软件包。如果您不认为此版本是稳定版本，则将软件包作为预发布版本发布。

更新软件包的版本以指示破坏性更改

• 如果您的软件包已达到 1.0.0 或更高版本，请增加主版本号。例如，如果之前的版本是 2.3.2，则新版本是 3.0.0。

• 如果您的软件包尚未达到 1.0.0，可以 增加次版本号或将版本更新为 1.0.0。例如，如果之前的版本是 0.3.2，则新版本可以是 0.4.0 或 1.0.0。

在发布软件包的稳定空安全版本之前，我们强烈建议遵循以下 pubspec 规则

• 将 Dart 的最低 SDK 约束设置为您已测试过的最低稳定版本（至少 2.12.0）。
• 使用所有直接依赖项的稳定版本。

如果您已走到这一步，您应该拥有一个完全迁移的、空安全的 Dart 软件包。

如果您依赖的所有软件包也都已迁移，那么您的程序在空引用错误方面是健全的。在运行或编译代码时，您应该看到如下输出

Compiling with sound null safety

Dart 团队全体人员，感谢您迁移您的代码。

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