Как отключить проверку типов: @ts-ignore, @ts-expect-error и @ts-nocheck
На этой странице
Комментарий // @ts-ignore отключает проверку типов для следующей строки, // @ts-expect-error делает то же, но сообщит об ошибке, если проверка на строке на самом деле проходит. // @ts-nocheck отключает проверку для всего файла. Все они — крайняя мера: они скрывают реальные проблемы. Предпочтительный порядок: исправить тип → сузить тип → @ts-expect-error с комментарием, почему.
Вопрос
Как отключить проверку типов для конкретной строки кода? Почему @ts-ignore считается антипаттерном и чем его заменить?
Директивы
// @ts-ignore
const result: number = legacyLib.compute(); // ошибка скрыта, даже если строку потом починят
// @ts-expect-error — библиотека возвращает неверный тип, issue #123
const value: string = brokenTypes.getValue();
// @ts-nocheck — в начале файла: проверка всего файла отключена
// @ts-check — в JS-файле: включить проверку| Директива | Область | Если ошибки нет |
|---|---|---|
@ts-ignore | следующая строка | молчит |
@ts-expect-error | следующая строка | сама становится ошибкой «Unused directive» |
@ts-nocheck | весь файл | — |
@ts-check | весь JS-файл | включает проверку |
Почему @ts-ignore — антипаттерн
- скрывает все ошибки строки, включая новые, появившиеся позже;
- после обновления библиотеки ошибка может исчезнуть, а игнор останется навсегда;
- маскирует реальные баги:
undefined, неверные аргументы; - распространяется по кодовой базе и обесценивает проверку типов.
@ts-expect-error лучше: когда проблема будет исправлена, компилятор напомнит удалить директиву. Его же используют в тестах типов, чтобы проверить, что неверный код не компилируется.
Чем заменить
// 1. исправить тип
const user = data as unknown as User; // плохо
const user2 = UserSchema.parse(data); // хорошо: проверка в runtime + тип
// 2. сузить тип
if (typeof value === "string") {
value.toUpperCase();
}
// 3. уточнить типы библиотеки
declare module "legacy-lib" {
export function compute(): number;
}
// 4. non-null assertion — если точно знаете, что значение есть
const root = document.getElementById("root")!;Политика в проекте
Линтер @typescript-eslint/ban-ts-comment позволяет запретить @ts-ignore и @ts-nocheck, а @ts-expect-error разрешить только с описанием:
{
"@typescript-eslint/ban-ts-comment": ["error", { "ts-expect-error": "allow-with-description" }]
}Что важно помнить
- Директивы отключают только проверку типов, но не синтаксические ошибки.
as,!иanyтоже отключают проверку, только менее заметно — относитесь к ним так же осторожно.- При миграции JS → TS временный
@ts-nocheckна файлах — нормальная практика, если есть план их исправить. - На ревью каждый
@ts-expect-errorдолжен иметь объяснение и, по возможности, ссылку на задачу.
Мини-шпаргалка
@ts-ignore— скрыть ошибку строки (избегать).@ts-expect-error— скрыть и напомнить, когда ошибка исчезнет.@ts-nocheck— весь файл, только для миграции.- Сначала исправить или сузить тип.
- Линтер
ban-ts-commentконтролирует использование.
Документация
TypeScript: Comments directives, typescript-eslint: ban-ts-comment.