修复类型提升失败

目录 keyboard_arrow_down keyboard_arrow_up

不支持字段提升的语言版本
只有局部变量可以被提升 (Dart 3.2 之前)
其他原因和解决方法

more_horiz

类型提升当流分析可以可靠地确认一个可空类型的变量不是 null，并且从那时起它不会改变时，就会发生。许多情况会削弱类型的健全性，导致类型提升失败。

本页列出了类型提升失败发生的原因，并提供了如何修复它们的提示。要了解更多关于流分析和类型提升的信息，请查看理解空安全页面。

原因： 您正在尝试提升一个字段，但是字段提升是语言版本化的，并且您的代码设置为 3.2 之前的语言版本。

如果您已经在使用 SDK 版本 >= Dart 3.2，您的代码可能仍然显式地针对较早的语言版本。这可能是因为

您的 pubspec.yaml 声明了一个 SDK 约束，其下限低于 3.2，或者
您在文件顶部有一个 // @dart=version 注释，其中 version 低于 3.2。

示例

baddart// @dart=3.1

class C {
  final int? _i;
  C(this._i);

  void f() {
    if (_i != null) {
      int i = _i;  // ERROR
    }
  }
}

消息

'_i' refers to a field. It couldn't be promoted because field promotion is only available in Dart 3.2 and above.

解决方案

确保您的库没有使用早于 3.2 的语言版本。检查您的文件顶部是否有过时的 // @dart=version 注释，或者您的 pubspec.yaml 中是否有过时的 SDK 约束下限。

原因： 您正在尝试提升一个属性，但是只有局部变量可以在 Dart 3.2 之前的版本中被提升，而您正在使用早于 3.2 的版本。

示例

baddartclass C {
  int? i;
  void f() {
    if (i == null) return;
    print(i.isEven);       // ERROR
  }
}

消息

'i' refers to a property so it couldn't be promoted.

解决方案

如果您正在使用 Dart 3.1 或更早版本，请升级到 3.2 或更高版本。

如果您需要继续使用旧版本，请阅读其他原因和解决方法

本页剩余的示例记录了与版本不一致无关的提升失败的原因，包括字段和局部变量失败，并提供了示例和解决方法。

一般来说，类型提升失败的常见修复方法是以下一项或多项

将属性的值分配给一个具有您需要的非空类型的局部变量。
添加显式的 null 检查 (例如，i == null)。
如果您确定表达式不可能是 null，请使用 ! 或 as 作为冗余检查。

这是一个创建局部变量（可以命名为 i）的示例，该变量保存 i 的值

gooddartclass C {
  int? i;
  void f() {
    final i = this.i;
    if (i == null) return;
    print(i.isEven);
  }
}

此示例以实例字段为特色，但它可以改为使用实例 getter、静态字段或 getter、顶层变量或 getter，或 this。

这是一个使用 i! 的示例

gooddart

print(i!.isEven);

原因： 您正在尝试提升 this，但是尚不支持 this 的类型提升。

一个常见的 this 提升场景是在编写扩展方法时。如果扩展方法的 on 类型是可空类型，您会想要进行 null 检查以查看 this 是否为 null

示例

baddartextension on int? {
  int get valueOrZero {
    return this == null ? 0 : this; // ERROR
  }
}

消息

`this` can't be promoted.

解决方案

创建一个局部变量来保存 this 的值，然后执行 null 检查。

gooddartextension on int? {
  int get valueOrZero {
    final self = this;
    return self == null ? 0 : self;
  }
}

原因： 您正在尝试提升一个字段，但是该字段不是私有的。

程序中的其他库可能会使用 getter 覆盖公共字段。因为 getter 可能不会返回稳定的值，并且编译器无法知道其他库在做什么，所以非私有字段无法被提升。

示例

baddartclass Example {
  final int? value;
  Example(this.value);
}

void test(Example x) {
  if (x.value != null) {
    print(x.value + 1); // ERROR
  }
}

消息

'value' refers to a public property so it couldn't be promoted.

解决方案

将字段设为私有可以让编译器确信没有外部库可能覆盖其值，因此可以安全地提升。

gooddartclass Example {
  final int? _value;
  Example(this._value);
}

void test(Example x) {
  if (x._value != null) {
    print(x._value + 1);
  }
}

原因： 您正在尝试提升一个字段，但是该字段不是 final 的。

对于编译器来说，原则上，非 final 字段可能在测试时间和使用时间之间的任何时间被修改。因此，编译器将非 final 可空类型提升为非空类型是不安全的。

示例

baddartclass Example {
  int? _mutablePrivateField;
  Example(this._mutablePrivateField);

  void f() {
    if (_mutablePrivateField != null) {
      int i = _mutablePrivateField; // ERROR
    }
  }
}

消息

'_mutablePrivateField' refers to a non-final field so it couldn't be promoted.

解决方案

将字段设为 final

gooddartclass Example {
  final int? _immutablePrivateField;
  Example(this._immutablePrivateField);

  void f() {
    if (_immutablePrivateField != null) {
      int i = _immutablePrivateField; // OK
    }
  }
}

原因： 您正在尝试提升一个 getter，但是只有实例字段可以被提升，而不是实例 getter。

编译器无法保证 getter 每次都返回相同的结果。由于无法确认其稳定性，因此 getter 不安全，无法提升。

示例

baddartimport 'dart:math';

abstract class Example {
  int? get _value => Random().nextBool() ? 123 : null;
}

void f(Example x) {
  if (x._value != null) {
    print(x._value.isEven); // ERROR
  }
}

消息

'_value' refers to a getter so it couldn't be promoted.

解决方案

将 getter 分配给一个局部变量

gooddartimport 'dart:math';

abstract class Example {
  int? get _value => Random().nextBool() ? 123 : null;
}

void f(Example x) {
  final value = x._value;
  if (value != null) {
    print(value.isEven); // OK
  }
}

原因： 您正在尝试提升一个字段，但是该字段被标记为 external。

External 字段不提升，因为它们本质上是 external getter；它们的实现是来自 Dart 外部的代码，因此编译器无法保证 external 字段每次调用都返回相同的值。

示例

baddartclass Example {
  external final int? _externalField;

  void f() {
    if (_externalField != null) {
      print(_externalField.isEven); // ERROR
    }
  }
}

消息

'_externalField' refers to an external field so it couldn't be promoted.

解决方案

将 external 字段的值分配给一个局部变量

gooddartclass Example {
  external final int? _externalField;

  void f() {
    final i = _externalField;
    if (i != null) {
      print(i.isEven); // OK
    }
  }
}

原因： 您正在尝试提升一个字段，但是同一库中的另一个类包含一个同名的具体 getter。

示例

baddartimport 'dart:math';

class Example {
  final int? _overridden;
  Example(this._overridden);
}

class Override implements Example {
  @override
  int? get _overridden => Random().nextBool() ? 1 : null;
}

void testParity(Example x) {
  if (x._overridden != null) {
    print(x._overridden.isEven); // ERROR
  }
}

消息

'_overriden' couldn't be promoted because there is a conflicting getter in class 'Override'.

解决方案:

如果 getter 和字段相关并且需要共享它们的名称（就像它们中的一个覆盖另一个一样，如上面的示例所示），那么您可以通过将值分配给局部变量来启用类型提升

gooddartimport 'dart:math';

class Example {
  final int? _overridden;
  Example(this._overridden);
}

class Override implements Example {
  @override
  int? get _overridden => Random().nextBool() ? 1 : null;
}

void testParity(Example x) {
  final i = x._overridden;
  if (i != null) {
    print(i.isEven); // OK
  }
}

请注意，在上面的示例中，很明显为什么提升字段 _overridden 是不安全的：因为字段和 getter 之间存在覆盖关系。但是，即使类不相关，冲突的 getter 也会阻止字段提升。例如

baddartimport 'dart:math';

class Example {
  final int? _i;
  Example(this._i);
}

class Unrelated {
  int? get _i => Random().nextBool() ? 1 : null;
}

void f(Example x) {
  if (x._i != null) {
    int i = x._i; // ERROR
  }
}

另一个库可能包含一个类，该类将两个不相关的类组合到同一个类层次结构中，这将导致函数 f 中对 x._i 的引用被分派到 Unrelated._i。例如

baddartclass Surprise extends Unrelated implements Example {}

void main() {
  f(Surprise());
}

解决方案

如果字段和冲突实体确实不相关，您可以通过给它们不同的名称来解决此问题

gooddartclass Example {
  final int? _i;
  Example(this._i);
}

class Unrelated {
  int? get _j => Random().nextBool() ? 1 : null;
}

void f(Example x) {
  if (x._i != null) {
    int i = x._i; // OK
  }
}

原因： 您正在尝试提升一个字段，但是同一库中的另一个类包含一个同名的字段，该字段不可提升（由于本页列出的任何其他原因）。

示例

baddartclass Example {
  final int? _overridden;
  Example(this._overridden);
}

class Override implements Example {
  @override
  int? _overridden;
}

void f(Example x) {
  if (x._overridden != null) {
    print(x._overridden.isEven); // ERROR
  }
}

此示例失败，因为在运行时，x 实际上可能是 Override 的实例，因此提升将是不健全的。

消息

'overridden' couldn't be promoted because there is a conflicting non-promotable field in class 'Override'.

解决方案

如果字段实际上是相关的并且需要共享一个名称，那么您可以通过将值分配给一个 final 局部变量来启用类型提升

gooddartclass Example {
  final int? _overridden;
  Example(this._overridden);
}

class Override implements Example {
  @override
  int? _overridden;
}

void f(Example x) {
  final i = x._overridden;
  if (i != null) {
    print(i.isEven); // OK
  }
}

如果字段不相关，则重命名其中一个字段，以避免它们冲突。阅读关于不相关类的说明。

原因： 您正在尝试提升一个私有且 final 的字段，但是同一库中的另一个类包含一个与该字段同名的隐式 noSuchMethod 转发器。

这是不健全的，因为无法保证 noSuchMethod 从一次调用到下一次调用将返回稳定的值。

示例

baddartimport 'package:mockito/mockito.dart';

class Example {
  final int? _i;
  Example(this._i);
}

class MockExample extends Mock implements Example {}

void f(Example x) {
  if (x._i != null) {
    int i = x._i; // ERROR
  }
}

在此示例中，_i 无法被提升，因为它可能会解析为编译器在 MockExample 内部生成的、不健全的隐式 noSuchMethod 转发器（也名为 _i）。

编译器创建了 _i 的这个隐式实现，因为 MockExample 在其声明中实现 Example 时承诺支持 _i 的 getter，但没有兑现该承诺。因此，未定义的 getter 实现由 Mock 的 noSuchMethod 定义处理，该定义创建了同名的隐式 noSuchMethod 转发器。

失败也可能发生在不相关类中的字段之间。

消息

'_i' couldn't be promoted because there is a conflicting noSuchMethod forwarder in class 'MockExample'.

解决方案

定义有问题的 getter，以便 noSuchMethod 不必隐式地处理其实现

gooddartimport 'package:mockito/mockito.dart';

class Example {
  final int? _i;
  Example(this._i);
}

class MockExample extends Mock implements Example {
  @override
  late final int? _i;
}

void f(Example x) {
  if (x._i != null) {
    int i = x._i; // OK
  }
}

getter 被声明为 late 是为了与 mocks 的一般使用方式保持一致；在不涉及 mocks 的场景中，不必将 getter 声明为 late 即可解决此类型提升失败。

原因： 您正在尝试提升一个变量，该变量可能在提升后被写入。

示例

baddartvoid f(bool b, int? i, int? j) {
  if (i == null) return;
  if (b) {
    i = j;           // (1)
  }
  if (!b) {
    print(i.isEven); // (2) ERROR
  }
}

解决方案:

在此示例中，当流分析到达 (1) 时，它将 i 从非空 int 降级回可空 int?。人类可以判断 (2) 处的访问是安全的，因为没有包含 (1) 和 (2) 的代码路径，但是流分析不够智能，无法看到这一点，因为它不跟踪单独的 if 语句中条件之间的相关性。

您可以通过组合两个 if 语句来解决此问题

gooddartvoid f(bool b, int? i, int? j) {
  if (i == null) return;
  if (b) {
    i = j;
  } else {
    print(i.isEven);
  }
}

在像这样的直线控制流情况下（没有循环），流分析在决定是否降级时会考虑赋值的右侧。因此，修复此代码的另一种方法是将 j 的类型更改为 int。

gooddartvoid f(bool b, int? i, int j) {
  if (i == null) return;
  if (b) {
    i = j;
  }
  if (!b) {
    print(i.isEven);
  }
}

原因： 您正在尝试提升可能在循环的前一次迭代中被写入的内容，因此提升被无效化。

示例

baddartvoid f(Link? p) {
  if (p != null) return;
  while (true) {    // (1)
    print(p.value); // (2) ERROR
    var next = p.next;
    if (next == null) break;
    p = next;       // (3)
  }
}

当流分析到达 (1) 时，它会向前看并看到 (3) 处对 p 的写入。但是由于它是向前看的，因此它尚未弄清楚赋值右侧的类型，因此它不知道保留提升是否安全。为了安全起见，它使提升无效。

解决方案:

您可以通过将 null 检查移至循环顶部来解决此问题

gooddartvoid f(Link? p) {
  while (p != null) {
    print(p.value);
    p = p.next;
  }
}

如果 case 块具有标签，则这种情况也可能在 switch 语句中出现，因为您可以使用带标签的 switch 语句来构造循环

baddartvoid f(int i, int? j, int? k) {
  if (j == null) return;
  switch (i) {
    label:
    case 0:
      print(j.isEven); // ERROR
      j = k;
      continue label;
  }
}

同样，您可以通过将 null 检查移至循环顶部来解决此问题

gooddartvoid f(int i, int? j, int? k) {
  switch (i) {
    label:
    case 0:
      if (j == null) return;
      print(j.isEven);
      j = k;
      continue label;
  }
}

原因： 变量可能在 try 块中被写入，并且执行现在位于 catch 块中。

示例

baddartvoid f(int? i, int? j) {
  if (i == null) return;
  try {
    i = j;                 // (1)
    // ... Additional code ...
    if (i == null) return; // (2)
    // ... Additional code ...
  } catch (e) {
    print(i.isEven);       // (3) ERROR
  }
}

在这种情况下，流分析不认为 i.isEven (3) 是安全的，因为它无法知道异常可能发生在 try 块中的哪个时间点，因此它保守地假设异常可能发生在 (1) 和 (2) 之间，那时 i 可能是 null。

类似的情况可能发生在 try 和 finally 块之间，以及 catch 和 finally 块之间。由于实现方式的历史遗留问题，这些 try/catch/finally 情况不考虑赋值的右侧，类似于循环中发生的情况。

解决方案:

要解决此问题，请确保 catch 块不依赖于关于在 try 块内部更改的变量状态的假设。请记住，异常可能在 try 块期间的任何时间发生，可能在 i 为 null 时发生。

最安全的解决方案是在 catch 块内部添加 null 检查

gooddarttry {
  // ···
} catch (e) {
  if (i != null) {
    print(i.isEven); // (3) OK due to the null check in the line above.
  } else {
    // Handle the case where i is null.
  }
}

或者，如果您确定在 i 为 null 时不会发生异常，只需使用 ! 运算符

darttry {
  // ···
} catch (e) {
  print(i!.isEven); // (3) OK because of the `!`.
}

原因： 您正在尝试提升到的类型不是变量当前提升类型的子类型（或者在尝试提升时不是子类型）。

示例

baddartvoid f(Object o) {
  if (o is Comparable /* (1) */ ) {
    if (o is Pattern /* (2) */ ) {
      print(o.matchAsPrefix('foo')); // (3) ERROR
    }
  }
}

在此示例中，o 在 (1) 处被提升为 Comparable，但在 (2) 处未被提升为 Pattern，因为 Pattern 不是 Comparable 的子类型。（理由是，如果它被提升，那么您将无法使用 Comparable 上的方法。）请注意，仅仅因为 Pattern 不是 Comparable 的子类型并不意味着 (3) 处的代码是死代码；o 可能具有一种类型——例如 String——它同时实现了 Comparable 和 Pattern。

解决方案:

一种可能的解决方案是创建一个新的局部变量，以便原始变量被提升为 Comparable，而新变量被提升为 Pattern

dartvoid f(Object o) {
  if (o is Comparable /* (1) */ ) {
    Object o2 = o;
    if (o2 is Pattern /* (2) */ ) {
      print(
        o2.matchAsPrefix('foo'),
      ); // (3) OK; o2 was promoted to `Pattern`.
    }
  }
}

但是，稍后编辑代码的人可能会尝试将 Object o2 更改为 var o2。该更改使 o2 的类型为 Comparable，这带回了对象无法提升为 Pattern 的问题。

冗余类型检查可能是一个更好的解决方案

gooddartvoid f(Object o) {
  if (o is Comparable /* (1) */ ) {
    if (o is Pattern /* (2) */ ) {
      print((o as Pattern).matchAsPrefix('foo')); // (3) OK
    }
  }
}

有时有效的另一种解决方案是当您可以使用更精确的类型时。如果第 3 行仅关心字符串，那么您可以在类型检查中使用 String。因为 String 是 Comparable 的子类型，所以提升有效

gooddartvoid f(Object o) {
  if (o is Comparable /* (1) */ ) {
    if (o is String /* (2) */ ) {
      print(o.matchAsPrefix('foo')); // (3) OK
    }
  }
}

原因： 变量已被局部函数或函数表达式写入捕获。

示例

baddartvoid f(int? i, int? j) {
  var foo = () {
    i = j;
  };
  // ... Use foo ... 
  if (i == null) return; // (1)
  // ... Additional code ...
  print(i.isEven);       // (2) ERROR
}

流分析认为，一旦到达 foo 的定义，它可能随时被调用，因此完全提升 i 不再安全。与循环一样，此降级与赋值右侧的类型无关。

解决方案:

有时可以重构逻辑，以便提升在写入捕获之前

gooddartvoid f(int? i, int? j) {
  if (i == null) return; // (1)
  // ... Additional code ...
  print(i.isEven); // (2) OK
  var foo = () {
    i = j;
  };
  // ... Use foo ...
}

另一种选择是创建一个局部变量，这样它就不会被写入捕获

gooddartvoid f(int? i, int? j) {
  var foo = () {
    i = j;
  };
  // ... Use foo ...
  var i2 = i;
  if (i2 == null) return; // (1)
  // ... Additional code ...
  print(i2.isEven); // (2) OK because `i2` isn't write captured.
}

或者您可以进行冗余检查

dartvoid f(int? i, int? j) {
  var foo = () {
    i = j;
  };
  // ... Use foo ...
  if (i == null) return; // (1)
  // ... Additional code ...
  print(i!.isEven); // (2) OK due to `!` check.
}

原因： 变量在闭包或函数表达式之外被写入，而类型提升位置在闭包或函数表达式内部。

示例

baddartvoid f(int? i, int? j) {
  if (i == null) return;
  var foo = () {
    print(i.isEven); // (1) ERROR
  };
  i = j;             // (2)
}

流分析认为，无法确定何时可能调用 foo，因此它可能在 (2) 处的赋值之后被调用，因此提升可能不再有效。与循环一样，此降级与赋值右侧的类型无关。

解决方案:

一种解决方案是创建一个局部变量

gooddartvoid f(int? i, int? j) {
  if (i == null) return;
  var i2 = i;
  var foo = () {
    print(i2.isEven); // (1) OK because `i2` isn't changed later.
  };
  i = j; // (2)
}

示例

一个特别棘手的情况看起来像这样

baddartvoid f(int? i) {
  i ??= 0;
  var foo = () {
    print(i.isEven); // ERROR
  };
}

在这种情况下，人类可以看到提升是安全的，因为对 i 的唯一写入使用非空值并且发生在 foo 创建之前。但是流分析没有那么智能。

解决方案:

同样，一种解决方案是创建一个局部变量

gooddartvoid f(int? i) {
  var j = i ?? 0;
  var foo = () {
    print(j.isEven); // OK
  };
}

此解决方案有效，因为由于其初始值 (i ?? 0)，j 被推断为具有非空类型 (int)。因为 j 具有非空类型，无论它是否稍后被赋值，j 永远不可能具有空值。

原因： 您正在尝试提升的变量在闭包或函数表达式之外被写入捕获，但是此变量的使用在尝试提升它的闭包或函数表达式内部。

示例

baddartvoid f(int? i, int? j) {
  var foo = () {
    if (i == null) return;
    print(i.isEven); // ERROR
  };
  var bar = () {
    i = j;
  };
}

流分析认为无法知道 foo 和 bar 可能以什么顺序执行；事实上，bar 甚至可能在执行 foo 的一半时执行（由于 foo 调用了调用 bar 的东西）。因此，在 foo 内部完全提升 i 是不安全的。

解决方案:

最好的解决方案可能是创建一个局部变量

gooddartvoid f(int? i, int? j) {
  var foo = () {
    var i2 = i;
    if (i2 == null) return;
    print(i2.isEven); // OK because i2 is local to this closure.
  };
  var bar = () {
    i = j;
  };
}

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

修复类型提升失败

不支持字段提升的语言版本

只有局部变量可以被提升 (Dart 3.2 之前)

其他原因和解决方法

无法提升 `this`

只有私有字段可以被提升

只有 final 字段可以被提升

Getters 无法被提升

External 字段无法被提升

与库中其他地方的 getter 冲突

关于不相关类的说明

与库中其他地方的不可提升字段冲突

与隐式 `noSuchMethod` 转发器冲突

可能在提升后被写入

可能在之前的循环迭代中被写入

在 try 中可能写入后的 catch 块中

子类型不匹配

写入被局部函数捕获

在当前闭包或函数表达式之外写入

写入在当前闭包或函数表达式之外被捕获

修复类型提升失败

不支持字段提升的语言版本

只有局部变量可以被提升 (Dart 3.2 之前)

其他原因和解决方法

无法提升 this

只有私有字段可以被提升

只有 final 字段可以被提升

Getters 无法被提升

External 字段无法被提升

与库中其他地方的 getter 冲突

关于不相关类的说明

与库中其他地方的不可提升字段冲突

与隐式 noSuchMethod 转发器冲突

可能在提升后被写入

可能在之前的循环迭代中被写入

在 try 中可能写入后的 catch 块中

子类型不匹配

写入被局部函数捕获

在当前闭包或函数表达式之外写入

写入在当前闭包或函数表达式之外被捕获

无法提升 `this`

与隐式 `noSuchMethod` 转发器冲突