Понимание @ts-ignore и когда его следует использовать

Система типов TypeScript обнаруживает ошибки до того, как они попадут в продакшен, но иногда нужно сказать компилятору, чтобы он закрыл на что-то глаза. Именно для этого существует @ts-ignore — директива TypeScript, которая подавляет ошибки компилятора для следующей строки кода. Хотя она может быть спасением в определённых ситуациях, небрежное использование подрывает саму типобезопасность, которую обеспечивает TypeScript.

В этой статье объясняется, что делает @ts-ignore, чем она отличается от более безопасной альтернативы @ts-expect-error, и когда (если вообще когда-либо) следует использовать эти директивы TypeScript в вашей кодовой базе.

Что делает @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 прерывает сборку, если на следующей строке нет ошибки:

// Using @ts-ignore (risky)
// @ts-ignore
const value: string = getUserName() // Silent even after fixing getUserName()

// Using @ts-expect-error (safer)
// @ts-expect-error
const value: string = getUserName() // Throws "Unused '@ts-expect-error' directive" when fixed

Это самодокументирующееся поведение делает @ts-expect-error предпочтительной для лучших практик TypeScript. Она заставляет вас удалить директиву после решения базовой проблемы, поддерживая типобезопасность во всей кодовой базе.

Когда @ts-ignore может быть приемлемой

Несмотря на риски, существуют редкие сценарии, где @ts-ignore служит законной цели:

Работа с легаси-кодом

При миграции JavaScript на TypeScript вы можете столкнуться со сложными легаси-паттернами, которые трудно правильно типизировать:

// @ts-ignore - Legacy validation logic, refactoring planned for Q2
return legacyValidator.validateWithCustomRules(data, rules)

Сторонние библиотеки без типов

Некоторые npm-пакеты не имеют определений TypeScript, и создание исчерпывающих типов не всегда выполнимо:

// @ts-ignore - No @types package available for ancient-library@1.0.0
import { processData } from 'ancient-library'

Временные исправления при миграции

Во время масштабного рефакторинга вам может потребоваться выпустить рабочий код до завершения обновления типов:

// @ts-ignore - Temporary: Remove after completing User type migration (JIRA-1234)
const user = getOldUserFormat()

Скрытые издержки чрезмерного использования @ts-ignore

Каждая @ts-ignore в вашей кодовой базе — это технический долг. Вот что вы рискуете получить:

// ❌ Bad: Hiding a real bug
// @ts-ignore
const total = calculatePrice(items, "invalid-discount-type")

// ✅ Better: Fix the actual issue
const total = calculatePrice(items, DiscountType.PERCENTAGE)

Подавление ошибок компилятора TypeScript означает:

• Ошибки времени выполнения, которые TypeScript мог бы обнаружить
• Более сложный рефакторинг, поскольку типы становятся ненадёжными
• Снижение поддержки автодополнения 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, попробуйте эти подходы:

// Option 1: Type assertions (when you know more than TypeScript)
const element = document.getElementById('my-id') as HTMLInputElement

// Option 2: Type guards
if (typeof value === 'string') {
  // TypeScript now knows value is a string
  console.log(value.toUpperCase())
}

// Option 3: Proper type definitions
declare module 'untyped-library' {
  export function someFunction(input: string): number
}

Заключение

Директива @ts-ignore — это аварийный выход TypeScript — используйте её только когда не существует других вариантов. Практически в каждом случае @ts-expect-error предоставляет более безопасную альтернативу, которая поддерживает подотчётность в вашей кодовой базе. Ещё лучше — инвестируйте время в правильную типизацию, утверждения типов или защитники типов, чтобы сохранить типобезопасность, которая делает TypeScript ценным.

Помните: каждая подавленная ошибка — это потенциальный баг, ожидающий своего часа. Держите ошибки компилятора TypeScript видимыми, ваши типы честными, а использование @ts-ignore на абсолютном нуле, когда это возможно.

Часто задаваемые вопросы

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.