企业官网建设流程全解析

• 开发工具
• 静态分析
• 代码质量

导读

Flow 的类型信息不仅能用来证明程序正确性，还能支撑一套内建 Linting 框架，在类型错误之外帮助你发现"可能有害"的代码模式。本文以 Flow 官方在 2017 年引入 Linter 的公告为起点，系统讲解 Lint 的三种配置方式（.flowconfig、--lints命令行参数、flowlint注释）、三种严重级别（off/warn/error）及其优先级规则，并结合当前仓库中的文档与源码，逐条解读sketchy-null、unclear-type、untyped-import等核心 Lint 规则的触发场景与修复方式。读完本文，你将能够在自己项目中正确配置、调试并逐步收紧 Flow 的 Lint 规则，让类型检查器同时充当代码质量守卫。

:::info[历史背景] 本主题源自 Flow 官方博客在 2017 年 8 月发布的《Linting in Flow》，该文章宣布了 Flow Linter 的正式引入。其当前语法与行为以 Linting 文档 为准。 :::

一、从"类型检查"到"代码检查"：Flow Linter 的定位

Flow 的类型系统在证明程序正确性之外，还掌握了每个表达式的精确类型信息，而这些信息恰好可以用于发现一类类型检查器默认不会报错、但实践中极易出问题的编码模式。Flow Linter 正是基于这一理念构建的：它复用类型推断的结果，把"潜在有害"的代码模式以 lint 规则的形式暴露出来，并按项目需求配置严重级别。

与 ESLint 这类纯语法/语义的 linter 不同，Flow 的 Lint 规则天然具备类型上下文，例如：

• sketchy-null需要知道某个值是否可能同时为null与0这样的 falsy 值；
• untyped-import需要知道被导入的文件是否经过类型检查；
• unnecessary-assertion需要根据类型信息判断某个invariant条件是否必然为真。

这类判断只有类型检查器本身才能可靠完成，这正是 Flow 内建 Linter 的价值所在。

二、Lint 严重级别：off / warn / error

Flow Lint 规则支持三种严重级别，对应源码中 severity.rs 定义的Severity枚举：

在源码实现中，Severity的字符串形式为off/warn/error（见 severity.rs 的severity_of_str），无效级别会直接报错："Valid settings are error, warn, and off."。

三、三种配置方式

Lint 设置可以在三个层级配置，按优先级从高到低依次是：flowlint注释 >--lints命令行参数 >.flowconfig。这个顺序的设计意图是：用flowlint注释做细粒度控制，用--lints参数临时试跑新规则，用.flowconfig固化项目级稳定设置。

3.1 在.flowconfig的[lints]段配置

在.flowconfig中新增[lints]段，每行一个规则=级别键值对，对整个项目全局生效：

[lints] all=warn untyped-type-import=error sketchy-null-bool=off

对应的解析逻辑位于 flowconfig.rs，其内部通过LintSettings::of_lines把[lints]段的每一行解析为规则条目，并合并进config.lint_severities。

同一配置内"后写的覆盖先写的"，这允许先开大类再关子类。例如：

[lints] # 对全部 sketchy-null 检查发出警告 sketchy-null=warn # 但布尔类型的除外 sketchy-null-bool=off

all是一个特殊"规则"，它并不是真正的 lint 规则，而是用于设置所有未显式配置规则的默认级别。它只能作为[lints]的第一条或--lints参数的第一个规则出现，且不允许出现在注释中（因为注释中的语义会与预期不同）。这一点在解析器中有强制：源码 lint_settings.rs 中，若all不是第一条设置会直接报错"all" is only allowed as the first setting. Settings are order-sensitive.。

3.2 通过--lints命令行参数配置

启动 Flow 服务器时传入--lints标志，使用逗号分隔的规则=级别列表，同样全局生效：

flow start --lints "all=warn, untyped-type-import=error, sketchy-null-bool=off"

这特别适合在正式写入.flowconfig之前临时试跑某些规则。底层实现上，命令行中的每条规则同样进入LintSettings::of_lines解析流程（见 flowconfig.rs），因此与.flowconfig共享完全相同的语法、错误检查与顺序语义。

3.3 通过flowlint注释在文件内配置

flowlint注释提供文件内最细粒度的控制，支持三种形式：flowlint、flowlint-line、flowlint-next-line。所有形式中，单词之间的空格和星号都会被忽略，因此排版可以很灵活。

flowlint——覆盖到文件末尾，直到被覆盖：

• 覆盖一段代码块：

import type { // flowlint untyped-type-import:off Foo, Bar, Baz, // flowlint untyped-type-import:error } from './untyped.js';

• 覆盖整个文件（不成对的注释自动延伸到文件末尾）：

// flowlint sketchy-null:off ...

• 覆盖一行中的某一部分（设置从注释本身所在位置开始生效，可用于比行级注释更精细的控制）：

function foo(a: ?boolean, b: ?boolean) { if (/* flowlint sketchy-null-bool:off */a/* flowlint sketchy-null-bool:warn */ && b) { ... } else { ... } }

flowlint-line——仅对当前行生效，主要用于压制某一行的 lint：

function foo(x: ?boolean) { if (x) { // flowlint-line sketchy-null-bool:off ... } else { ... } }

flowlint-next-line——对下一行生效：

function foo(x: ?boolean) { // flowlint-next-line sketchy-null-bool:off if (x) { ... } else { ... } }

3.4 配置的防错机制

Lint 设置解析器相当"聪明"，会在以下情形主动拦截，防止误配置：

• 写了冗余规则（该参数不会改变任何 lint 设置，如 lint_settings.rs 中的"Redundant argument. This argument doesn't change any lint settings."）；
• 规则被完全覆盖（后写的规则把前面规则的效果全部抹掉）；
• 存在未被使用的flowlint压制注释；
• 规则格式错误（缺少=、无效规则名、无效级别等，见 lint_settings.rs）。

四、核心 Lint 规则解读

完整的规则参考见 Lint 规则参考，源码层面所有规则名定义于 lints.rs。以下按典型使用场景分组介绍最常用的规则。

4.1 可疑的假值检查：sketchy-null 家族

sketchy-null在"对可能是 null/undefined 或 falsy 的值做存在性检查"时触发。例如const x: ?number = 5; if (x) {}之所以 sketchy，是因为x可能为0（falsy）也可能为null，二者语义不同却都被if (x)排除。

sketchy-null是家族总开关，另有按类型细分的子规则：

• sketchy-null-bool
• sketchy-null-number
• sketchy-null-string
• sketchy-null-mixed
• sketchy-null-bigint

源码 lints.rs 显示，sketchy-null一条规则会展开为Bool / String / Number / BigInt / Mixed / EnumBool / EnumString / EnumNumber / EnumBigInt共九种SketchyNullKind，因此总开关天然继承所有子规则。子规则的价值在于选择性放行：例如允许布尔 sketchy 检查（把"可选布尔当作 false"的惯用法），同时禁止其余类型：

[lints] sketchy-null=warn sketchy-null-bool=off

注意子规则的压制只影响对应类型，例如// flowlint sketchy-null:error, sketchy-null-bool:off后，const x: ?(number | boolean) = 0; if (x) {}仍会因sketchy-null-number报错。

4.2 sketchy-number：数字出现在&&左侧

sketchy-number目前在number出现在&&表达式左侧时触发。经典的 React 陷阱是：

{count && <>[{count} comments]</>}

count为0时会渲染出可见的"0"（0和NaN是仅有的 React 会渲染出可见结果的 falsy 值），可能让用户误以为数字被放大了十倍。正确写法是显式条件判断：

{count ? <>[{count} comments]</> : null}

4.3 不安全的类型：unclear-type 与 deprecated-type

• unclear-type：使用any、Object、Function作为类型注解时触发，这些类型不安全。
• deprecated-type：对bool类型触发，它是boolean的别名，直接用boolean即可。

4.4 未类型化的导入：untyped-import 与 untyped-type-import

• untyped-import：从未类型化文件导入时触发——这些导入会被类型化为any，不安全。
• untyped-type-import：从未类型化文件导入类型时触发——结果是一个any别名，通常并非预期。开启该规则能限制隐式any的扩散，提升类型覆盖度。

4.5 unsafe-getters-setters 与 unsafe-object-assign

• unsafe-getters-setters：使用 getter/setter 时触发，因为它们可能带副作用。
• unsafe-object-assign：任何Object.assign的使用都会触发（默认即 error）。Object.assign原地修改第一个参数，类型系统难以追踪；改用对象展开{...defaults, ...overrides}更安全，因为每次都会创建新对象，Flow 也能精确推断其类型。

4.6 unnecessary-assertion（原 unnecessary-invariant）

当invariant检查的条件在类型信息上已知必然为真时触发。规则相当保守：例如只知道条件是boolean时不会触发。注意：条件必然为假时不会触发，因为invariant(false, ...)抛异常表示"不可达代码"是常见惯用法。旧名unnecessary-invariant仍被配置和压制注释接受（源码 lints.rs 明确保留该兼容名）。

4.7 unnecessary-optional-chain

?.用在不必要的位置时触发，分两种情况：

• 左侧不可能为 nullish 时，如foo?.bar（foo类型明确为Foo）；
• 左侧可能 nullish，但短路行为已经足够时，如foo?.bar?.baz（foo是?Foo）：第二个?.冗余，写成foo?.bar.baz反而让读者明白bar不是潜在 nullish 属性。

4.8 unused-promise

Promise未被使用即触发，因为错误可能未处理、执行顺序也可能不符合预期。await、带拒绝处理器的.then、.catch、.finally、存储到变量/传给函数等都算"使用"。显式忽略可用void运算符：void foo();。

4.9 面向 React 组件语法的规则

• nested-component（默认 error）：组件定义在另一个组件或 hook 内部时触发。React 无法在父组件重渲染间保留嵌套组件状态——每次渲染都会创建全新组件类型，导致 React 总是卸载再重挂载。修复方式是移到顶层。
• nested-hook（默认 error）：hook 定义在另一个组件或 hook 内部时触发，会破坏 Hooks 规则。同样应移至顶层。
• react-intrinsic-overlap（默认 off）：局部定义与 JSX 内建元素同名（如div、span）且类型可能作为 React 组件使用时触发。JSX 中<div />永远指 HTML 元素，改名即可。

这些规则仅在component_syntax=true的.flowconfig下作用于组件/hook 语法声明。

4.10 其他规则

• nonstrict-import：与@flow strict配合，当从非@flow strict模块导入时触发，保证严格模块的依赖同样严格。
• internal-type（默认 error）：直接使用内部 Flow 类型（如$Omit、React$Node）时触发，应改用Omit、React.Node等公开等价形式。
• invalid-this-arg（默认 error）：用call/apply/bind给方法传入非来源对象作为接收者时触发（如counter.increment.call(other)），允许的形式是obj.method.call(obj, ...)与this.method.bind(this)。
• libdef-override（默认 error）：库定义文件覆盖内建定义（名称覆盖、模块覆盖，或同一库文件被重复包含）时触发，可用$FlowFixMe[libdef-override]压制或项目级libdef-override=off。
• ambiguous-object-type：对象类型语法未显式说明精确/非精确时触发，{x: number}报错，{x: number, ...}与{| x: number |}均可。

五、命令行与配置的完整工作流

综合以上内容，一个典型的上手流程是：

1. 用--lints参数临时试跑感兴趣规则，确认其在你代码库中的噪音水平：

flow start --lints "all=warn, untyped-type-import=error"

2. 在.flowconfig中固化项目级设置，利用"后写覆盖先写"组织大类与子类例外。
3. 对个别文件/行用flowlint、flowlint-line、flowlint-next-line注释做定点控制。
4. 通过--include-warnings或include_warnings=true查看全部警告，逐步把团队代码收敛到目标级别。

六、总结

Flow Linter 把类型信息从"证明正确"延伸到"发现有害模式"，通过三级配置（.flowconfig、--lints、flowlint注释）和三级严重级别（off/warn/error）提供了从项目全局到单行局部、从稳定配置到临时试跑的完整控制粒度。其解析器内置的冗余规则、顺序敏感和未使用压制检测，能有效防止误配置。

从 2017 年首次引入至今，该框架在仓库中已演化为flow_lint_settings这一独立 crate（见 lints.rs），规则数量从最初的几个扩展到了覆盖 sketchy 检查、React 组件/hook 语法、导入严格性、内部类型使用等二十余类。若想进一步了解所有规则与默认级别，可直接查阅 Lint 规则参考；更深入的flowlint注释语法见 Flowlint 注释文档；.flowconfig的[lints]段说明见 配置文件文档。

• 开发工具
• 静态分析
• 代码质量