Puppeteer PDF: возможности, установка, ограничения и сценарии HTML-to-PDF

Puppeteer PDF — это не отдельная программа, редактор или облачный конвертер, а практическое название функции генерации PDF внутри библиотеки Puppeteer. Она управляет Chrome или Firefox из JavaScript/TypeScript и позволяет превратить уже отрисованную веб-страницу или заданный HTML в PDF через метод Page.pdf(). Поэтому продукт логичнее оценивать не как замену Acrobat или Sumatra PDF, а как программный компонент для серверной и локальной автоматизации: отчётов, счетов, билетов, архивных копий веб-страниц и других документов, которые формируются из HTML/CSS.

ПараметрАктуальное состояние
Официальное имяPuppeteer; «Puppeteer PDF» — функция Page.pdf(), а не отдельный продукт
Разработчик и поддержкаChrome Browser Automation team
Актуальная версия25.10.0 на 12 сентября 2026 года; релиз опубликован 3 сентября 2026 года
ТипJavaScript/TypeScript-библиотека автоматизации браузера с генерацией PDF
Основной выводPDF из HTML, URL или состояния веб-приложения через браузерный движок
БраузерыChrome и Firefox; для полного набора PDF-параметров возможности протоколов различаются
ЛицензияApache License 2.0, открытый исходный код
Цена и аккаунтБесплатно; подписка, активация и отдельный аккаунт Puppeteer не требуются
ИнтерфейсПрограммный API; собственной настольной панели для верстки PDF нет
Системная базаNode.js 22.12+; поддерживаемые ОС и архитектуры зависят от Chrome for Testing или Firefox

Скачать Puppeteer PDF

Бесплатно
В реестре российского ПО
Чистая установка

Новейшая версия для Виндовс, macOS и Линукс. Удобный редактор PDF под российские реалии.

⬇ Скачать PDF Commander бесплатно

⬇ Скачать Puppeteer PDF

Отдельного установщика с названием Puppeteer PDF не существует. Безопасный путь — добавить официальный пакет Puppeteer в проект через поддерживаемый менеджер пакетов. Документация версии 25.10.0 показывает команды npm i puppeteer, yarn add puppeteer, pnpm add puppeteer и bun add puppeteer. Пакет puppeteer ориентирован на конечное использование и при нормальной установке загружает совместимый Chrome for Testing, а также chrome-headless-shell; это важно учитывать при оценке объёма загрузки и политики CI.

На дату обзора актуальная ветка — Puppeteer 25.10.0. Официальный журнал релизов фиксирует выпуск 3 сентября 2026 года; для этой версии таблица совместимости указывает Chrome for Testing 152.0.7977.75 и Firefox 155.0. Устанавливать произвольный старый архив только ради «Puppeteer PDF» обычно нет смысла: проект намеренно связывает версии библиотеки и браузеров, чтобы уменьшить вероятность несовместимости протокола.

При установке важно видеть разницу между библиотекой и браузером. Документация оценивает загрузку Chrome for Testing примерно в 170 МБ для macOS, 282 МБ для Linux и 280 МБ для Windows; фактический размер и кэш могут меняться с релизами. По умолчанию браузерные файлы сохраняются в каталоге кэша Puppeteer в домашнем профиле. Если менеджер пакетов блокирует postinstall-скрипты, браузер может не скачаться; тогда официальный путь восстановления — разрешить установочный скрипт либо отдельно выполнить команду установки браузеров через Puppeteer.

Что такое Puppeteer PDF

Puppeteer — библиотека JavaScript, предоставляющая высокоуровневый API для управления Chrome и Firefox через Chrome DevTools Protocol и WebDriver BiDi. Проект поддерживает Chrome Browser Automation team. Формулировка «Puppeteer PDF» удобна для обозначения сценария, но технически речь идёт о методе Page.pdf() и связанных настройках PDFOptions внутри общего инструмента автоматизации браузера.

Метод Page.pdf() просит браузер сформировать PDF из текущего состояния страницы. Это принципиально отличается от библиотек, которые самостоятельно реализуют движок разметки, и от настольных PDF-редакторов. Puppeteer сначала получает реальную браузерную страницу: открывает URL, выполняет JavaScript, применяет CSS, загружает шрифты и другие ресурсы, а затем использует механизм печати. В результате он особенно уместен, когда исходник уже является веб-интерфейсом или HTML-шаблоном.

Статус проекта активный. В сентябре 2026 года ветка 25.x продолжает получать релизы, обновления совместимых браузеров и исправления. Поддержка Firefox является штатной с Puppeteer 23.0.0, однако документация отдельно предупреждает о различиях между возможностями CDP и WebDriver BiDi. Для PDF это важно: сам Page.pdf() доступен и через BiDi, но не каждый параметр PDFOptions одинаково поддерживается всеми протоколами.

Основные функции Puppeteer PDF

Генерация PDF из URL и HTML

Базовый сценарий состоит из запуска браузера, создания страницы, загрузки URL или передачи HTML через setContent и вызова Page.pdf(). Метод возвращает Uint8Array, поэтому результат необязательно сразу писать на диск: его можно сохранить в файл, отдать HTTP-ответом, передать в объектное хранилище или обработать дальше в коде. Если задан параметр path, Puppeteer сам записывает PDF по указанному пути; относительный путь считается от текущего рабочего каталога процесса.

Размер бумаги, ориентация, поля и масштаб

PDFOptions позволяет выбрать именованный формат бумаги или задать ширину и высоту. Если указан format, он имеет приоритет над width и height. По умолчанию используется Letter, поэтому для русскоязычных и европейских документов формат A4 лучше задавать явно, а не надеяться на системные настройки. Отдельно настраиваются альбомная ориентация, поля и масштаб рендеринга в диапазоне от 0,1 до 2.

Параметр preferCSSPageSize позволяет отдать приоритет размеру, объявленному в CSS через @page. Это полезно для шаблонов, где формат листа является частью дизайна и должен храниться рядом с правилами печати. Если preferCSSPageSize выключен, браузер масштабирует содержимое под размер, заданный в PDFOptions. Такой выбор стоит фиксировать в проекте, иначе одинаковый HTML может неожиданно менять переносы при смене настроек.

Печатные стили, фон и цвета

Page.pdf() по умолчанию использует CSS-медиатип print. Это означает, что правила @media print могут скрывать навигацию, перестраивать сетку, менять типографику и готовить веб-страницу к бумажному виду. Если нужен вид, максимально близкий к экранному, перед печатью можно переключить эмуляцию на media type screen.

Фоновые графические элементы управляются параметром printBackground, который по умолчанию выключен. Для макетов с заливками, цветными карточками и фоновыми изображениями его обычно включают осознанно. Документация также отмечает, что печатный режим может модифицировать цвета; если требуется более точное сохранение экранных цветов, это решается CSS-свойством -webkit-print-color-adjust. Важный вывод: визуальная идентичность документа определяется совместно HTML, CSS и параметрами печати, а не одной опцией Puppeteer.

Колонтитулы, номера страниц и диапазоны

При displayHeaderFooter можно добавить HTML-шаблоны верхнего и нижнего колонтитулов. В них предусмотрены специальные классы для даты, заголовка, URL, текущего номера и общего количества страниц. Это позволяет формировать деловые документы без ручного расчёта пагинации. Отдельный pageRanges ограничивает печать нужными страницами, например диапазонами и отдельными номерами.

Шрифты, ожидание и доступность

Параметр waitForFonts по умолчанию включён: Page.pdf() ждёт document.fonts.ready. Это снижает риск сформировать документ до загрузки веб-шрифтов. Однако ожидание шрифтов не означает автоматическое ожидание любых сетевых данных, анимаций или асинхронных виджетов; готовность страницы всё равно нужно определять на уровне навигации или приложения.

В актуальном PDFOptions параметр tagged, отвечающий за генерацию тегированного PDF, помечен экспериментальным и имеет значение true по умолчанию. Параметр outline для структуры документа также экспериментальный и по умолчанию выключен. Эти возможности нельзя трактовать как автоматическую гарантию соответствия PDF/UA или конкретному стандарту доступности: корректная семантика исходного HTML и итоговая валидация остаются отдельными задачами.

Интерфейс и удобство использования

У Puppeteer PDF нет традиционного интерфейса с панелью «Открыть», миниатюрами страниц и кнопкой «Экспорт». Рабочая зона — исходный код проекта, консоль и при необходимости окно управляемого браузера. По умолчанию Puppeteer запускается headless, то есть без видимого окна, но для отладки может работать в headful-режиме. Это делает инструмент удобным для разработчиков и одновременно неудобным для пользователя, ожидающего визуальный конструктор документа.

Логика API последовательна: Browser управляет экземпляром браузера, Page соответствует вкладке, навигационные методы подготавливают состояние, а Page.pdf() завершает сценарий печатью. Порог входа определяется не PDF как форматом, а знакомством с Node.js, async/await, HTML/CSS и браузерной моделью. Разработчик, который уже пишет сервер на JavaScript или автоматизирует Chrome, обычно получает прямую модель работы; бухгалтеру или редактору без программирования Puppeteer практически не даёт самостоятельного пользовательского интерфейса.

Отдельной локализации интерфейса нет, потому что самого GUI нет. Имена методов и параметров — часть программного API. Для командной работы это означает, что удобство определяется качеством собственного кода, шаблонов, документации проекта и автоматических проверок, а не языком меню.

Поддерживаемые форматы и совместимость

На входе Puppeteer PDF работает прежде всего с веб-контентом. Page.goto() открывает URL, а setContent принимает строку HTML. Внутри страницы браузер обрабатывает HTML, CSS, JavaScript, изображения, веб-шрифты и другие ресурсы в той мере, в какой их поддерживает выбранный браузер. На выходе Page.pdf() создаёт PDF; это не универсальный конвертер DOCX, XLSX, ODT, DJVU или сканированных TIFF в PDF.

Если исходный документ хранится в офисном формате, его сначала нужно преобразовать в HTML или использовать другой инструмент, который понимает исходный формат напрямую. Аналогично готовый PDF не является штатным «входным проектом» для редактирования. В headless shell документация отдельно отмечает ограничение навигации непосредственно к PDF-документу. Поэтому попытка построить на Puppeteer полноценный PDF-редактор приводит к лишнему слою и неверному выбору инструмента.

Версия 25.10.0 официально поддерживает Chrome и Firefox. Для Chrome Puppeteer по умолчанию использует CDP, а для Firefox — WebDriver BiDi. Таблица версии связывает Puppeteer 25.10.0 с Chrome for Testing 152.0.7977.75 и Firefox 155.0. Это не просто справочная деталь: проект сознательно тестирует совместимые сочетания, а произвольная замена браузера может дать протокольные различия.

В документации WebDriver BiDi для генерации PDF перечислен сокращённый набор поддерживаемых параметров: format, height, landscape, margin, pageRanges, printBackground, scale и width. Следовательно, Chrome/CDP остаётся безопаснее для сценариев, где критичны колонтитулы, preferCSSPageSize, tagged PDF, outline или другие опции за пределами этого списка. Кросс-браузерность Puppeteer не означает полной идентичности PDF-вывода.

Производительность и стабильность

Главная характеристика производительности следует из архитектуры: Puppeteer запускает полноценный браузерный движок. Это тяжелее, чем библиотека, которая только собирает структуру PDF, зато рендеринг современного HTML/CSS/JavaScript близок к тому, что реально делает Chrome. Официальная документация не задаёт универсальных значений времени или памяти для PDF, поэтому корректно оценивать ресурсность только на собственных шаблонах, размерах изображений, шрифтах и объёмах данных.

Стабильность тесно связана с браузерной версией. Puppeteer выпускается вместе с конкретными ревизиями браузеров, чтобы изменения CDP и WebDriver BiDi не ломали автоматизацию неожиданно. Поэтому обновление библиотеки следует рассматривать как обновление связки «API + браузер», особенно если PDF должен быть пиксельно стабильным для юридических форм, счетов или печатной продукции.

Отдельный класс проблем характерен для контейнеров и Linux. Chrome требует системных библиотек, записываемых временных каталогов и корректно настроенного sandbox. Документация настоятельно не рекомендует отключать sandbox через —no-sandbox для недоверенного контента. В read-only контейнерах нужно предусмотреть доступные для записи конфигурационный, кэш- и пользовательский каталоги; иначе Chrome может завершаться до подключения Puppeteer.

Лицензирование и версии

Puppeteer распространяется с открытым исходным кодом под Apache License 2.0. Платной редакции «Puppeteer PDF», подписки, пробного срока или ограничения числа сгенерированных файлов у официальной библиотеки нет. Цена использования определяется не лицензией Puppeteer, а собственной инфраструктурой: вычислительными ресурсами, хранением, трафиком, CI, контейнерами, поддержкой шаблонов и при необходимости сторонним сервисом удалённых браузеров.

Регистрация в отдельном аккаунте Puppeteer не требуется. Библиотека не является SaaS и не отправляет документы в собственное облако «для конвертации». Если скрипт открывает внешний URL, ресурсы загружаются браузером из сети; если разработчик подключает Puppeteer к удалённому браузеру, данные обрабатываются уже в выбранной инфраструктуре. Поэтому приватность зависит от архитектуры приложения, а не только от лицензии библиотеки.

Системные требования

Для Puppeteer 25.10.0 официальная страница требований указывает Node.js 22.12 или новее. При использовании TypeScript требуется TypeScript 5.0.1+, а при проверке типов node_modules — target ES2022 или более новый. Это конкретные требования актуальной версии, поэтому старые инструкции для Node 18 или ранних веток Puppeteer нельзя автоматически переносить на 25.x.

Windows

Chrome for Testing поддерживается на Windows x64. Для распаковки браузерных бинарников требуется tar.exe или PowerShell, если не используется дополнительная зависимость yauzl. При корпоративных политиках Chrome возможны проблемы запуска из-за запрета расширений или разрешений sandbox, поэтому серверная установка должна проверяться под теми же политиками, что и production.

macOS

Для Chrome for Testing официально указаны x64 и arm64. Для распаковки обычно нужен unzip, если не задействован альтернативный механизм. Документация установки оценивает загрузку браузера примерно в 170 МБ для macOS, но к дисковому бюджету следует добавить node_modules, кэш и временные файлы создаваемых страниц.

Linux

Для Chrome for Testing перечислены Debian/Ubuntu x64 и openSUSE/Fedora x64 с набором системных библиотек. Документация отдельно предупреждает, что официальные Chrome-бинарники для Linux arm64 недоступны в том же виде, что macOS ARM, поэтому стандартная загрузка Puppeteer на Linux arm64 требует отдельного решения с совместимым браузером. Для распаковки используется unzip; для Firefox на Linux нужны xz или bzip2.

Карта критических зависимостей

ЗависимостьЗачем нужнаЧто ломаетсяКак контролировать
Node.jsИсполняет Puppeteer и прикладной кодСкрипт не запускается или несовместим с APIФиксировать поддерживаемую версию, для 25.10.0 — 22.12+
Совместимый браузерРендерит HTML и печатает PDFОшибки протокола, отличия верстки, невозможность запускаИспользовать связку из таблицы Puppeteer или явно тестировать свой executablePath
Системные библиотеки LinuxНужны Chrome для запускаBrowser launch errorСверять зависимости с актуальной документацией Chrome
ШрифтыОпределяют метрики текстаЗамена гарнитуры, иные переносы и пагинацияУстанавливать нужные шрифты и ждать document.fonts.ready
Сеть и внешние ресурсыЗагружают данные, CSS, изображенияПустые блоки, таймауты, нестабильный результатЛокализовать критические ресурсы или явно контролировать готовность
Sandbox и writable-директорииБезопасность и служебные файлы ChromeChrome не стартует в контейнереНе отключать sandbox без необходимости, дать минимально нужные права

Преимущества и недостатки Puppeteer PDF

Плюсы и минусы

• Современный браузерный рендеринг. Подходит для страниц с JavaScript, SPA и актуальным CSS, потому что документ формируется после реальной отрисовки браузером.

• Гибкие параметры печати. Доступны размеры бумаги, ориентация, поля, масштаб, фон, диапазоны страниц, колонтитулы, CSS @page и ожидание шрифтов.

• Удобная интеграция с Node.js. PDF получается как массив байтов или поток и легко встраивается в HTTP-сервис, очередь заданий или генератор отчетов.

• Открытая лицензия. Apache 2.0 не вводит подписку, лимит документов или платную активацию.

• Контроль состояния страницы. Перед печатью можно выполнить действия, дождаться данных и сформировать документ из авторизованного или динамического представления, если это предусмотрено приложением.

• Официально поддерживаемый Chrome for Testing. Версия Puppeteer привязана к конкретному браузеру, что упрощает воспроизводимость в CI.

Минусы

• Нет визуального PDF-редактора. Все операции задаются кодом и стилями; ручная правка готового файла выходит за рамки Puppeteer.

• Тяжелее специализированных библиотек. Для генерации нужен браузерный процесс со всеми его зависимостями и требованиями к памяти.

• Кросс-браузерные различия. В WebDriver BiDi поддерживается не весь набор PDFOptions, поэтому одинаковый код не гарантирует идентичный вывод Chrome и Firefox.

• Зависимость от корректной печатной верстки. Длинные таблицы, разрывы страниц и колонтитулы не исправляются автоматически, если HTML/CSS спроектирован плохо.

• Операционные сложности Linux и контейнеров. Нужны системные библиотеки, права, writable-пути и корректный sandbox.

• Нет OCR и редактирования существующих PDF. Для сканов, исправления текста и структурных операций нужны другие инструменты.

Сравнение с аналогами

РешениеПодходСильная сторонаОсновное ограничениеКогда выбирать
Puppeteer PDFChrome/Firefox через Node.jsДинамические веб-приложения и полный браузерНужен браузерный процессHTML уже является частью приложения, нужен JS и автоматизация
PlaywrightАвтоматизация нескольких браузерных движковШирокий стек тестовой автоматизацииPDF-экспорт официально Chromium-onlyПроект уже построен на Playwright и PDF — одна из задач
WeasyPrintPython-движок HTML/CSS для печатиПагинация, печатные стандарты, Python APIНе является полноценным браузером и не исполняет веб-приложение как ChromeДокумент проектируется как печатный HTML, особенно в Python-стеке
PrinceСпециализированный коммерческий HTML/XML-to-PDF движокТипографика и издательская версткаКоммерческая лицензия для соответствующих сценариевНужны сложные печатные документы и специализированные функции верстки
wkhtmltopdfСтарый WebKit/Qt-конвертерПростой CLI и большой исторический парк интеграцийОфициальный репозиторий архивирован в 2023 годуПоддержка унаследованной системы, где миграция пока невозможна
Sumatra PDFЛёгкий просмотрщик документов для WindowsБыстрое чтение готовых PDFНе предназначен для серверного HTML-to-PDFНужно открыть и проверить уже созданный файл

Playwright ближе всего по архитектуре. Его page.pdf() также печатает страницу и предлагает похожие параметры, но официальная документация прямо помечает PDF как Chromium-only. Если команда уже использует Puppeteer и не нуждается в других возможностях Playwright, миграция только ради PDF обычно не даёт самостоятельного выигрыша.

Sumatra PDF находится в другой категории: это просмотрщик, а не генератор. Его корректнее считать дополнением к Puppeteer PDF. Скрипт создаёт документ, а пользователь открывает его в лёгком просмотрщике. Если требуется полноценная ручная обработка, ближе будет Adobe Acrobat Pro; если нужен бесплатный настольный набор операций с PDF в Windows — полезно сравнить и PDF24 Creator.

Инструкция по установке

Установка в новый Node.js-проект

1. Проверьте Node.js: для Puppeteer 25.10.0 официально требуется версия 22.12 или новее.

2. Создайте или откройте проект Node.js и добавьте зависимость командой npm i puppeteer. Вместо npm допустимы официально указанные Yarn, pnpm или Bun.

3. Дождитесь postinstall. При обычной установке Puppeteer скачивает совместимый Chrome for Testing и chrome-headless-shell в кэш пользователя.

4. Если установка завершилась, но запуск сообщает, что нужный Chrome не найден, проверьте, не блокирует ли менеджер пакетов dependency scripts. Официальный способ — разрешить скрипт или выполнить npx puppeteer browsers install.

5. Создайте минимальный скрипт: импортируйте Puppeteer, запустите браузер, откройте новую Page, задайте HTML или URL, вызовите Page.pdf() с путём к файлу и закройте Browser.

6. Откройте созданный PDF в независимом просмотрщике и проверьте формат страницы, число листов, шрифты, фон и ссылки.

Установка puppeteer-core

Используйте puppeteer-core, если браузер управляется отдельно. Пакет не скачивает Chrome и не применяет часть конфигурации обычного puppeteer. После установки нужно явно указать executablePath или channel либо подключиться к уже работающему браузеру. Такой вариант уменьшает скрытые загрузки в CI, но ответственность за совместимую версию браузера переходит к инфраструктуре проекта.

Первый запуск в контейнере

Для Docker официальный проект публикует образ с Chrome for Testing, зависимостями и Puppeteer. При использовании этого пути заранее проверьте модель sandbox, init-процесс и права записи. Не решайте ошибку «No usable sandbox» механическим добавлением —no-sandbox для документов из недоверенных источников: официальная документация прямо не рекомендует такой режим.

Безопасное удаление

Если пакет добавлен через npm, стандартная команда npm uninstall puppeteer удаляет зависимость из node_modules и обновляет package.json и lock-файл. Браузерный кэш Puppeteer хранится отдельно, поэтому его состояние следует оценивать отдельно: в одной системе кэш могут использовать несколько проектов. Метод trimCache удаляет неактуальные браузерные бинарники, но документация предупреждает, что он не проверяет потребности других установленных версий Puppeteer. Поэтому удалять общий кэш целиком безопасно только после проверки, что он больше не нужен другим проектам.

Паспорт обратимости операций

ОперацияОбратимостьЧто сохранятьРиск
Генерация PDF из URLИсходная веб-страница не изменяетсяURL, версия шаблона, параметры печатиСтраница позже изменится, и повторный PDF будет другим
Генерация из setContentПовторяема при фиксированном HTML и ресурсахHTML, CSS, шрифты, данныеВнешние ресурсы могут измениться или исчезнуть
Запись через pathФайл можно перегенерироватьИсходник и конфигурациюСуществующий файл по тому же пути может быть заменён логикой приложения
Изменение PDFOptionsПолностью обратимо в кодеВерсию конфигурацииМеняются пагинация и внешний вид
Обновление Puppeteer/ChromeТехнически можно вернуться к зафиксированной версииpackage-lock, образ контейнера, тестовые эталоныРендеринг и протокольное поведение могут отличаться

Практические кейсы

Счёт или акт из HTML-шаблона

Цель: сформировать A4-документ из серверных данных без отдельного офисного редактора.

1. Подготовка. Создайте HTML-шаблон с семантическими блоками, печатным CSS и локально доступными шрифтами. Для A4 либо задайте @page, либо зафиксируйте format в PDFOptions.

2. Шаги. Сформируйте HTML на сервере, передайте его в Page.setContent(), дождитесь загрузки, затем вызовите Page.pdf() с format A4, нужными margins и printBackground, если фон обязателен.

3. Проверка. Сверьте номер документа, итоговые суммы, количество страниц, перенос строк в реквизитах и наличие всех шрифтов.

4. Ограничение. Puppeteer не проверяет бизнес-логику суммы и не гарантирует, что длинная таблица будет эстетично разбита без специально написанного CSS.

PDF из динамического дашборда

Цель: получить снимок состояния SPA после загрузки графиков и данных.

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

2. Шаги. Откройте URL через Page.goto(), при необходимости установите параметры, выполните действия в интерфейсе и дождитесь выбранного признака. После этого переключите media type, если нужен экранный вид, и сформируйте PDF.

3. Проверка. Убедитесь, что на страницах присутствуют значения, подписи графиков и легенды, а не только контейнеры до рендеринга.

4. Ограничение. Анимации, бесконечная подгрузка и постоянно открытые сетевые соединения требуют прикладного критерия готовности.

Архивная копия публичной веб-страницы

Цель: сохранить читаемое представление URL в PDF.

1. Подготовка. Проверьте, что автоматизированный доступ к странице разрешён и что нужный контент не требует действий, нарушающих правила сайта.

2. Шаги. Откройте HTTPS-URL, дождитесь основного содержимого, сформируйте PDF с print CSS и при необходимости включите фон.

3. Проверка. Сохраните дату формирования рядом с файлом и визуально проверьте, что печатный CSS не скрывает важный текст.

4. Ограничение. PDF фиксирует отрисованное состояние, но не является полноценным архивом всех исходных ресурсов, JavaScript и интерактивности страницы.

Пакетная генерация документов

Цель: создавать серию персонализированных PDF в одном процессе.

1. Подготовка. Зафиксируйте максимальный размер задания, таймаут и правила именования; подготовьте очередь данных.

2. Шаги. Запустите Browser, последовательно или контролируемо параллельно создавайте Page/BrowserContext, загружайте шаблон, формируйте PDF и освобождайте страницу после каждого документа.

3. Проверка. Для каждого задания фиксируйте успешную генерацию, размер ненулевого результата и прикладные идентификаторы документа.

4. Ограничение. Неограниченный параллелизм умножает процессы/страницы Chrome и может исчерпать память; число одновременно обрабатываемых документов нужно определять нагрузочным тестом своей инфраструктуры.

Контроль перед сохранением и передачей

• Формат и ориентация бумаги заданы явно, если документ предназначен для печати.

• Поля не обрезают таблицы, QR-коды, подписи и обязательные реквизиты.

• Веб-шрифты загрузились, нет незапланированной подмены гарнитуры.

• printBackground включён только там, где фон действительно нужен.

• В PDF нет скрытых тестовых данных, служебных URL или лишних колонтитулов.

• Число страниц и критические текстовые значения проверены приложением или тестом.

• Файл открывается в независимом просмотрщике, например Adobe Acrobat Reader.

• Если требуется PDF/A, PDF/UA, электронная подпись или иная нормативная характеристика, она проверена отдельным специализированным валидатором, а не выводится из факта успешного Page.pdf().

Навигатор по сбоям

СимптомЧто проверитьВероятная причинаБезопасное действие
Could not find ChromeКэш и postinstallМенеджер пакетов заблокировал установочный скриптРазрешить официальный postinstall или выполнить установку браузеров Puppeteer
Chrome не запускается на LinuxСистемные библиотеки и архитектуруНет зависимостей или используется неподдерживаемая связкаСверить список пакетов и поддерживаемую архитектуру
No usable sandboxПолитику user namespaces/AppArmor и праваSandbox не может инициализироватьсяНастроить sandbox; не отключать его для недоверенного контента как первый шаг
PDF создан слишком раноПризнак готовности данныхPage.pdf() вызван до окончания асинхронного рендерингаДобавить явное ожидание состояния приложения
Другие переносы строкШрифты и версию браузераFallback-шрифт или обновление рендерераЗафиксировать шрифты, окружение и сравнить эталон
Нет фонаprintBackground и печатный CSSФоны отключены по умолчаниюВключить параметр и проверить @media print
Firefox игнорирует часть настроекСписок WebDriver BiDi PDF-возможностейПараметр не поддерживается протоколомУпростить параметры или использовать Chrome/CDP для данного документа

Часто задаваемые вопросы

Можно ли установить Puppeteer PDF как обычную программу?

Нет. Отдельного приложения Puppeteer PDF нет. Устанавливается npm-пакет Puppeteer в проект, а генерация выполняется программным методом Page.pdf(). Если нужен графический интерфейс для ручного создания PDF, следует выбирать настольный редактор или виртуальный PDF-принтер, например решения класса doPDF.

Нужен ли установленный Google Chrome?

Не обязательно. Обычный пакет puppeteer сам загружает совместимый Chrome for Testing. Если используется puppeteer-core, браузером управляет разработчик и обычно задаёт executablePath, channel или удалённое подключение.

Работает ли генерация PDF в Firefox?

Да, Page.pdf() входит в поддерживаемые возможности WebDriver BiDi, но документация указывает сокращённый набор параметров по сравнению с общим PDFOptions. Если документ использует опции, отсутствующие в списке BiDi, нужно отдельно проверить поведение или выбрать Chrome/CDP.

Можно ли получить PDF без записи временного файла?

Да. Page.pdf() возвращает Uint8Array, а createPDFStream() возвращает поток байтов. Это подходит для ответа HTTP, загрузки в хранилище или дальнейшей обработки без обязательной записи промежуточного PDF в рабочий каталог.

Поддерживает ли Puppeteer PDF русский текст?

Браузер способен рендерить Unicode-текст, но внешний вид зависит от доступных шрифтов. На сервере или в контейнере нужно обеспечить установку/загрузку гарнитуры с нужными символами и дождаться готовности шрифтов. Иначе система может выбрать fallback с другими метриками.

Есть ли OCR для сканов?

Нет. Page.pdf() печатает веб-страницу и не распознаёт текст на изображениях или в сканированных PDF. Для OCR нужен отдельный распознаватель, после чего результат можно представить в HTML и уже затем печатать Puppeteer при необходимости.

Почему PDF отличается от страницы на экране?

По умолчанию Page.pdf() использует CSS media type print, а браузер применяет печатные правила и может корректировать цвета. Для экранного режима можно заранее эмулировать media type screen. Кроме того, результат зависит от размера бумаги, полей, масштаба, printBackground и CSS @page.

Стоит ли включать —no-sandbox в Docker, если Chrome не стартует?

Не как универсальное решение. Официальная документация Puppeteer прямо предупреждает, что запуск без sandbox настоятельно не рекомендуется. Сначала следует исправить контейнерные права, user namespaces, AppArmor или использовать официальный образ/поддерживаемую конфигурацию.

Вывод

Puppeteer PDF подходит разработчикам, которым нужно программно печатать современные веб-страницы и HTML-шаблоны в PDF из Node.js. Его сильная сторона — использование реального браузера: JavaScript, CSS, веб-шрифты и состояние SPA можно подготовить перед печатью, а PDFOptions даёт достаточно контроля для отчётов, счетов, билетов и архивных представлений.

Продукт не подходит тем, кому нужен визуальный PDF-редактор, OCR, ручная перестановка страниц или простой настольный конвертер без кода. Он также не является лучшим выбором, если проект требует специализированной типографики и стандартов архивного PDF без браузерной зависимости: здесь разумно рассмотреть WeasyPrint или Prince. Для просмотра уже созданного файла логичнее использовать Sumatra PDF или другой reader, а не запускать автоматизацию.


Ваш адрес email не будет опубликован. Обязательные поля помечены *