Linter 规则

设置
状态
快速修复
规则

使用 Dart linter 来识别 Dart 代码中可能存在的问题。您可以通过 IDE 或使用 dart analyze 命令来使用 linter。有关如何启用和禁用单个 linter 规则的信息，请参阅分析器文档的单个规则部分。

此页面列出了所有 linter 规则，以及有关何时可能需要使用每个规则、触发它的代码模式以及如何修复代码的详细信息。

为了避免需要单独选择兼容的 linter 规则，请考虑从 linter 规则集开始，以下包提供了这些规则集

lints: 包含由 Dart 团队策划的两个规则集。我们建议至少使用 core 规则集，该规则集在对上传到 pub.dev 的包进行评分时使用。或者，更好的是，使用 recommended 规则集，它是 core 的超集，可识别其他问题并强制执行样式和格式。如果您正在编写 Flutter 代码，请使用 flutter_lints 包中的规则集，该规则集构建于 lints 之上。

flutter_lints: 包含 flutter 规则集，Flutter 团队鼓励您在 Flutter 应用、包和插件中使用该规则集。此规则集是 recommended 集的超集，而 recommended 集本身又是 core 集的超集，后者部分决定了上传到 pub.dev 的包的分数。

要了解如何使用特定的规则集，请访问有关启用和禁用 linter 规则的文档。

要查找更多预定义的规则集，请查看 pub.dev 上的 #lints 主题。

每个规则都有一个状态或成熟度级别

稳定: 这些规则可以安全使用，并已验证可以在最新版本的 Dart 语言中正常工作。除非标记为实验性、已弃用或已删除，否则所有规则都被认为是稳定的。
实验性: 这些规则仍在评估中，可能永远不会稳定。请谨慎使用这些规则并报告您遇到的任何问题。
已弃用: 不再建议使用这些规则，并且可能会在未来的 Dart 版本中删除。
已删除: 这些规则已在最新的稳定 Dart 版本中删除。

某些规则可以使用快速修复自动修复。快速修复是一种自动编辑，旨在修复 linter 规则报告的问题。

如果规则有快速修复，则可以使用 dart fix 或使用您的支持 Dart 的编辑器来应用。要了解更多信息，请参阅分析问题的快速修复。

以下是所有 linter 规则的索引及其功能的简短描述。要了解有关每个规则的更多信息，请单击其名称。

有关 Dart 3.6.0 中包含所有 linter 规则的自动生成列表，请查看所有 linter 规则。

always_declare_return_types

声明方法返回类型。

always_put_control_body_on_new_line

将控制结构表达式与其语句分开。

always_put_required_named_parameters_first

将必需的命名参数放在前面。

always_require_non_null_named_parameters (已删除)
在没有默认值的命名参数上指定 @required。

always_specify_types

指定类型注解。

always_use_package_imports

避免 lib/ 中文件的相对导入。

annotate_overrides

注解重写的成员。

annotate_redeclares (实验性)

注解重新声明的成员。

avoid_annotating_with_dynamic

在不需要时避免使用 dynamic 注解。

avoid_as (已删除)
避免使用 as。

avoid_bool_literals_in_conditional_expressions
避免在条件表达式中使用 bool 字面量。

avoid_catches_without_on_clauses
避免没有 on 子句的 catch。

avoid_catching_errors
不要显式捕获 Error 或实现它的类型。

avoid_classes_with_only_static_members
避免定义仅包含静态成员的类。

avoid_double_and_int_checks
避免 double 和 int 检查。

avoid_dynamic_calls
避免对 dynamic 目标进行方法调用或属性访问。

avoid_empty_else

避免 else 子句中的空语句。

avoid_equals_and_hash_code_on_mutable_classes
避免在未标记为 @immutable 的类上重载运算符 == 和 hashCode。

avoid_escaping_inner_quotes

通过转换周围的引号来避免转义内部引号。

avoid_field_initializers_in_const_classes
避免在 const 类中使用字段初始值设定项。

avoid_final_parameters
避免为参数声明使用 final。

avoid_function_literals_in_foreach_calls

避免将 forEach 与函数字面量一起使用。

avoid_futureor_void (实验性)
避免使用“FutureOr”作为结果的类型。

avoid_implementing_value_types
不要实现重写 == 的类。

avoid_init_to_null

不要将变量显式初始化为 null。

avoid_js_rounded_ints
避免 JavaScript 四舍五入的整数。

avoid_multiple_declarations_per_line

不要在同一行上声明多个变量。

avoid_null_checks_in_equality_operators

不要在自定义 == 运算符中检查 null。

avoid_positional_boolean_parameters
避免使用位置布尔参数。

avoid_print

避免在生产代码中调用 print。

avoid_private_typedef_functions

避免使用私有类型别名函数。

avoid_redundant_argument_values

避免冗余的参数值。

avoid_relative_lib_imports

避免 lib/ 中文件的相对导入。

avoid_renaming_method_parameters

不要重命名重写方法中的参数。

avoid_return_types_on_setters

避免在 setter 上使用返回类型。

avoid_returning_null (已删除)
避免从返回类型为 bool、double、int 或 num 的成员返回 null。

avoid_returning_null_for_future (已删除)
避免为 Future 返回 null。

avoid_returning_null_for_void

避免为 void 返回 null。

avoid_returning_this
避免从方法返回 this 只是为了启用流畅的接口。

avoid_setters_without_getters
避免使用没有 getter 的 setter。

avoid_shadowing_type_parameters

避免隐藏类型参数。

avoid_single_cascade_in_expression_statements

避免在表达式语句中使用单个级联。

avoid_slow_async_io
避免使用缓慢的异步 dart:io 方法。

avoid_type_to_string
避免在生产代码中使用 .toString()，因为结果可能会被缩小。

avoid_types_as_parameter_names

避免将类型用作参数名称。

avoid_types_on_closure_parameters

避免为函数表达式参数注解类型。

avoid_unnecessary_containers

避免不必要的容器。

avoid_unstable_final_fields (已删除)
避免覆盖 final 字段以在多次调用时返回不同的值。

avoid_unused_constructor_parameters

避免在构造函数中定义未使用的参数。

avoid_void_async

避免返回 void 的 async 函数。

avoid_web_libraries_in_flutter

避免在 Flutter Web 插件包之外使用仅限 Web 的库。

await_only_futures

仅等待 Future。

camel_case_extensions

使用 UpperCamelCase 命名扩展。

camel_case_types

使用 UpperCamelCase 命名类型。

cancel_subscriptions
取消 dart:async StreamSubscription 的实例。

cascade_invocations

在同一引用上级联连续的方法调用。

cast_nullable_to_non_nullable

不要将可空值转换为不可空类型。

close_sinks
关闭 dart:core Sink 的实例。

collection_methods_unrelated_type

使用不相关类型的参数调用各种集合方法。

combinators_ordering

按字母顺序排列组合器名称。

comment_references

仅在文档注释中引用作用域内的标识符。

conditional_uri_does_not_exist
缺少条件导入。

constant_identifier_names

常量名称首选使用 lowerCamelCase。

control_flow_in_finally

避免在 finally 块中使用控制流。

curly_braces_in_flow_control_structures

对所有流程控制结构都使用花括号。

dangling_library_doc_comments

将库文档注释附加到库指令。

depend_on_referenced_packages

依赖于引用的包。

deprecated_consistency
缺少已弃用的注解。

deprecated_member_use_from_same_package

避免在声明已弃用元素的包中使用它们。

diagnostic_describe_all_properties

在调试方法中引用所有公共属性。

directives_ordering

遵守 Effective Dart 指南的指令排序约定。

discarded_futures

不要在非 async 块中调用异步函数。

do_not_use_environment
不要使用环境变量声明的变量。

document_ignores
记录忽略注释。

empty_catches

避免空的 catch 块。

empty_constructor_bodies

对于空的构造函数体，请使用 ; 而不是 {}。

empty_statements

避免空语句。

enable_null_safety (已移除)
请使用健全的空安全。

eol_at_end_of_file

在文件末尾添加一个换行符。

exhaustive_cases

为类似枚举的类中的所有常量定义 case 子句。

file_names

使用 lowercase_with_underscores 命名源文件。

flutter_style_todos

使用 Flutter TODO 格式：// TODO(用户名)：消息，https://URL-to-issue。

hash_and_equals

如果覆盖 ==，请始终覆盖 hashCode。

implementation_imports

不要从另一个包导入实现文件。

implicit_call_tearoffs

将对象用作函数时，请显式拆解 call 方法。

implicit_reopen (实验性)

不要隐式重新打开类。

invalid_case_patterns (实验性)

使用 Dart 3.0 中有效的 case 表达式。

invalid_runtime_check_with_js_interop_types

对于可能无法在平台之间保持一致的 JS 互操作类型，请避免使用运行时类型测试。

invariant_booleans (已移除)
条件不应无条件地计算为 true 或 false。

iterable_contains_unrelated_type (已移除)
使用不相关类型的引用调用 Iterable<E>.contains。

join_return_with_assignment
在可能的情况下，将 return 语句与赋值语句结合起来。

leading_newlines_in_multiline_strings

多行字符串以换行符开头。

library_annotations

将库注释附加到库指令。

library_names
使用 lowercase_with_underscores 命名库。

library_prefixes

指定库前缀时，使用 lowercase_with_underscores。

library_private_types_in_public_api

避免在公共 API 中使用私有类型。

lines_longer_than_80_chars
避免超过 80 个字符的行。

list_remove_unrelated_type (已移除)
使用不相关类型的引用调用 remove。

literal_only_boolean_expressions
仅由字面量组成的布尔表达式。

matching_super_parameters
使用匹配的超参数名称。

missing_code_block_language_in_doc_comment
代码块缺少指定的语言。

missing_whitespace_between_adjacent_strings
相邻字符串之间缺少空格。

no_adjacent_strings_in_list
不要在列表中使用相邻字符串。

no_default_cases (实验性)
无默认情况。

no_duplicate_case_values

不要使用多个具有相同值的 case。

no_leading_underscores_for_library_prefixes

避免库前缀使用前导下划线。

no_leading_underscores_for_local_identifiers

避免局部标识符使用前导下划线。

no_literal_bool_comparisons

不要将布尔表达式与布尔字面量进行比较。

no_logic_in_create_state

不要在 createState 中放置任何逻辑。

no_runtimeType_toString
避免在 runtimeType 上调用 toString()。

no_self_assignments
不要将变量赋值给自己。

no_wildcard_variable_uses

不要使用通配符参数或变量。

non_constant_identifier_names

非常量标识符使用 lowerCamelCase 命名。

noop_primitive_operations

无操作基本操作。

null_check_on_nullable_type_parameter

不要对可能为空的类型参数使用 null 检查。

null_closures

在需要闭包的地方，请勿将 null 作为参数传递。

omit_local_variable_types

省略局部变量的类型注解。

omit_obvious_local_variable_types (实验性)

省略局部变量的明显类型注解。

omit_obvious_property_types (未发布)

省略顶层和静态变量的明显类型注解。

one_member_abstracts
如果简单的函数可以满足需求，请避免定义单成员抽象类。

only_throw_errors
仅抛出扩展 Exception 或 Error 的类的实例。

overridden_fields

不要覆盖字段。

package_api_docs (已弃用)
为所有公共 API 提供文档注释。

package_names

包名使用 lowercase_with_underscores。

package_prefixed_library_names
在库名称前添加包名称和点分隔的路径。

parameter_assignments
不要重新赋值函数或方法的参数引用。

prefer_adjacent_string_concatenation

使用相邻字符串连接字符串字面量。

prefer_asserts_in_initializer_lists
首选将断言放在初始化列表。

prefer_asserts_with_message
首选带有消息的断言。

prefer_bool_in_asserts (已移除)
首选使用布尔值作为断言条件。

prefer_collection_literals

尽可能使用集合字面量。

prefer_conditional_assignment

首选使用 ??= 而不是测试 null。

prefer_const_constructors

对常量构造函数首选使用 const。

prefer_const_constructors_in_immutables

在 @immutable 类上首选声明 const 构造函数。

prefer_const_declarations

对于声明，首选 const 而不是 final。

prefer_const_literals_to_create_immutables

在 @immutable 类上，首选常量字面量作为构造函数的参数。

prefer_constructors_over_static_methods
首选定义构造函数而不是静态方法来创建实例。

prefer_contains

对 List 和 String 实例使用 contains。

prefer_double_quotes

在不需要转义序列时首选使用双引号。

prefer_equal_for_default_values (已移除)
使用 = 分隔命名参数及其默认值。

prefer_expression_function_bodies

对于主体是单个 return 语句的短成员，请使用 =>。

prefer_final_fields

私有字段可以设为 final。

prefer_final_in_for_each

如果引用未重新赋值，则在 for-each 循环变量中首选 final。

prefer_final_locals

如果变量声明未重新赋值，则首选 final。

prefer_final_parameters

如果参数声明未重新赋值，则首选 final。

prefer_for_elements_to_map_fromIterable

从可迭代对象构建 Map 时，首选 for 元素。

prefer_foreach
仅将函数应用于所有元素时，请使用 forEach。

prefer_function_declarations_over_variables

使用函数声明将函数绑定到名称。

prefer_generic_function_type_aliases

首选泛型函数类型别名。

prefer_if_elements_to_conditional_expressions

尽可能首选 if 元素而不是条件表达式。

prefer_if_null_operators

首选使用 ?? 运算符。

prefer_initializing_formals

尽可能使用初始化形式参数。

prefer_inlined_adds

尽可能内联列表项声明。

prefer_int_literals

首选整数字面量而不是双精度字面量。

prefer_interpolation_to_compose_strings

使用插值来组合字符串和值。

prefer_is_empty

对 Iterable 和 Map 使用 isEmpty。

prefer_is_not_empty

对 Iterable 和 Map 使用 isNotEmpty。

prefer_is_not_operator

首选 is! 运算符。

prefer_iterable_whereType

首选在可迭代对象上使用 whereType。

prefer_mixin
首选使用 mixins。

prefer_null_aware_method_calls
首选可空感知的方法调用。

prefer_null_aware_operators

首选使用可空感知的运算符。

prefer_relative_imports

对于 lib/ 中的文件，首选相对导入。

prefer_single_quotes

仅对包含单引号的字符串使用双引号。

prefer_spread_collections

尽可能使用展开集合。

prefer_typing_uninitialized_variables

首选为未初始化的变量和字段键入类型。

prefer_void_to_null

除非您确定不需要 void，否则不要使用 Null 类型。

provide_deprecation_message

通过 @Deprecated("message") 提供弃用消息。

public_member_api_docs
为所有公共成员编写文档。

recursive_getters

属性 getter 递归返回自身。

require_trailing_commas

所有参数列表和实参列表都使用尾随逗号。

secure_pubspec_urls

在 pubspec.yaml 中使用安全 URL。

sized_box_for_whitespace

使用 SizedBox 作为空白。

sized_box_shrink_expand
使用 SizedBox 的 shrink 和 expand 命名构造函数。

slash_for_doc_comments

优先使用 /// 作为文档注释。

sort_child_properties_last

在 widget 实例创建中将子属性排序到最后。

sort_constructors_first

将构造函数声明排序在其他成员之前。

sort_pub_dependencies
按字母顺序对 pub 依赖项进行排序。

sort_unnamed_constructors_first

将未命名的构造函数声明排序在最前面。

specify_nonobvious_local_variable_types (实验性)

为局部变量指定非显式的类型注解。

specify_nonobvious_property_types (未发布)

为顶层和静态变量指定非显式的类型注解。

super_goes_last (已移除)
在构造函数初始化列表中将 super 调用放在最后。

test_types_in_equals
在 operator ==(Object other) 中测试参数的类型。

throw_in_finally
避免在 finally 代码块中使用 throw。

tighten_type_of_initializing_formals
收紧初始化形式参数的类型。

type_annotate_public_apis

为公共 API 添加类型注解。

type_init_formals

不要为初始化形式参数添加类型注解。

type_literal_in_constant_pattern

不要在常量模式中使用类型字面量。

unawaited_futures

async 函数体中的 Future 结果必须使用 await 或使用 dart:async 标记为 unawaited。

unintended_html_in_doc_comment

Markdown 会将文档注释中的尖括号视为 HTML。

unnecessary_await_in_return

在 return 中不必要的 await 关键字。

unnecessary_brace_in_string_interps

在不需要时避免在字符串插值中使用花括号。

unnecessary_breaks

当已经隐含了 break 时，不要使用显式的 break。

unnecessary_const

避免使用 const 关键字。

unnecessary_constructor_name

不必要的 .new 构造函数名。

unnecessary_final

不要对局部变量使用 final。

unnecessary_getters_setters

避免为了“安全”而将字段包装在 getter 和 setter 中。

unnecessary_lambdas

当使用 tear-off 即可时，不要创建 lambda。

unnecessary_late

在不需要时不要指定 late 修饰符。

unnecessary_library_directive

除非库指令有文档注释或注解，否则避免使用它们。

unnecessary_library_name

在 library 声明中不要包含库名称。

unnecessary_new

不必要的 new 关键字。

unnecessary_null_aware_assignments

避免在 null 感知赋值中使用 null。

unnecessary_null_aware_operator_on_extension_on_nullable
对可空类型的扩展使用不必要的 null 感知运算符。

unnecessary_null_checks (实验性)

不必要的 null 检查。

unnecessary_null_in_if_null_operators

避免在 ?? 运算符中使用 null。

unnecessary_nullable_for_final_variable_declarations

对于使用非空值初始化的 final 变量，使用非空类型。

unnecessary_overrides

不要重写一个方法来使用相同的参数进行 super 方法调用。

unnecessary_parenthesis

可以删除不必要的括号。

unnecessary_raw_strings

不必要的原始字符串。

unnecessary_statements
避免使用不必要的语句。

unnecessary_string_escapes

删除字符串中不必要的反斜杠。

unnecessary_string_interpolations

不必要的字符串插值。

unnecessary_this

除非为了避免阴影，否则不要使用 this 访问成员。

unnecessary_to_list_in_spreads

在 spread 中不必要的 toList()。

unreachable_from_main

在可执行库中不可达的顶层成员。

unrelated_type_equality_checks

使用无关类型的引用调用相等运算符 ==。

unsafe_html (已移除)
避免使用不安全的 HTML API。

unsafe_variance (未发布)
不安全的类型：在非协变位置具有类型变量。

use_build_context_synchronously

不要在异步间隙中使用 BuildContext。

use_colored_box

使用 ColoredBox。

use_decorated_box

使用 DecoratedBox。

use_enums

使用枚举而不是行为类似于枚举的类。

use_full_hex_values_for_flutter_colors

优先使用 8 位十六进制整数（例如，0xFFFFFFFF）来实例化 Color。

use_function_type_syntax_for_parameters

对参数使用泛型函数类型语法。

use_if_null_to_convert_nulls_to_bools
使用 ?? 运算符将 null 转换为 bool。

use_is_even_rather_than_modulo
优先使用 intValue.isOdd/isEven，而不是检查 % 2 的结果。

use_key_in_widget_constructors

在 widget 构造函数中使用 key。

use_late_for_private_fields_and_variables (实验性)
对具有非空类型的私有成员使用 late。

use_named_constants

使用预定义的命名常量。

use_raw_strings

使用原始字符串以避免转义。

use_rethrow_when_possible

使用 rethrow 来重新抛出捕获的异常。

use_setters_to_change_properties
对概念上更改属性的操作使用 setter。

use_string_buffers
使用字符串缓冲区来组合字符串。

use_string_in_part_of_directives

在 part of 指令中使用字符串。

use_super_parameters (实验性)

尽可能使用 super-initializer 参数。

use_test_throws_matchers
使用 throwsA 匹配器而不是 fail()。

use_to_and_as_if_applicable
如果适用，请以 to/_to 或 as/_as 开头方法名称。

use_truncating_division

使用截断除法。

valid_regexps

使用有效的正则表达式语法。

void_checks

不要赋值给 void。

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

Linter 规则

设置

状态

快速修复

规则