健全的空安全

Dart 语言要求使用健全的空安全特性。

空安全会在编译期防止意外访问 null 变量的错误的产生。

例如，如果一个方法需要整型结果，却接收到了 null，你的应用会出现运行时错误。这类空引用错误在以前调试是非常困难的。

有了健全的空安全体系，变量需要有默认值，即 Dart 认为变量是「非空」的。它们可以赋予与定义的类型相同类型的任意值（例如 int i = 42），且永远不能被设置为 null。你可以指定一个类型为可空（例如 int? i），这类变量只能包含对应类型的值或者 null。

健全的空安全通过对非空变量的未被初始化或以 null 初始化的情况进行标记，把潜在的 运行时错误 转变成了 编辑时 的分析错误。这样的特性让你在开发应用的过程中就可以修复这类错误：

• 没有以非空的值初始化

• 赋了 null 值。

这些检查让你能在构建你的应用前就修复这些错误。

有了空安全，下面代码中所有的变量都是非空的：

// With null safety, none of these can ever be null.
var i = 42; // Inferred to be an int.
String name = getFileName();
final b = Foo();

若你想让变量可以为 null，只需要在类型声明后加上 ?。

int? aNullableInt = null;

• 要尝试一些交互示例，请查看 Dart 语言的速查表 中一些面向空安全的示例。

• 更深入的探讨，可以阅读文档 深入理解空安全。

Dart 的空安全支持基于以下两条核心原则：

默认不可空
除非你将变量显式声明为可空，否则它一定是非空的类型。我们在研究后发现，非空是目前的 API 中最常见的选择，所以选择了非空作为默认值。

完全可靠
Dart 的空安全是非常可靠的。如果类型系统推断出某个变量或表达式具有不可空的类型，那么可以保证它在运行时永远不会为 null。

Dart 凭借全程序健全的空安全机制，得以充分运用这些原则，减少错误、精简体积并提升运行速度。

Dart 3 has built-in sound null safety. Dart 3 prevents code without it from running.

To learn how to migrate to Dart 3, check out the Dart 3 migration guide. Packages developed without null safety support cause issues when resolving dependencies:

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.

Libraries incompatible with Dart 3 cause analysis or compilation errors.

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
^^^^^^^^^^^^

To resolve these issues:

1. Check for null safe versions of any packages you installed from pub.dev
2. migrate all of your source code to use sound null safety.

Dart 3 can be found in the stable channels for Dart and Flutter. To learn more, check out the download page for details. To test your code for Dart 3 compatibility, use Dart 3 or later.

dart --version                     # make sure this reports 3.0.0-417.1.beta or higher
dart pub get / flutter pub get     # this should resolve without issues
dart analyze / flutter analyze     # this should pass without errors

If the pub get step fails, check the status of the dependencies.

If the analyze step fails, update your code to resolve the issues listed by the analyzer.

在 Dart 2.12 到 2.19 中，你需要手动启用空安全。 Dart 2.12 之前的 SDK 版本不提供空安全。

想要启用健全空安全，你需要将 SDK 的最低版本约束 设定为 2.12 或者更高的 语言版本。例如，你的 pubspec.yaml 可以设置为如下的限制：

environment:
  sdk: '>=2.12.0 <3.0.0'

没有加入空安全支持的 Dart 代码可以迁移到使用空安全。我们建议使用 Dart SDK 2.12 到 2.19 版本中包含的 dart migrate 工具。

cd my_app
dart migrate

你可以阅读 迁移指南 来学习如何迁移你的代码至空安全。

想了解关于空安全的更多内容，可查看以下的资源内容：

• 深入理解空安全

• 现有代码的迁移指南

• 空安全常见问题和解答

• 空安全示例代码

除非另有说明，文档之所提及适用于 Dart 3.7.3 版本，本页面最后更新时间: 2025-05-12。 查看文档源码 或者 报告页面问题。