Back

理解 @ts-ignore 以及何时应该使用它

OpenReplay Team OpenReplay Team

Nov 9, 2025 · 2 min read

理解 @ts-ignore 以及何时应该使用它

TypeScript 的类型系统能在错误进入生产环境之前捕获它们,但有时你需要告诉编译器”睁一只眼闭一只眼”。这就是 @ts-ignore 的用武之地——一个 TypeScript 指令,用于抑制下一行代码的编译器错误。虽然它在特定情况下可以救急,但不加思考地使用它会破坏 TypeScript 提供的类型安全性。

本文将解释 @ts-ignore 的作用、它与更安全的 @ts-expect-error 替代方案之间的区别,以及在代码库中何时(如果有的话)应该使用这些 TypeScript 指令。

核心要点

  • @ts-ignore 会静默且永久地抑制 TypeScript 错误,这对长期代码维护来说存在风险
  • @ts-expect-error 是更安全的替代方案,当错误不再存在时会导致构建失败
  • 谨慎使用这些指令——仅用于遗留代码、缺失的第三方类型或临时迁移修复
  • 在抑制错误之前,考虑使用类型断言、类型守卫或适当的类型定义

@ts-ignore 在 TypeScript 中的作用

@ts-ignore 指令是一个注释,它告诉 TypeScript 编译器跳过对下一行的类型检查:

// @ts-ignore
const result: number = "this is actually a string"

如果没有这个指令,TypeScript 会抛出编译器错误,因为你将一个字符串赋值给了类型为 number 的变量。使用 @ts-ignore 后,错误就消失了——永久且静默地消失。

这种行为使 @ts-ignore 特别危险。一旦添加,即使底层问题得到修复,它也不会提供任何反馈。该指令会一直留在你的代码中,可能会隐藏未来更改导致的新 TypeScript 编译器错误。

@ts-ignore vs @ts-expect-error:关键区别

TypeScript 3.9 引入了 @ts-expect-error,这是 @ts-ignore 的更安全替代方案。关键区别在哪里?如果下一行不存在错误,@ts-expect-error 会导致构建失败:

// 使用 @ts-ignore(有风险)
// @ts-ignore
const value: string = getUserName() // 即使修复 getUserName() 后仍然保持静默

// 使用 @ts-expect-error(更安全)
// @ts-expect-error
const value: string = getUserName() // 修复后会抛出 "Unused '@ts-expect-error' directive"

这种自我记录的行为使 @ts-expect-error 更符合 TypeScript 最佳实践。它强制你在底层问题解决后移除该指令,从而在整个代码库中保持类型安全。

何时 @ts-ignore 可能是可接受的

尽管存在风险,但在少数情况下 @ts-ignore 确实有其合理用途:

处理遗留代码

在将 JavaScript 迁移到 TypeScript 时,你可能会遇到难以正确类型化的复杂遗留模式:

// @ts-ignore - 遗留验证逻辑,计划在第二季度重构
return legacyValidator.validateWithCustomRules(data, rules)

没有类型定义的第三方库

某些 npm 包缺少 TypeScript 定义,而创建全面的类型并不总是可行的:

// @ts-ignore - ancient-library@1.0.0 没有可用的 @types 包
import { processData } from 'ancient-library'

临时迁移修复

在大规模重构期间,你可能需要在完成类型更新之前先发布可工作的代码:

// @ts-ignore - 临时:在完成 User 类型迁移后移除 (JIRA-1234)
const user = getOldUserFormat()

过度使用 @ts-ignore 的隐藏成本

代码库中的每个 @ts-ignore 都是技术债务。你面临的风险包括:

// ❌ 不好:隐藏真实的 bug
// @ts-ignore
const total = calculatePrice(items, "invalid-discount-type")

// ✅ 更好:修复实际问题
const total = calculatePrice(items, DiscountType.PERCENTAGE)

抑制 TypeScript 编译器错误意味着:

  • TypeScript 本可以捕获的运行时 bug
  • 由于类型变得不可靠而导致重构更困难
  • IDE 自动完成和 IntelliSense 支持减弱
  • 团队成员无法信任类型而感到困惑

使用 ESLint 强制执行更好的实践

TypeScript ESLint 插件提供了管理指令使用的规则:

{
  "rules": {
    "@typescript-eslint/prefer-ts-expect-error": "error",
    "@typescript-eslint/ban-ts-comment": [
      "error",
      {
        "ts-ignore": "allow-with-description",
        "minimumDescriptionLength": 10
      }
    ]
  }
}

此配置要求提供解释性注释,并鼓励使用 @ts-expect-error 而不是 @ts-ignore,使 TypeScript 指令更加有意识和可追踪。

首先考虑的更好替代方案

在使用 @ts-ignore 之前,请尝试以下方法:

// 选项 1:类型断言(当你比 TypeScript 知道得更多时)
const element = document.getElementById('my-id') as HTMLInputElement

// 选项 2:类型守卫
if (typeof value === 'string') {
  // TypeScript 现在知道 value 是字符串
  console.log(value.toUpperCase())
}

// 选项 3:适当的类型定义
declare module 'untyped-library' {
  export function someFunction(input: string): number
}

结论

@ts-ignore 指令是 TypeScript 的紧急出口——仅在没有其他选择时使用。在几乎所有情况下,@ts-expect-error 都提供了更安全的替代方案,能够在代码库中保持问责制。更好的做法是,投入时间进行适当的类型化、类型断言或类型守卫,以保持使 TypeScript 有价值的类型安全性。

记住:每个被抑制的错误都是一个潜在的等待发生的 bug。保持 TypeScript 编译器错误的可见性,保持类型的诚实性,并尽可能将 @ts-ignore 的使用降至绝对零。

常见问题

不可以,@ts-ignore 只影响紧接着的下一行。对于多行代码,你需要为每一行使用单独的指令,或者考虑将代码包装在具有适当类型的函数中。

不会,@ts-ignore 纯粹是编译时指令。它对运行时性能没有影响,因为 TypeScript 注释在编译为 JavaScript 时会被移除。

使用 IDE 的搜索功能查找所有 @ts-ignore 实例,或者在项目目录中运行 grep 命令,如 grep -r '@ts-ignore' . 来定位它们以供审查。

避免使用 @ts-nocheck,因为它会禁用整个文件的类型检查。如果需要多个抑制,最好解决根本原因或使用带有解释的针对性 @ts-expect-error 注释。

Complete picture for complete understanding

Capture every clue your frontend is leaving so you can instantly get to the root cause of any issue with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.

Check our GitHub repo and join the thousands of developers in our community.

OpenReplay

More articles from OpenReplay Blog