Node.js и TypeScript: как разбирать и исправлять ошибки

Короткий ответ: сначала не угадывайте, а определите, где именно ошибка. В проектах Node.js и TypeScript проблемы обычно делятся на четыре группы: TypeScript не компилирует код, Node.js не запускает скомпилированный файл, конфликтуют ESM и CommonJS, либо не установлены типы для Node.js и библиотек

Самый полезный порядок диагностики такой:

npx tsc --noEmit
node dist/index.js
cat package.json
cat tsconfig.json

Если tsc --noEmit падает, чините типы и tsconfig. Если TypeScript проходит, но node dist/index.js падает, проблема уже в runtime, путях, формате модулей или сборке

Содержание

Ошибка Cannot find module
Ошибка про require и import
Ошибка Cannot find name process
Ошибка из-за strict
Минимальный рабочий шаблон
Частые ошибки
Самопроверка
Что почитать дальше по TypeScript

Ошибка Cannot find module

Частый пример:

Error: Cannot find module './service'

Проверьте три вещи. Первая — файл действительно существует. Вторая — после компиляции он попадает в dist. Третья — путь в импорте совпадает с реальной структурой

Пример структуры:

src/
  index.ts
  service.ts
dist/
  index.js
  service.js

Импорт:

import { getUser } from "./service";

Если вы запускаете src/index.ts напрямую через node, Node.js не обязан понимать TypeScript-файлы так же, как ваш сборщик. Для обычного проекта надежнее компилировать:

npx tsc
node dist/index.js

Ошибка про require и import

Если видите:

ReferenceError: require is not defined in ES module scope

или:

SyntaxError: Cannot use import statement outside a module

значит, смешались ESM и CommonJS. Выберите один режим и настройте его последовательно

Вариант CommonJS:

{
  "compilerOptions": {
    "module": "CommonJS",
    "target": "ES2022",
    "outDir": "dist",
    "rootDir": "src"
  }
}

Вариант ESM:

{
  "type": "module",
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

{
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "target": "ES2022",
    "outDir": "dist",
    "rootDir": "src"
  }
}

Смысл простой: package.json и tsconfig.json должны говорить об одном и том же формате модулей

Ошибка Cannot find name process

Если TypeScript ругается на process, Buffer, __dirname или NodeJS.Timeout, почти всегда не хватает типов Node.js:

npm install -D @types/node

И проверьте tsconfig.json:

{
  "compilerOptions": {
    "types": ["node"]
  }
}

Если types не указан, TypeScript обычно сам подхватит установленные типы. Но если поле types уже есть, оно ограничивает список подключаемых типов, и node нужно добавить явно

Ошибка из-за strict

Например:

Parameter 'req' implicitly has an 'any' type

Это не ошибка Node.js, а настройка TypeScript. Исправляйте типами:

import type { IncomingMessage, ServerResponse } from "node:http";

function handler(req: IncomingMessage, res: ServerResponse) {
  res.end("ok");
}

Не выключайте strict только потому, что появилась первая ошибка. Лучше типизировать границу: параметры функции, результат API, конфиг, переменные окружения

Минимальный рабочий шаблон

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js",
    "check": "tsc --noEmit"
  },
  "devDependencies": {
    "@types/node": "latest",
    "typescript": "latest"
  }
}

src/index.ts:

import { createServer } from "node:http";

createServer((req, res) => {
  res.end("Hello TypeScript");
}).listen(3000);

Проверка:

npm run check
npm run build
npm start

Частые ошибки

Первая ошибка — чинить текст ошибки без чтения полного стека. Смотрите первую строку и файл, где ошибка началась

Вторая ошибка — запускать не тот файл: изменили src/index.ts, а запускаете старый dist/index.js

Третья ошибка — смешать module: CommonJS, "type": "module" и разные стили импортов

Четвертая ошибка — забыть @types/node

Пятая ошибка — поставить skipLibCheck и any везде, вместо того чтобы исправить границу типов

Самопроверка

Сделайте отдельную команду npm run check и запускайте ее перед стартом. Если check проходит, но приложение падает, ищите runtime-проблему. Если check падает, сначала чините TypeScript