Обзор wkhtmltopdf: создание PDF из HTML, установка, безопасность и актуальные альтернативы

wkhtmltopdf — консольный HTML-to-PDF-конвертер на базе Qt WebKit. Он умеет собирать отчёты из нескольких веб-страниц, добавлять колонтитулы, оглавление, PDF-закладки, cookies и сетевые параметры. В 2026 году его нужно оценивать с оговоркой: проект архивирован, а встроенный WebKit устарел. Поэтому wkhtmltopdf уместен прежде всего для сопровождения существующих систем и старых проверенных шаблонов, а не как базовый рендерер нового веб-сервиса.

Скачать wkhtmltopdf

Безопасный исходный путь — официальный сайт wkhtmltopdf и связанные с ним GitHub-релизы организации wkhtmltopdf. Сайт всё ещё называет стабильной серию 0.12.6. Для Linux позднее выходила упаковочная линия 0.12.6.1; последним официальным packaging-релизом остаётся 0.12.6.1-3. Это не ветка 0.12.7 и не новый движок, а поздняя упаковка старого ядра и патченного Qt.

Не следует смешивать wkhtmltopdf с родственными компонентами: wkhtmltoimage выводит веб-содержимое в изображения, а wkhtmltox охватывает библиотеки и упаковочные части. Здесь рассматривается именно утилита генерации PDF.

Windows

Официальная страница сохраняет установщики и 7z-архивы 0.12.6 для 32- и 64-разрядной Windows. Указание «Vista или новее» относится к исторической матрице 2020 года и не является обещанием поддержки Windows 10/11 в 2026 году.

macOS

Доступен 64-разрядный пакет 0.12.6; отдельная сборка r2 выпускалась для совместимости со старыми macOS. Нативная современная поддержка Apple Silicon проектом не заявлена. Если новая macOS блокирует старый пакет, не стоит отключать защитные механизмы ради него — лучше использовать изолированную наследуемую среду или другой рендерер.

Linux

Для Linux выпускались пакеты Debian, Ubuntu, AlmaLinux, CentOS, Amazon Linux, openSUSE и Arch Linux. Финальный packaging-релиз 0.12.6.1-3 содержит, среди прочего, Debian 12 bookworm и AlmaLinux 8/9 для нескольких архитектур. Пакет нужно подбирать по дистрибутиву и архитектуре: проект прямо связывает переносимость с glibc, OpenSSL, libjpeg, fontconfig, freetype и другими библиотеками.

Сторонние зеркала не дают преимуществ перед официальным архивом. Для нового проекта с современным HTML/CSS/JavaScript сначала целесообразно оценить актуальный рендерер, а wkhtmltopdf брать только при подтверждённой зависимости от его поведения.

Что такое wkhtmltopdf

wkhtmltopdf — свободная утилита командной строки, преобразующая одну или несколько HTML-страниц в PDF через патченную версию Qt WebKit. Изначально проект создал Jakob Truelsen, позднее его поддерживал Ashish Kulkarni. Программа работает headless: обычный экран и оконная оболочка для рендеринга не требуются. Это делает её удобной для cron-задач, веб-серверов, систем отчётности и приложений, которые вызывают внешний процесс из PHP, Python, Java, .NET или другого окружения.

По состоянию на 11 сентября 2026 года продукт снят с активного сопровождения. Репозиторий wkhtmltopdf переведён в read-only 2 января 2023 года, репозиторий packaging — 28 августа 2023 года, а GitHub-организация wkhtmltopdf помечена как архивная и «больше не поддерживается» с 10 июля 2024 года. Официальный сайт остаётся доступен, документация и загрузки работают, но это архив действующего когда-то проекта, а не признак текущей разработки.

Это критично для позиционирования. wkhtmltopdf хорошо подходит, когда организация должна продолжать формировать PDF по старым шаблонам и результат уже утверждён регламентом. Для новой системы, где страницы используют современный Flexbox, Grid, CSS-переменные, новые JavaScript API или сложную клиентскую гидратацию, его движок следует считать техническим долгом. Встроенный Qt 4 не поддерживается с 2015 года, а используемый WebKit не обновлялся до современного уровня браузерной безопасности.

Хронология развития и поддержки

2012–2015. Технологическая база начала отставать от браузеров. В собственной статусной заметке проект указывает, что WebKit в Qt 4 не обновлялся с 2012 года, Qt 4 прекратил поддержку в 2015-м, а QtWebKit в дальнейшем был исключён из основной линии Qt. Для wkhtmltopdf это означало зависимость от большого набора собственных патчей.

11 июня 2020 года. Вышла версия 0.12.6. Среди изменений — исправления оглавления и canvas, поддержка дополнительных архитектур и важное изменение безопасности: доступ HTML к произвольным локальным файлам стал заблокирован по умолчанию. На сайте одновременно был опубликован подробный статус проекта и предупреждение не обрабатывать недоверенный HTML.

2020–2022. В changelog появилась запись 0.12.7 как «unreleased», но финального стабильного релиза не последовало. Пакеты 0.12.6.1 продолжили обновлять совместимость с конкретными Linux-дистрибутивами, не меняя фундаментальную проблему старого рендерера.

2023–2024. Основной репозиторий и packaging стали архивными, затем была архивирована вся GitHub-организация. Поэтому любое внедрение после этой точки должно исходить из отсутствия будущих исправлений ядра, а не из ожидания «следующего патча».

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

Преобразование и сборка документа

Источник задаётся как URL или локальный HTML-файл, результатом служит PDF. За один запуск можно собрать несколько объектов: page добавляет обычную страницу, cover — обложку без стандартных колонтитулов и включения в оглавление, toc — автоматически созданное содержание. Порядок объектов задаётся командной строкой, поэтому один вызов может сформировать титульный лист, оглавление и главы.

Минимальная команда: wkhtmltopdf input.html output.pdf. Для удалённой страницы вместо input.html передаётся HTTPS-адрес. Такой CLI удобно вызывать из очереди отчётов, cron-задачи или серверного приложения.

Параметры страницы и качества

Можно задавать формат бумаги, точные ширину и высоту, книжную или альбомную ориентацию, поля, zoom, DPI, качество JPEG и предельное разрешение встраиваемых изображений. По умолчанию используются A4 и портретная ориентация. Есть оттенки серого, управление фоном и PDF-компрессией. Механизм smart shrinking пытается уместить широкое содержимое; для строгих бланков его поведение нужно фиксировать вместе с CSS.

Колонтитулы и нумерация

Верхние и нижние колонтитулы задаются текстом или отдельным HTML. Подстановки включают текущую и последнюю страницу, дату, время, URL, заголовок документа и раздела. Поэтому нумерация «Страница 3 из 18» формируется самим рендерером. HTML-колонтитулы гибче, но их собственные стили и ресурсы тоже должны загрузиться корректно.

Оглавление и PDF-закладки

С patched Qt программа строит PDF outline на основе HTML-заголовков. Объект toc формирует XML-структуру и преобразует её в HTML через XSLT. Можно выгрузить outline, получить стандартный XSLT и подключить собственный стиль оглавления — полезно для длинных регламентированных отчётов.

JavaScript и момент печати

JavaScript включён по умолчанию; стандартная задержка перед печатью составляет 200 мс. Доступны javascript-delay, run-script и window-status, позволяющий дождаться сигнала от страницы после асинхронной загрузки. Но это старый WebKit, а не современный Chrome: новые API, модули и сложный фронтенд могут не работать.

Сеть и аутентификация

Поддерживаются cookies, cookie jar, дополнительные HTTP-заголовки, HTTP Authentication, POST-поля и файлы, прокси и клиентские TLS-сертификаты. Это позволяет печатать внутренние URL без интерактивного браузера. Секреты лучше не хранить в shell history и скриптах с широкими правами.

Локальные ресурсы и CSS

С 0.12.6 локальный HTML не может произвольно читать другие локальные файлы: доступ блокируется по умолчанию. Для доверенного шаблона безопаснее разрешить конкретный каталог через allow, чем включать всю файловую систему. Также доступны user stylesheet, print/screen media type, viewport, encoding, zoom, обработка ошибок загрузки и управление ссылками. HTML form fields можно превратить в PDF-поля, но эта функция по умолчанию выключена.

Ошибки загрузки, ссылки и формы

Поведение при недоступной основной странице и при сбое отдельного медиафайла настраивается раздельно. Для load-error-handling документация перечисляет abort, ignore и skip, причём по умолчанию выбран abort. Для load-media-error-handling доступны те же режимы, но стандартное значение — ignore. Это различие важно в автоматизации: PDF может сформироваться, хотя часть картинок или других ресурсов не загрузилась. Поэтому одного факта появления выходного файла недостаточно — журнал и содержимое критичных ресурсов нужно контролировать отдельно.

Внутренние и внешние ссылки по умолчанию преобразуются в активные PDF-ссылки; их можно отключить независимыми опциями. Формы устроены наоборот: превращение HTML form fields в интерактивные поля PDF по умолчанию выключено и требует явного включения. Для архивного или юридически значимого документа это полезное разделение: обычные ссылки сохраняются без дополнительной настройки, а интерактивность формы не появляется случайно.

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

Основной интерфейс wkhtmltopdf — терминал. Визуального редактора, панели страниц и предпросмотра нет: HTML/CSS правится во внешнем редакторе, параметры передаются аргументами, а результат проверяется в PDF-просмотрщике. Для разработчика базовое преобразование просто, но сложность быстро растёт при несовместимом CSS, шрифтах, авторизации и локальных ресурсах.

Параметры делятся на глобальные, страничные, колонтитулы, outline и TOC. Диагностика текстовая: журнал имеет уровни none, error, warn и info, для JavaScript есть debug-javascript. Это удобно в автоматизации, но не подходит пользователю, ожидающему интерактивный экспорт. Готовый PDF можно проверить в Foxit Reader или другом просмотрщике.

Штатная справка англоязычная; отдельного русского GUI нет. Русский текст выводится при корректной входной кодировке и наличии подходящих шрифтов в системе.

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

DOCX, ODT, XLSX, изображения и готовый PDF не являются прямыми входными форматами. Офисный документ нужно сначала экспортировать в HTML/PDF; если веб-рендеринг вообще не нужен, практичнее использовать LibreOffice. Готовый PDF открывается в обычных просмотрщиках; для редактирования нужен отдельный инструмент, например Adobe Acrobat Pro. OCR в wkhtmltopdf нет.

Совпадение с современным браузером не гарантируется. Простые таблицы, float, фиксированные размеры и старые WebKit-совместимые стили обычно легче стабилизировать, чем макеты на новых CSS-функциях. Конкретный шаблон следует считать совместимым только после проверки в целевом бинарнике и окружении.

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

Современного официального бенчмарка нет. Каждый запуск загружает Qt/WebKit, парсит HTML, получает ресурсы, выполняет JavaScript, рассчитывает layout и пишет PDF. В простых документах заметна стоимость старта процесса и сети; в сложных — изображений, шрифтов и скриптов.

Для серии документов есть read-args-from-stdin: документация рекомендует его, если множество отдельных запусков слишком медленно. Это уменьшает накладные расходы старта, но не отменяет ограничение параллелизма по памяти и CPU.

Архивный tracker содержит сообщения о сбоях на длинных документах, масштабировании, print media, шрифтах и локальных ресурсах. Новых исправлений ядра уже нет, поэтому воспроизводимую проблему приходится решать изменением шаблона, фиксацией старой среды или миграцией. Для стабильной генерации полезно локализовать шрифты и статику, не зависеть от случайных CDN и закреплять версию окружения.

Официальная документация не устанавливает максимальное число страниц, размер HTML или гарантированный предел памяти, поэтому такие ограничения нельзя переносить из чужих тестов как спецификацию. Ресурсоёмкость растёт вместе с DOM, количеством изображений, шрифтов и сложностью layout. По умолчанию wkhtmltopdf использует 96 dpi, ограничивает встраиваемые изображения 600 dpi и задаёт качество JPEG 94; эти параметры влияют на размер результата и объём обработки, но не превращают старый WebKit в оптимизированный современный браузер.

Стабильность также зависит от времени получения внешних ресурсов. Сетевой CSS, веб-шрифт, картинка или API могут замедлить рендер либо дать неполный документ при ошибке загрузки. Фиксированная javascript-delay добавляет ожидание даже там, где страница уже готова, а слишком короткая задержка печатает незавершённый DOM. Для страниц, которые можно контролировать, сигнал window-status обычно лучше отражает фактическую готовность. Если же скрипт использует неподдерживаемый Web API, увеличение задержки не устраняет несовместимость.

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

wkhtmltopdf — свободное ПО по GNU LGPL 3.0. Платной редакции, подписки, аккаунта, водяных знаков, лимита страниц или пробного периода нет. При коммерческом распространении или встраивании важно соблюдать условия LGPL, особенно для модифицированных и связанных библиотек.

Последнее стабильное ядро — 0.12.6. Запись 0.12.7 в changelog помечена как unreleased. Номера 0.12.6.1-2 и 0.12.6.1-3 относятся к поздней упаковке, а не к переходу на новый браузерный движок.

Linux-пакет дистрибутива и официальный wkhtmltopdf могут отличаться: сам проект отмечает, что некоторые дистрибутивы собирали программу без его патчей Qt. Поэтому два бинарника с одинаковой командой нельзя автоматически считать функционально идентичными.

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

После архивирования проекта нет актуальной поддерживаемой матрицы. Официальное «Supported on» отражает среды, для которых когда-то собрали пакеты, а не гарантию совместимости с обновлениями ОС 2026 года. Практический критерий — подходящий официальный бинарник, его зависимости и успешная проверка в вашей среде.

Windows

Исторически установщик 0.12.6 заявлен для Vista и новее, 32/64 бит; 7z-архив — для XP/Server 2003 и новее. Эти минимумы не являются рекомендацией старых ОС. На Windows 10/11 нужно отдельно проверять запуск, TLS-ресурсы и шрифты.

macOS

Официальный пакет — 64-разрядный, с историческим минимумом macOS 10.7. Современная нативная поддержка Apple Silicon не заявлена, поэтому для нового Mac разумнее выбирать актуальный рендерер.

Linux

Совместимость зависит от glibc, OpenSSL, libpng/libjpeg, fontconfig и freetype. Старая матрица включает Debian 9–11, Ubuntu 16.04–22.04, AlmaLinux 8/9, CentOS 6/7, Amazon Linux 2 и openSUSE Leap 15; финальный packaging-релиз содержит также Debian 12 bookworm. Пакет следует выбирать под конкретный дистрибутив и архитектуру.

Особенно важны шрифты. fontconfig и freetype участвуют не только в отображении символов: замена гарнитуры меняет ширину строк, высоту блоков и, как следствие, переносы и пагинацию. Для кириллицы недостаточно указать UTF-8 в HTML — в рабочем образе должна существовать гарнитура с нужными глифами и теми же метриками, что использовалась при утверждении шаблона.

Термин «static» в старой документации пакетов не означает полностью самодостаточный исполняемый файл. Проект отдельно объясняет, что статически связывался главным образом модифицированный Qt, тогда как системные компоненты вроде glibc, OpenSSL, libpng/libjpeg и fontconfig остаются зависимостями. Поэтому перенос бинарника между произвольными Linux-системами без подходящего пакета ненадёжен; контейнер или образ ОС воспроизводит окружение лучше, чем копирование одного файла.

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

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

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

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

Простая автоматизация. CLI легко встроить в существующий серверный процесс или очередь.

Развитые печатные функции. Колонтитулы, нумерация, TOC, outline, поля и несколько HTML-объектов закрывают многие задачи отчётности.

Headless-работа. Обычный графический сеанс не требуется.

Сетевые параметры. Cookies, заголовки, прокси и HTTP Authentication помогают печатать внутренние страницы.

Нет подписки. LGPL 3.0, без аккаунта и фирменного облака.

Минусы

Архивный статус. Новые дефекты и уязвимости ядра официально не исправляются.

Старый WebKit. Современный CSS/JavaScript может отличаться от актуальных браузеров.

Риск недоверенного HTML. Сам проект предупреждает о возможности компрометации сервера.

Зависимость от окружения. Библиотеки и шрифты влияют на переносимость результата.

Нет визуального редактора. Макет правится через HTML/CSS и параметры CLI.

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

WeasyPrint — прямой свободный кандидат для серверных документов без полноценного браузерного JavaScript. Он активно выпускает обновления и ориентирован на paged media. Puppeteer использует текущий Chromium и лучше подходит для страницы, которая должна совпадать с современным Chrome; его Page.pdf поддерживает формат бумаги, поля, фоны и HTML-шаблоны колонтитулов. Prince — коммерческий движок с актуальными пакетами для Windows, macOS и Linux и бесплатным режимом для тестирования/некоммерческого использования; его выбирают ради профессиональной печати и поддержки производителя.

Puppeteer управляет актуальным Chrome/Chromium. Для React/Vue/других клиентских приложений это обычно самый близкий путь к тому, что пользователь видит в браузере: можно дождаться шрифтов и состояния страницы, затем вызвать Page.pdf. Современный PDF API поддерживает размеры, поля, печать фонов, диапазоны страниц, CSS @page, масштаб и HTML-шаблоны колонтитулов. Цена этого совпадения — более тяжёлое браузерное окружение и необходимость регулярно обновлять Chromium вместе с автоматизацией.

Prince 16.2 занимает коммерческий сегмент: производитель предлагает актуальные пакеты для Windows, macOS и Linux, а также официальные интеграционные обёртки. Бесплатное использование относится к тестированию и некоммерческим задачам; коммерческий сценарий требует лицензии или сервиса. Это вариант для команды, которой важнее предсказуемая печатная верстка и поддержка поставщика, чем отсутствие лицензионных затрат.

Поэтому wkhtmltopdf в 2026 году выигрывает не «современностью», а совместимостью с уже закреплённым наследием. Если старый шаблон утверждён именно под 0.12.6 и его перенос дороже изоляции, сохранение текущей цепочки может быть рациональным. Если шаблон только проектируется, активная поддержка WeasyPrint, Chromium/Puppeteer или Prince обычно весит больше, чем привычная команда wkhtmltopdf.

Sumatra PDF не является прямым аналогом: wkhtmltopdf создаёт PDF из HTML, Sumatra PDF открывает готовый файл. Это соседние этапы одного процесса, а не конкурирующие функции. Если после рендера нужно объединять или переставлять страницы, пригодится отдельная утилита вроде PDF24 Creator.

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

Поскольку проект архивирован, сначала зафиксируйте причину использования и эталонный PDF. Если это новый сервис, сравните современный рендерер. Если требуется совместимость со старым шаблоном, устанавливайте ту же линию бинарника, что использовалась в рабочей среде.

Windows

1. Выберите на официальной странице 32- или 64-разрядный установщик 0.12.6. 2. Установите его штатным способом. 3. В новом терминале выполните wkhtmltopdf -V и проверьте, что видна ожидаемая версия с patched qt. 4. Создайте простой локальный HTML и выполните wkhtmltopdf input.html output.pdf; только затем добавляйте сеть и корпоративные ресурсы.

macOS

Используйте официальный 64-разрядный пакет 0.12.6 только для подтверждённой старой зависимости. После установки проверьте wkhtmltopdf -V и минимальный PDF. Если современная macOS блокирует или ломает старый пакет, не обходите системную защиту вслепую — изоляция или миграция безопаснее.

Linux

1. Определите дистрибутив, версию и архитектуру. 2. Выберите официальный пакет из таблицы загрузок или packaging-релиза 0.12.6.1-3 и ставьте его штатным менеджером пакетов: даже «статическая» сборка зависит от системных библиотек. 3. Выполните wkhtmltopdf -V и минимальный рендер. 4. Для локальных CSS и изображений разрешайте только нужный каталог через allow.

Если вместо официального пакета выбран пакет репозитория дистрибутива, отдельно проверьте строку версии и требуемые функции. Собственная документация wkhtmltopdf предупреждает, что часть дистрибутивных сборок создавалась без patched Qt; в них могут отсутствовать или отличаться outline, TOC, колонтитулы и другие возможности, для которых нужны проектные патчи. Для миграции действующей системы важна не только цифра 0.12.6, но и конкретный тип сборки.

Первый запуск и удаление

Контроль первого запуска лучше проводить ступенчато. Сначала выполните wkhtmltopdf -V и сохраните точную строку версии. Затем преобразуйте минимальный HTML без сети; после этого добавьте кириллицу и нужный шрифт, локальное изображение через ограниченный allow, колонтитул и только в последнюю очередь удалённый HTTPS-ресурс. Если ошибка появляется на конкретной ступени, её причина локализуется без гадания между TLS, правами файловой системы, JavaScript и версткой.

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

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

Счёт или акт из контролируемого HTML

Цель. Получить A4 PDF из серверного шаблона. Подготовка. Держите HTML, CSS, логотип и шрифты в отдельном каталоге. Шаги. Сформируйте HTML, задайте A4, поля и allow для каталога ресурсов; при необходимости добавьте page/topage в footer. Проверка. Сверьте реквизиты, страницы, переносы и логотип. Ограничение. Современный Grid/Flex способен изменить макет.

Отчёт с обложкой и оглавлением

Цель. Собрать титульный лист и главы. Подготовка. Структурируйте главы HTML-заголовками. Шаги. Передайте cover, затем toc и страницы; при необходимости подключите собственный XSLT. Проверка. Сверьте PDF-закладки и номера в TOC. Ограничение. Любое изменение CSS может сдвинуть пагинацию.

Динамический внутренний отчёт

Цель. Напечатать данные после асинхронной загрузки. Подготовка. Страница должна работать в старом WebKit. Шаги. Пусть приложение выставляет window.status после готовности, а wkhtmltopdf ждёт это значение. Проверка. Динамические блоки присутствуют в PDF. Ограничение. Для современного SPA надёжнее Puppeteer, чем увеличение фиксированной задержки.

Закрытая страница с сессией

Цель. Печатать внутренний URL без интерактивного входа. Подготовка. Выдайте технической сессии минимальные права. Шаги. Передайте cookie/cookie jar, при необходимости custom-header и proxy. Проверка. PDF содержит только разрешённые данные. Ограничение. Не храните долгоживущие секреты в shell history и общедоступных скриптах.

Пакетная генерация

Цель. Снизить стоимость многочисленных запусков. Подготовка. Сформируйте независимые наборы аргументов и ограничьте параллелизм. Шаги. Передавайте их строками через read-args-from-stdin. Проверка. Учитывайте код завершения каждой операции и наличие выходного файла. Ограничение. Режим не уменьшает сложность тяжёлого HTML.

Печать с отдельным пользовательским CSS

Цель. Получить печатную версию страницы, не меняя её основной stylesheet. Подготовка. Создайте доверенный CSS-файл с правилами для скрытия навигации, ширины таблиц и разрывов страниц. Шаги. Передайте этот файл через user-style-sheet; если шаблон рассчитан на @media print, включите print-media-type, иначе wkhtmltopdf по умолчанию использует screen media. Проверка. Сравните содержимое и разрывы с эталоном, убедитесь, что CSS действительно загрузился. Ограничение. Новый CSS-синтаксис, который не понимает Qt WebKit, сторонний stylesheet не исправит.

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

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

1. Успешный код завершения и ненулевой файл. 2. Открытие независимым просмотрщиком. 3. Проверка первой, последней и средней страниц. 4. Кириллица, изображения и шрифты. 5. Нумерация, TOC и ссылки. 6. Удаление лишних cookies и временных секретов. 7. Фиксация версии wkhtmltopdf, ОС и эталонного PDF для регрессионного контроля.

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

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

wkhtmltopdf использует собственный старый Qt WebKit, а не установленный в системе Chrome. Поэтому поддержка CSS, JavaScript и метрики рендеринга отличаются. Исправлять нужно шаблон под целевой движок либо менять сам движок.

Что означает «with patched qt» в wkhtmltopdf -V?

Это сборка с набором патчей Qt, на которые рассчитана часть возможностей wkhtmltopdf. Дистрибутивный пакет Linux может быть собран иначе, поэтому совпадение номера версии не гарантирует идентичного поведения.

Можно ли писать PDF в конвейер, а не только в файл?

CLI wkhtmltopdf поддерживает «-» как специальный путь для стандартного ввода/вывода, поэтому HTML можно подать из stdin, а PDF получить через stdout. В производственной цепочке это требует аккуратного разделения потоков: бинарный PDF нельзя смешивать с диагностическим выводом, а вызывающая программа должна проверить код завершения и целостность результата. У архивного проекта есть старые отчёты о проблемах потокового режима в отдельных окружениях, поэтому конкретный способ запуска следует закреплять регрессионным тестом.

Как надёжнее ждать JavaScript: delay или window-status?

Фиксированный delay подходит для предсказуемой короткой операции. Для асинхронной страницы лучше window-status: приложение само сигнализирует о готовности. Если нужный JavaScript вообще не поддерживается старым WebKit, ожидание не поможет.

Почему локальный CSS работает, а картинка нет?

С 0.12.6 локальный доступ ограничен. Проверьте реальные пути и allow для каталога ресурсов. Не включайте полный доступ к файловой системе без необходимости.

Можно ли сохранить активные ссылки и формы?

Внутренние и внешние PDF-ссылки поддерживаются и по умолчанию включены. HTML form fields можно преобразовать в PDF-поля отдельной опцией; по умолчанию эта функция выключена.

Если документ должен быть неизменяемой архивной копией, интерактивные поля лучше не включать без отдельного требования: enable-forms меняет характер результата. Для ссылок также проверьте, должен ли внешний URL оставаться активным в передаваемом документе; при необходимости внешние и внутренние ссылки отключаются независимо.

Как уменьшить расхождения между серверами?

Фиксируйте одну версию бинарника, ОС/контейнера, набор системных библиотек, fontconfig и шрифты. Избегайте внешних CDN при генерации эталонных документов.

Почему колонтитул перекрывает основной текст?

Высота колонтитула и поля страницы — отдельные параметры. HTML header/footer не резервирует подходящее место автоматически для любой верстки: нужно согласовать верхнее или нижнее поле со spacing и фактической высотой колонтитула. После изменения шрифта или текста снова проверьте первую и самую плотную страницу.

Можно ли использовать DOCX или скан как вход?

Напрямую нет. DOCX/ODT нужно предварительно экспортировать, а OCR выполняется отдельным инструментом. wkhtmltopdf специализируется на HTML-to-PDF.

Есть ли смысл запускать wkhtmltopdf в контейнере?

Контейнер помогает закрепить библиотеки, шрифты и права процесса, но не обновляет старый WebKit и не исправляет его уязвимости. Для недоверенного HTML одной контейнеризации недостаточно.

Когда миграция становится предпочтительнее ремонта шаблона?

Когда страница зависит от современного JavaScript/CSS, приходится ослаблять системную защиту, новые ОС перестают запускать пакет или команда превращается в набор исключений. В этих случаях WeasyPrint, Chromium/Puppeteer или Prince обычно дают более устойчивую основу.

Вывод

wkhtmltopdf полезен как наследуемый конвертер: CLI прост, а колонтитулы, нумерация, TOC, outline, cookies, прокси и многостраничная сборка закрывают реальные задачи. Если существующая система годами формирует утверждённые отчёты на 0.12.6/0.12.6.1 и входной HTML полностью контролируется, рационально заморозить рабочее окружение, ограничить доступы и держать эталонные PDF для проверки.

Для нового проекта выбор слабее: старый WebKit, архивный статус и официальное предупреждение о недоверенном HTML делают wkhtmltopdf рискованной основой публичного сервиса. WeasyPrint лучше подходит печатному HTML/CSS без сложного браузерного JS, Puppeteer — современным веб-приложениям, Prince — профессиональной верстке с поддержкой производителя.

Sumatra PDF выполняет другую задачу: он открывает готовый PDF. Поэтому в наследуемой цепочке wkhtmltopdf может формировать файл, Sumatra PDF — проверять его, а отдельный редактор подключается только для последующей правки.