Как преобразовать веб-страницу в PDF и изображение в Linux

В этой статье показано, как захватить веб-страницу и сохранить её как PDF-документ или как изображение, работая из терминала Linux. Мы разберём установку, базовые команды, полезные опции, сценарии применения, когда инструмент не сработает, и альтернативные подходы.

Что такое wkhtmltopdf и wkhtmltoimage

wkhtmltopdf — это открытая консольная утилита, которая рендерит веб-страницы в PDF. wkhtmltoimage входит в тот же пакет и сохраняет страницы как изображения (PNG, JPG, SVG). Оба инструмента работают без запуска видимого браузера — рендер идёт headless.

Определение в одну строку: wkhtmltopdf/wkhtmltoimage — движок рендеринга страниц на базе Qt WebKit для конвертации HTML в PDF/изображения.

Важно: эти утилиты хорошо работают с классическими статическими страницами. Для сложных JavaScript-приложений может потребоваться headless-браузер.

Установка на популярных дистрибутивах

На Debian/Ubuntu и производных:

sudo apt install wkhtmltopdf

На Arch-based дистрибутивах (Manjaro и др.):

sudo pacman -S wkhtmltopdf

На RHEL-подобных (Fedora, CentOS Stream):

sudo dnf install wkhtmltopdf

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

Базовый синтаксис

Общая форма команды для PDF:

wkhtmltopdf <веб-страница> <выходной-файл.pdf>

Пример — сохранить главную страницу Google в PDF:

wkhtmltopdf https://google.com google.pdf

Вывод рендерится в файл google.pdf и обычно соответствует видимой структуре страницы.

При открытии PDF вы увидите страницу, преобразованную в документ.

Полезные опции и примеры использования

Ниже перечислены часто используемые флаги с кратким описанием и примерами.

• –copies N — добавить N копий страницы в один PDF (не создаёт несколько файлов):

wkhtmltopdf --copies 3 https://google.com google.pdf

• -g или –grayscale — сделать вывод в оттенках серого:

wkhtmltopdf -g https://google.com google.pdf

• –orientation [Portrait|Landscape] — ориентация страницы (portrait по умолчанию):

wkhtmltopdf --orientation landscape https://google.com google.pdf

• –no-images — не включать изображения в итоговый документ:

wkhtmltopdf --no-images https://google.com google.pdf

• –page-size A4|Letter — задать размер страницы:

wkhtmltopdf --page-size A4 https://example.com report.pdf

• –margin-top/–margin-bottom/–margin-left/–margin-right — настроить поля:

wkhtmltopdf --margin-top 10mm --margin-bottom 10mm https://example.com report.pdf

• –zoom N — масштаб рендера (например, 1.25 для увеличения):

wkhtmltopdf --zoom 1.25 https://example.com report.pdf

• –enable-javascript и –javascript-delay ms — разрешить JS и задать задержку для загрузки динамического содержимого:

wkhtmltopdf --enable-javascript --javascript-delay 2000 https://site-with-js.example out.pdf

• –enable-local-file-access — разрешить доступ к локальным файлам (если в HTML используются локальные ресурсы):

wkhtmltopdf --enable-local-file-access file:///home/user/report.html out.pdf

Таблица быстрого доступа (обзор):

Конвертация страницы в изображение

Синтаксис wkhtmltoimage аналогичен:

wkhtmltoimage <веб-страница> <выходной-файл.png>

Пример для Google в PNG:

wkhtmltoimage https://google.com google.png

wkhtmltoimage поддерживает расширения PNG, JPG и SVG — просто укажите нужную расширение в имени файла.

wkhtmltoimage https://google.com google.jpg

Мини-методология: автоматизация конвертации для отчётов

1. Составьте список URL, которые нужно сохранить.
2. Напишите небольшой shell-скрипт, который перебирает список и вызывает wkhtmltopdf/wkhtmltoimage.
3. Добавьте обработку ошибок: проверяйте код возврата; логируйте неудачные URL.
4. Если сайт требует авторизации, используйте заголовки/куки или проходите auth через скрипт перед вызовом.
5. Интегрируйте в cron/systemd timer для регулярной генерации отчётов.

Пример шаблона скрипта:

#!/bin/bash
urls=("https://site1.example" "https://site2.example")
for u in "${urls[@]}"; do
  out=$(basename "$u")
  wkhtmltopdf --enable-javascript --javascript-delay 2000 "$u" "${out}.pdf"
  if [ $? -ne 0 ]; then
    echo "Ошибка при обработке $u" >> /var/log/wkhtmltopdf-errors.log
  fi
done

Когда wkhtmltopdf не подходит и альтернативы

Когда он не сработает:

• Страница — SPA (React/Vue) с поздней подгрузкой данных через XHR/fetch. JavaScript может требовать времени или событий, которые wkhtmltopdf не воспроизводит полностью.
• Нужна сложная интерактивная отрисовка или WebGL/Canvas с динамическим контентом.
• Страница защищена сложной аутентификацией (OAuth, MFA) без возможности подставить cookie/токен.

Альтернативы:

• Headless Chrome/Chromium через Puppeteer или Playwright — лучший выбор для динамического JS и управления сценариями.
• WeasyPrint — если требуется строгое соответствие CSS и Python-экосистема.
• CutyCapt — устаревший, но иногда полезен для простых задач.

Пример запуска headless Chrome для PDF (Puppeteer на Node.js): кратко — позволяет управлять событиями, ждать селекторов и делать скриншоты/PDF с точной эмуляцией браузера.

Отладка и часто встречаемые проблемы

• Пустой PDF или отсутствует контент: попробуйте –enable-javascript и –javascript-delay 2000 (значение в миллисекундах).
• Страницы с локальными ресурсами: используйте –enable-local-file-access или укажите полный file:// путь.
• Проблемы с шрифтами: убедитесь, что нужные системные шрифты установлены в окружении сервера.
• Ограничения окружения без GUI: wkhtmltopdf должен работать headless, но в редких случаях требуется установка шрифтов или библиотек X11/GTK.

Контроль качества и критерии приёмки

Критерии приёмки:

• PDF содержит основной контент страницы (текст/ключевые изображения) в том числе после указанной javascript-задержки.
• Страницы имеют читаемую типографику и корректные поля/ориентацию.
• Скрипт корректно логирует ошибки и возвращает ненулевой код при сбое.

Чек-листы по ролям

Для разработчика:

• Проверить рендер с –enable-javascript и разными задержками.
• Добавить тесты на стабильность рендера (сравнение SHA/скриншотов).

Для системного администратора:

• Убедиться в наличии бинарника в PATH и прав на запись в целевую папку.
• Настроить ротацию логов и уведомления об ошибках.

Для контент-редактора:

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

Шпаргалка команд (cheat sheet)

• Быстрая конверсия в PDF:

wkhtmltopdf https://example.com out.pdf

• PDF в оттенках серого с ландшафтной ориентацией:

wkhtmltopdf -g --orientation landscape https://example.com out.pdf

• Снять скриншот в JPG:

wkhtmltoimage https://example.com out.jpg

• Включить JS и ждать загрузки:

wkhtmltopdf --enable-javascript --javascript-delay 3000 https://example.com out.pdf

Небольшая диаграмма выбора инструмента

flowchart TD
  A[Нужно захватить страницу?] --> B{Страница статическая?}
  B -- Да --> C[wkhtmltopdf/wkhtmltoimage]
  B -- Нет --> D{Требуется полный рендер JS?}
  D -- Да --> E[Headless Chrome / Puppeteer / Playwright]
  D -- Нет --> C
  C --> F[Скрипт и cron]
  E --> F

Безопасность и приватность

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

Краткое резюме

wkhtmltopdf и wkhtmltoimage — удобные и лёгкие инструменты для конвертации HTML в PDF и изображения из терминала Linux. Они отлично подходят для статических страниц и простых отчётов. Для динамического контента и сложных сценариев используйте headless-браузерные решения. Автоматизацию можно легко встроить в cron/systemd с логированием и обработкой ошибок.

Ключевые шаги: установка пакета, выбор нужных флагов, тестирование рендера, автоматизация и мониторинг.