Настройка VS Code и TypeScript для неиспользуемых аргументов

Чтобы настроить VS Code и TypeScript для обработки неиспользуемых аргументов с префиксом _, нужно включить опции noUnusedParameters и noUnusedLocals в tsconfig.json, а затем сконфигурировать визуальные настройки редактора через settings.json. TypeScript автоматически исключает из проверок параметры, начинающиеся с подчёркивания, а затемнение неиспользуемых переменных в редакторе регулируется отдельно — через editor.showUnused.

Содержание

• Почему это вообще нужно
• Настройка компилятора TypeScript
• Визуальные настройки VS Code
• Префикс подчёркивания и как он работает
• Полный пример конфигурации
• Решение частых проблем
• Источники
• Заключение

Почему это вообще нужно

Неиспользуемые переменные — это шум в коде. Они отвлекают при чтении, намекают на недописанную логику, а в больших проектах накапливаются и превращаются в технический долг. Но есть нюанс: иногда параметр функции нужен по сигнатуре, хотя внутри тела вы его не используете. Классический пример — колбэки:

array.forEach((_item, index) => {
 console.log(index);
});

Здесь _item не используется, но без него не обойтись — иначе index станет первым аргументом. Конфликт: с одной стороны, хочется видеть предупреждения обо всех лишних переменных. С другой — не нужно, чтобы компилятор постоянно ругался на параметры-«заглушки». Именно эту задачу решает связка из двух инструментов: компилятор TypeScript определяет, что считать ошибкой, а VS Code отвечает за то, как это отображается визуально.

Настройка компилятора TypeScript

За контроль неиспользуемых переменных и параметров отвечают две опции в секции compilerOptions файла tsconfig.json.

noUnusedParameters

Согласно официальной документации TypeScript, опция noUnusedParameters заставляет компилятор сообщать об ошибке на каждый неиспользуемый параметр функции. Включается так:

{
 "compilerOptions": {
 "noUnusedParameters": true
 }
}

После этого вызов вроде function greet(name: string, age: number) { return name; } вызовет диагностическое сообщение: 'age' is declared but its value is never read.

Но что если параметр нужен формально? Вот тут и вступает в игру правило подчёркивания: любой параметр, имя которого начинается с _, автоматически исключается из проверки. Это встроенное поведение компилятора — никаких дополнительных опций для этого не требуется.

// Ошибка: 'age' is declared but its value is never read
function greet(name: string, age: number) {
 return name;
}

// Ошибки нет — параметр с префиксом _ игнорируется
function greet(name: string, _age: number) {
 return name;
}

noUnusedLocals

Вторая опция — noUnusedLocals — делает то же самое, но для локальных переменных, объявленных внутри функции или блока:

{
 "compilerOptions": {
 "noUnusedLocals": true,
 "noUnusedParameters": true
 }
}

Обе опции можно включить одновременно. Это даёт максимально строгий режим: каждая объявленная, но не использованная сущность будет подсвечена как ошибка.

Важно: эти опции влияют только на диагностику компилятора — то есть на то, появляется ли волнистая линия и сообщение об ошибке. На визуальное затемнение текста они не влияют. Это разные слои.

Визуальные настройки VS Code

Теперь разберёмся с визуальной частью. В VS Code за отображение неиспользуемых переменных отвечает параметр editor.showUnused. Он контролирует, как именно редактор показывает переменные, которые определены, но нигде не используются.

Значения editor.showUnused

Параметр принимает три значения:

Нас интересует "inline" — именно он даёт затемнение. Откройте settings.json (через палитру команд: Preferences: Open User Settings (JSON)):

{
 "editor.showUnused": "inline"
}

Цвет затемнения

По умолчанию VS Code использует полупрозрачный текст для неиспользуемых переменных. Если хотите настроить оттенок, добавьте в workbench.colorCustomizations:

{
 "workbench.colorCustomizations": {
 "editorGhostText.foreground": "#6a737d",
 "editorUnnecessaryCode.opacity": "#00000080"
 }
}

Ключ editorUnnecessaryCode.opacity контролирует степень затемнения. Значение в формате HEX с альфа-каналом: 80 в конце — это примерно 50% прозрачности.

Ключевой момент

А вот тут кроется важная деталь, которую часто упускают. VS Code определяет «неиспользуемость» на основе языкового сервера. Для TypeScript это встроенный tsserver, который читает настройки из tsconfig.json. Когда noUnusedLocals и noUnusedParameters включены, языковой сервер передаёт редактору информацию о том, какие переменные неиспользуемы. VS Code, в свою очередь, применяет к ним стиль editor.showUnused.

Получается цепочка:

tsconfig.json (noUnusedLocals / noUnusedParameters)
 ↓
 tsserver анализирует код и помечает переменные
 ↓
 VS Code получает диагностические данные
 ↓
 editor.showUnused определяет визуальный стиль

Префикс подчёркивания и как он работает

Это, пожалуй, самая интересная часть. Давайте разделим поведение на три уровня.

Уровень 1: Диагностика TypeScript

Когда noUnusedParameters включён, компилятор проверяет каждый параметр. Если имя начинается с _ — проверка пропускается. Это зафиксировано в документации компилятора. Работает для любого количества подчёркиваний: _, __, _unusedArg — всё допустимо.

Уровень 2: Диагностика VS Code

VS Code получает от tsserver те же данные. Если параметр с _ не помечен как ошибка компилятором, то и волнистой линии в редакторе не будет. Требование №2 из вопроса — выполнено.

Уровень 3: Затемнение

А вот тут начинается тонкость. Даже если компилятор «прощает» параметр с _, языковой сервер всё равно знает, что переменная технически неиспользуема. И VS Code, в зависимости от внутренней логики tsserver, может продолжать показывать её затемнённой.

На практике (начиная с TypeScript 4.x и выше) tsserver отправляет для параметров с _ диагностический тег unnecessary — тот же, что и для обычных неиспользуемых переменных. Разница лишь в том, что уровень серьёзности (severity) для _-параметров снижен: вместо ошибки это информация или предупреждение.

Что это значит для визуального отображения? Если editor.showUnused установлен в "inline", то параметр _foo будет затемнён, но без волнистой красной линии. Он останется полупрозрачным — что как раз и соответствует вашему третьему требованию.

Если вдруг на вашей версии tsserver этого не происходит (поведение может отличаться между версиями TypeScript), можно добавить дополнительную настройку:

{
 "typescript.tsserver.experimental.enableProjectDiagnostics": false
}

Или, как более надёжный вариант, использовать расширение вроде Error Lens, которое позволяет гибко кастомизировать отображение диагностики.

Полный пример конфигурации

Собираем всё вместе. Вот минимальный набор настроек, который реализует все три требования из вопроса.

tsconfig.json

{
 "compilerOptions": {
 "target": "ES2020",
 "module": "ESNext",
 "strict": true,
 "noUnusedLocals": true,
 "noUnusedParameters": true,
 "outDir": "./dist",
 "rootDir": "./src"
 },
 "include": ["src/**/*"]
}

.vscode/settings.json (на уровне проекта)

{
 "editor.showUnused": "inline",
 "typescript.tsdk": "node_modules/typescript/lib",
 "typescript.enablePromptUseWorkspaceTsdk": true
}

Параметр typescript.tsdk указывает VS Code использовать версию TypeScript из node_modules проекта, а не встроенную. Это гарантирует, что поведение диагностики совпадает с тем, что вы получите при сборке через tsc.

Проверяем на примере

// main.ts

// ❌ Ошибка: 'unusedVar' is declared but its value is never read
// 🔅 Затемнена + волнистая линия
const unusedVar = 42;

// ✅ Ошибки нет (префикс _), но 🔅 затемнена
const _configValue = "something";

// ❌ Ошибка: 'y' is declared but its value is never read
// 🔅 Затемнена + волнистая линия
function add(x: number, y: number) {
 return x;
}

// ✅ Ошибки нет (префикс _), но 🔅 затемнена
function process(data: string, _options: object) {
 return data.toUpperCase();
}

// Типичный реальный сценарий
["a", "b", "c"].forEach((_char, i) => {
 console.log(`Index: ${i}`);
});

Итого по трём пунктам:

Решение частых проблем

«Включил опции, но ничего не происходит»

Самая распространённая причина — VS Code использует встроенную версию TypeScript, а не ту, что в вашем проекте. Откройте палитру команд (Ctrl+Shift+P / Cmd+Shift+P) и выполните TypeScript: Select TypeScript Version. Выберите Use Workspace Version. Если этого пункта нет, добавьте в settings.json:

{
 "typescript.tsdk": "node_modules/typescript/lib"
}

После этого перезапустите языковой сервер: TypeScript: Restart TS Server.

«Параметры с _ показывают ошибку»

Проверьте версию TypeScript. Поддержка автоматического исключения _-параметров из проверки noUnusedParameters существует давно, но в очень старых версиях (до 2.x) поведение могло отличаться. Обновите:

npm install typescript@latest --save-dev

«Неиспользуемые переменные не затемняются»

Убедитесь, что editor.showUnused установлен в "inline", а не в "off". Также проверьте, не переопределяет ли какая-то тема или расширение цвет неиспользуемого кода. Попробуйте временно переключиться на стандартную тему (например, Default Dark+) и проверить.

Ещё одна возможная причина — файл не включён в tsconfig.json через include или files. Если файл вне области действия tsconfig, tsserver не анализирует его по полным правилам.

«Хочу, чтобы _-параметры не затемнялись тоже»

Это невозможно стандартными средствами, потому что затемнение и диагностика — это один и тот же тег unnecessary на уровне языкового сервера. Вы не можете сказать «считай это не ошибкой, но и не unnecessary». Единственный обходной путь — отключить editor.showUnused и использовать расширение вроде Error Lens или Todo Tree для кастомной визуализации.

Источники

1. TypeScript — noUnusedParameters — Официальная документация опции компилятора для контроля неиспользуемых параметров: https://www.typescriptlang.org/tsconfig#noUnusedParameters
2. TypeScript — noUnusedLocals — Документация опции для обнаружения неиспользуемых локальных переменных: https://www.typescriptlang.org/tsconfig#noUnusedLocals
3. VS Code — editor.showUnused — Настройка визуального отображения неиспользуемого кода в редакторе: https://code.visualstudio.com/docs/getstarted/settings#_editor-showunused

Заключение

Настройка обработки неиспользуемых аргументов в связке VS Code + TypeScript сводится к двум слоям: компилятор решает, что считать проблемой (noUnusedLocals, noUnusedParameters в tsconfig.json), а редактор определяет, как это показать (editor.showUnused). Префикс _ работает как встроенный механизм исключения — компилятор пропускает такие параметры, но языковой сервер по-прежнему помечает их как unnecessary, благодаря чему они остаются затемнёнными в редакторе. Две настройки в tsconfig.json, одна в settings.json — и ваш проект получает чистый, самодокументирующийся код без ложных срабатываний.