Puppeteer и TypeScript: как подружить запуск и типы

Короткий ответ: чтобы Puppeteer и TypeScript нормально работали вместе, не начинайте с хаотичных правок импортов. Сначала поставьте актуальные зависимости, выберите понятный режим модулей, запустите минимальный скрипт через tsx или предварительную компиляцию tsc, а потом уже разбирайте конкретную ошибку

Рабочий минимальный набор:

npm init -y
npm install puppeteer
npm install --save-dev typescript tsx @types/node

Puppeteer уже поставляется с типами, отдельный @types/puppeteer обычно не нужен

Содержание

Минимальный tsconfig
Минимальный пример
Если не работает import puppeteer
Если Chrome не скачался или не запускается
Если TypeScript ругается на Node-типы
Частые ошибки
Самопроверка
Что почитать дальше по TypeScript

Минимальный tsconfig

Создайте tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

Для свежих версий Puppeteer важны Node.js и TypeScript современного уровня. Если проект старый, проблемы часто появляются не из-за Puppeteer, а из-за старого Node, старого TypeScript или смешения CommonJS и ESM

Минимальный пример

Создайте src/screenshot.ts:

import puppeteer from "puppeteer";

const browser = await puppeteer.launch();
const page = await browser.newPage();

await page.goto("https://example.com", {
  waitUntil: "networkidle2",
});

await page.screenshot({
  path: "example.png",
  fullPage: true,
});

await browser.close();

Запустите:

npx tsx src/screenshot.ts

Если рядом появился example.png, базовая связка Puppeteer + TypeScript работает

Если не работает import puppeteer

Частая ошибка:

Cannot use import statement outside a module

Она означает, что Node пытается выполнить код как CommonJS, а вы пишете ESM-импорт. Есть два нормальных пути

Первый путь — ESM. Добавьте в package.json:

{
  "type": "module"
}

И используйте module: "NodeNext" в tsconfig.json

Второй путь — CommonJS. Тогда можно писать:

import puppeteer from "puppeteer";

но компилировать в CommonJS и запускать готовый .js. Для новых проектов проще держаться ESM-схемы

Если Chrome не скачался или не запускается

Puppeteer по умолчанию скачивает совместимую версию браузера. Если установка была прервана, за прокси или с отключенным скачиванием, браузера может не быть

Попробуйте:

npx puppeteer browsers install chrome

Если используете свой Chrome, передайте путь:

const browser = await puppeteer.launch({
  executablePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
});

Путь зависит от системы. На сервере Linux часто дополнительно нужны системные библиотеки Chromium/Chrome

Если TypeScript ругается на Node-типы

Ошибки вроде Cannot find name process или проблемы с Buffer обычно лечатся установкой Node-типов:

npm install --save-dev @types/node

Если в tsconfig.json явно задано поле types, добавьте туда node:

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

Если поля types нет, TypeScript обычно сам видит @types/node

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

Не ставьте @types/puppeteer без необходимости. Для современных версий это чаще создает конфликт, чем помогает

Не смешивайте module: "CommonJS" и ESM-запуск без понимания. Большая часть странных ошибок начинается именно там

Не запускайте .ts напрямую через node src/file.ts. Node не компилирует TypeScript сам. Используйте tsx, ts-node или сначала tsc, потом node dist/file.js

Если скрипт зависает, убедитесь, что всегда вызываете await browser.close() в конце или в finally

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

Сделайте три проверки:

node -v
npx tsc --noEmit
npx tsx src/screenshot.ts

Если проверка типов проходит, скрипт создает скриншот, а браузер закрывается без зависшего процесса, проблема дружбы Puppeteer и TypeScript решена на базовом уровне

Что почитать дальше по TypeScript

Если нужен общий маршрут по теме, откройте рубрику TypeScript. Для соседних задач пригодятся эти разборы: