如何用JSDoc解决TypeScript 2367类型无重叠比较错误？

问题代码 #

// @ts-check
/** @type {('standalone' | 'export' | undefined)} */
const output = 'standalone';

output === 'export'; // <-- 这里会触发 `typescript 2367` 错误

错误提示 #

TypeScript 2367错误：
该比较似乎是无意的，因为类型'"standalone"'与'"export"'无重叠

问题背景 #

我试过先给值加typedef，也查过一些速查表，但还是不知道怎么解决。请问如何用JSDoc处理这类问题？

解决思路与方法 #

问题根源在于：用const声明并直接赋值字符串字面量时，TypeScript会自动将变量类型收窄为该字面量类型（即'standalone'），而非你通过JSDoc声明的联合类型('standalone' | 'export' | undefined)，因此和'export'比较时会触发类型无重叠的错误。

以下是两种实用的JSDoc解决方式：

方式一：使用类型断言强制保留联合类型

通过在赋值时添加类型断言，明确告诉TypeScript使用你指定的联合类型，覆盖自动收窄的行为：

// @ts-check
const output = /** @type {('standalone' | 'export' | undefined)} */ ('standalone');

output === 'export'; // 不再触发2367错误

方式二：先定义typedef再结合类型断言

如果需要复用这个联合类型，可以先通过@typedef定义，再在赋值时断言类型：

// @ts-check
/** @typedef {'standalone' | 'export' | undefined} OutputType */
const output = /** @type {OutputType} */ ('standalone');

output === 'export'; // 正常通过类型检查

内容的提问来源于stack exchange，提问作者Adrian Miranda