TypeScript TS2367 — 比较无重叠

症状

遇到“TypeScript TS2367 — 比较无重叠”时靠猜测只会浪费时间。请按证据排查：先复现症状，再执行针对性诊断，定位根因后修复，并用明确检查验证结果。

可观察到的症状包括：

• error TS2367: This comparison appears to be unintentional because the types have no overlap
• 收窄联合类型后某 status === 检查报错
• 类型收紧后代码不再编译

诊断

先在隔离环境中复现故障，再按顺序执行以下检查，逐步缩小范围。

步骤 1

npx tsc --noEmit 2>&1 | grep TS2367

消息显示两个被比较的类型，暴露不可能成立的分支。

步骤 2

grep -n "type Status\|: '\w*'" src/status.ts

对比声明的联合与实际值，决定是放宽类型还是移除检查。

常见诱因（按出现频率排序）：

• 比较使用了该联合类型不可能持有的字面量
• 先前的收窄已排除被比较的值
• 变量类型比运行期值更窄，暗示类型声明有误

根因

当两个操作数依据静态类型不可能重叠、该分支永不为真时，TypeScript 报 TS2367。它常提示陈旧的收窄，或类型不再匹配运行期数据。

修复

移除不可能成立的检查，放宽类型以包含运行期值，或修正被错误收窄的类型；不要用转换来压制。

注意：用 any 绕过 TS2367 会掩盖真实不匹配，导致运行期异常。

type Status = 'idle' | 'running' | 'done';

function label(s: Status) {
  if (s === 'running') return 'busy';
  if (s === 'done') return 'finished';
  // ❌ if (s === 'cancelled') return 'x'; // TS2367: no overlap with Status
  return 'idle';
}

// fix the union when the runtime really can be 'cancelled'
type Status2 = Status | 'cancelled';

验证

运行 tsc –noEmit 并确认 TS2367 消失；补充用例覆盖此前不可能的值并断言预期行为。

修复后补充一条回归测试，复现原始症状，防止问题再次出现。

这类故障通常是环境问题而非纯逻辑错误，因此在缺陷记录中应写明完整命令、环境变量与工作目录。请用最小的脚本复现，待最小用例清楚后再扩大范围。为这类故障准备一份简短的排查清单，能显著减少下次排障时间。