Отладка TypeScript кода: инструменты и техники для разработчика

Отладка TypeScript кода: превращаем баги в задачи

Вы когда-нибудь тратили час на поиск ошибки, которая оказалась простой опечаткой в названии переменной? Или ловили себя на мысли, что console.log — это единственный инструмент, которым вы пользуетесь? Добро пожаловать в клуб. Отладка — это не просто «ловля багов», а целое искусство понимания того, как работает ваш код на самом деле.

TypeScript добавляет в эту историю особый шарм. С одной стороны, статическая типизация отсекает целый класс ошибок ещё на этапе компиляции. С другой — когда код уже скомпилирован в JavaScript, отлаживать его «на лету» становится сложнее: вы пишете на TS, а видите в браузере скомпилированный JS. Как не потеряться в этом лабиринте?

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

Почему отладка TypeScript отличается от отладки JavaScript?

Главная фишка TypeScript — транспиляция. Вы пишете код с типами, дженериками и интерфейсами, а браузер или Node.js получают чистый JavaScript. Это значит, что при отладке вы смотрите на скомпилированный код, который может сильно отличаться от оригинала: названия переменных могут быть изменены, дженерики стёрты, а интерфейсы исчезли вовсе.

Решение — Source Maps. Это карты соответствия между исходным TS и скомпилированным JS. Без них отладка TypeScript превращается в гадание на кофейной гуще.

Настройка Source Maps: первый шаг к прозрачности

Чтобы браузер или отладчик понимали, какой строке TS соответствует строка JS, нужно включить генерацию source maps в tsconfig.json:

{
  "compilerOptions": {
    "sourceMap": true,
    "outDir": "./dist",
    "target": "ES2020",
    "module": "commonjs"
  },
  "include": ["src/**/*"]
}

Теперь при компиляции рядом с каждым JS-файлом появится файл .map. Браузер (Chrome, Firefox) автоматически подгрузит его, и вы сможете ставить точки остановки прямо в TypeScript-коде.

Важно: в production source maps лучше отключать или использовать скрытые endpoint'ы, чтобы не светить исходный код пользователям. Настройте это через переменные окружения:

// tsconfig.prod.json
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "sourceMap": false
  }
}

Инструменты отладки TypeScript: ваш арсенал

1. VS Code — встроенный отладчик

Visual Studio Code — это, пожалуй, лучшая среда для отладки TypeScript. Встроенный отладчик умеет читать source maps и ставить breakpoints прямо в .ts файлах. Вот минимальная конфигурация launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Отладка TS через ts-node",
      "runtimeArgs": ["-r", "ts-node/register"],
      "args": ["${workspaceFolder}/src/index.ts"],
      "sourceMaps": true,
      "cwd": "${workspaceFolder}",
      "protocol": "inspector"
    }
  ]
}

Теперь вы можете нажать F5 и сразу попасть в отладчик. Ставьте красные точки слева от номеров строк — они сработают, даже если вы отлаживаете TypeScript код с дженериками и декораторами.

Лайфхак: используйте debugger; прямо в коде — это эквивалентно установке breakpoint, но не требует мыши.

2. Chrome DevTools — отладка фронтенда

Для фронтенд-проектов на TypeScript (React, Angular, Vue) Chrome DevTools — must have. Откройте вкладку Sources, найдите ваш файл в папке webpack:// или src — если source maps настроены правильно, вы увидите оригинальный TypeScript.

Полезные фишки:

• Conditional breakpoints — щёлкните правой кнопкой по breakpoint и введите условие, например user.age > 30. Остановка произойдёт только когда условие истинно.
• Logpoints — вместо остановки можно вывести сообщение в консоль (Chrome 73+). Кликните правой кнопкой по строке → "Add logpoint". Идеально для быстрой отладки без остановки выполнения.
• Watch expressions — добавьте выражение вроде this.state.users.filter(u => u.active) и следите за его значением на каждом шаге.

3. ts-node и Node.js — отладка серверного кода

Для бэкенда часто используют ts-node, который выполняет TypeScript напрямую, без компиляции. Но при отладке могут возникнуть нюансы с source maps. Лучший способ — запускать через node --inspect-brk:

node --inspect-brk -r ts-node/register src/server.ts

Затем откройте в Chrome chrome://inspect и подключитесь к процессу. Всё будет работать как часы, включая breakpoints в TypeScript.

Техники отладки TypeScript: от простого к сложному

1. Работа с типами: не дайте компилятору вас обмануть

Иногда ошибка не в логике, а в том, что TypeScript выводит тип не так, как вы ожидаете. Используйте console.log с типами — это звучит странно, но работает:

function processData(data: unknown) {
  // Проверяем тип в runtime
  console.log(typeof data);
  console.log(data instanceof Array);
  console.log(Object.prototype.toString.call(data));
  
  // Если нужно увидеть структуру объекта
  console.log(JSON.stringify(data, null, 2));
}

Для сложных типов используйте satisfies (TypeScript 4.9+) — он проверяет тип, не меняя его вывода:

const config = {
  url: "https://api.example.com",
  timeout: 5000
} satisfies Record<string, string | number>;

// config.url — тип string, а не string | number
console.log(config.url.toUpperCase()); // Работает!

2. Продвинутые breakpoints: не просто пауза

Точки остановки — это мощно, но есть нюансы с асинхронностью. TypeScript в связке с async/await может вести себя неочевидно. Попробуйте такой трюк:

async function fetchUser(id: number): Promise<User> {
  const response = await fetch(`/api/users/${id}`);
  
  // Установите breakpoint на следующей строке
  const data: User = await response.json();
  
  // Добавьте в watch: "data" — увидите результат
  // Добавьте conditional breakpoint: "data.role === 'admin'"
  return data;
}

Также полезно использовать <