修复类型提升失败

目录 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 或更高版本。

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

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

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

将属性的值赋给具有所需非空类型的局部变量。
添加显式空检查（例如，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 类型是可空类型，您需要进行空检查，以查看 this 是否为 null。

示例

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

消息

`this` can't be promoted.

解决方案

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

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。

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

示例

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.

解决方案

将外部字段的值赋给一个局部变量

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 不能被提升，因为它可能会解析为不健全的隐式 noSuchMethod 转发器（也命名为 _i），该转发器由编译器在 MockExample 内部生成。

编译器会创建 _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 是为了与通常使用 mock 的方式保持一致；在不涉及 mock 的场景中，不需要声明 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 的唯一写入使用非 null 值，并且发生在创建 foo 之前。但是流分析没有那么智能。

解决方案:

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

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

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

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

示例

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.6.0 版本。页面最后更新于 2024-12-10。查看源代码或报告问题。

修复类型提升失败

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

只有局部变量可以被提升（在 Dart 3.2 之前）

其他原因和解决方法

无法提升 `this`

只有私有字段可以被提升

只有 final 字段可以被提升

Getter 不能被提升

外部字段不能被提升

与库中其他地方的 getter 冲突

关于不相关类的注意事项

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

与隐式 `noSuchMethod` 转发器的冲突

可能在提升后写入

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

在 try 中可能写入后的 catch 中

子类型不匹配

写入被局部函数捕获

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

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

修复类型提升失败

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

只有局部变量可以被提升（在 Dart 3.2 之前）

其他原因和解决方法

无法提升 this

只有私有字段可以被提升

只有 final 字段可以被提升

Getter 不能被提升

外部字段不能被提升

与库中其他地方的 getter 冲突

关于不相关类的注意事项

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

与隐式 noSuchMethod 转发器的冲突

可能在提升后写入

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

在 try 中可能写入后的 catch 中

子类型不匹配

写入被局部函数捕获

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

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

无法提升 `this`

与隐式 `noSuchMethod` 转发器的冲突