Как сохранять веб‑страницы в PDF и изображения через терминал Linux

Wkhtmltopdf и wkhtmltoimage — это небольшие инструменты с открытым исходным кодом, которые рендерят HTML в PDF и в растровые/векторные изображения из терминала. Они полезны для автоматической генерации отчётов, снэпшотов страниц или архивирования контента.

Определение: wkhtmltopdf — командная утилита, использующая движок рендеринга WebKit для преобразования HTML в PDF; wkhtmltoimage делает то же в изображение.

Что умеют эти утилиты

• Генерировать PDF из URL или локального HTML.
• Сохранять страницу в PNG/JPG/SVG.
• Настраивать ориентацию, поля, масштаб и качество.
• Добавлять заголовки/подвалы, печатные копии, включать или исключать изображения.

Важно: для очень динамичных страниц, которые сильно зависят от JavaScript или WebSocket, рендер WebKit в wkhtmltopdf может не выполнить все скрипты. Для таких случаев лучше headless Chrome/Chromium или Puppeteer.

Установка wkhtmltopdf и wkhtmltoimage на Linux

Wkhtmltopdf часто не входит в минимальные наборы пакетов. Ниже — команды для популярных дистрибутивов.

На Ubuntu/Debian:

sudo apt update
sudo apt install wkhtmltopdf

На Arch‑основанных (Manjaro):

sudo pacman -S wkhtmltopdf

На RHEL/Fedora/CentOS:

sudo dnf install wkhtmltopdf

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

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

Команды просты и последовательны:

wkhtmltopdf  
wkhtmltoimage  

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

wkhtmltopdf https://google.com google.pdf

При открытии PDF вы увидите документ, в котором wkhtmltopdf постарался максимально точно отобразить структуру страницы.

Полезные опции для PDF

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

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

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

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

wkhtmltopdf --grayscale https://google.com google_gray.pdf

• –orientation portrait|landscape — ориентация страницы.

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

• –no-images — не рендерить изображения на странице.

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

Дополнительные часто полезные опции:

• –margin-top/–margin-bottom/–margin-left/–margin-right <мм|см|in>
• –zoom <число> — масштаб рендеринга (например 1.2)
• –dpi <число> — точки на дюйм для точности при конвертации в изображения
• –header-center/–footer-right — добавить текст в заголовок или подвал
• –no-background — не включать фоновые цвета/изображения

Короткий пример: печатать страницу с полями 10 мм и заголовком:

wkhtmltopdf --margin-top 10mm --margin-bottom 10mm --header-center "Отчёт" https://example.com report.pdf

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

Wkhtmltoimage работает по тому же принципу, но сохраняет в растровые/векторные форматы.

Базовая команда:

wkhtmltoimage https://google.com google.png

Поддерживаемые форматы: PNG, JPG, SVG. Просто укажите нужное расширение в имени файла.

wkhtmltoimage https://google.com google.jpg

Советы по качеству изображений:

• Для веб‑скриншотов используйте PNG при необходимости прозрачности и высоких деталей.
• Для фотографий и меньших размеров используйте JPG с опцией –quality <0-100>.
• Для векторной графики (например, сохранения SVG) убедитесь, что контент действительно векторный.

Автоматизация: сценарии и cron

Часто нужно генерировать PDF/изображения регулярно. Пример простого bash‑скрипта для пакетной конвертации:

#!/bin/bash
# batch_convert.sh
URLs=("https://example.com/page1" "https://example.com/page2")
OUT_DIR="/var/reports/webshots"
mkdir -p "$OUT_DIR"
for url in "${URLs[@]}"; do
  name=$(echo "$url" | sed 's/[^a-zA-Z0-9]/_/g')
  wkhtmltopdf "$url" "$OUT_DIR/${name}.pdf"
done

Поставьте его в cron, чтобы запускать по расписанию:

0 6 * * * /usr/local/bin/batch_convert.sh >> /var/log/webshots.log 2>&1

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

• Скрипт успешно создаёт PDF для каждого URL без ошибок.
• Размеры и ориентация совпадают с требованиями шаблона.
• Файлы сохраняются в указанной директории с понятными именами.

Тонкости и ограничения (когда инструмент может не подойти)

• JavaScript‑тяжёлые одностраничные приложения (SPA): wkhtmltopdf может не дождаться выполнения всех асинхронных скриптов. Для таких сайтов лучше использовать headless Chrome/Puppeteer.
• Современные CSS‑фичи (grid, flex, новые свойства) могут отображаться иначе, чем в современном браузере.
• Аутентификация и защищённый контент: если страница требует логин/cookie, нужно передать соответствующие заголовки или использовать локальный HTML.
• Большие страницы: при рендеринге больших документов следите за потреблением памяти.

Альтернативы и когда их выбирать

• Headless Chrome / Puppeteer: для сложных JS‑страниц, контроля времени ожидания, взаимодействия с DOM.
• wkhtmltopdf: хорош для статичных и серверных HTML, быстрый старт.
• WeasyPrint: альтернатива на Python с хорошей поддержкой CSS, если нужна интеграция в Python‑проект.
• Chrome‑headless (через CLI) для простых скриншотов: chrome –headless –screenshot.

Пример вызова Puppeteer (Node.js) для полноценных динамических рендеров — см. документацию Puppeteer.

Руководство по отладке

1. Проверяйте HTML локально: wkhtmltopdf file.html out.pdf
2. Включайте –debug-javascript для диагностики JS‑ошибок.
3. Если контент не загрузился — увеличьте таймаут опцией –javascript-delay .
4. Для проблем с шрифтами проверяйте доступность локальных шрифтов и их embedding.
5. При ошибках компиляции попробуйте другую сборку wkhtmltopdf (qt4/qt5).

Мини‑плейбук: быстрый SOP для создания отчёта в PDF

1. Подготовьте шаблон HTML с print‑friendly CSS.
2. Локально проверьте рендер в браузере и откорректируйте CSS для печати.
3. Запустите wkhtmltopdf с нужными опциями (поля, ориентация, header/footer).
4. Проверьте выходной PDF на обязательные элементы: логотип, колонтитулы, нумерацию.
5. Автоматизируйте запуск и хранение в безопасном каталоге.

Ролевые чек‑листы

• Разработчик:

  • Есть print CSS.
  • Проверен локальный HTML.
  • Скрипт выдаёт exit code 0.

• Системный администратор:

  • Установлен wkhtmltopdf и зависимости.
  • Настроен cron и ротация логов.
  • Контроль прав доступа к папке с отчётами.

• QA/Контент‑менеджер:

  • Визуальная проверка PDF.
  • Проверка корректности пагинации и ссылок.

Безопасность и конфиденциальность

• Не передавайте в командной строке пароли в открытом виде. Лучше использовать cookie‑файлы или защищённые токены.
• При сохранении страниц с персональными данными соблюдайте политику хранения и удаления (GDPR/локальные требования).
• Запуск рендеринга сторонних URL на сервере может быть использован для SSRF‑атак; ограничьте список URL или используйте прокси/фильтры.

Пример дерева решений (меркмайд для выбора инструмента)

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

Частые ошибки и решения

• “Segmentation fault” при запуске — попробуйте другую сборку или увеличьте доступную память.
• Пустой PDF — проверьте, нет ли редиректов или требуемой авторизации.
• Неправильные шрифты — установите нужные системные шрифты или укажите @font‑face в CSS с локальными файлами.

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

Wkhtmltopdf и wkhtmltoimage — быстрый и эффективный способ захватить веб‑страницы в PDF или изображение прямо из терминала. Они легко автоматизируются и покрывают большинство задач по конвертации статичных страниц. Для динамичных SPA и сайтов с интенсивным JS лучше использовать headless Chrome/Puppeteer. Следуйте практикам безопасности при автоматическом рендеринге защищённого контента.

Важно: перед массовым архивированием проверьте юридическую сторону хранения копий веб‑контента и соблюдение конфиденциальности.

Список полезных шагов для старта:

1. Установите wkhtmltopdf.
2. Подготовьте print‑дружественный HTML/CSS.
3. Протестируйте локально и в скрипте.
4. Настройте cron и мониторинг ошибок.

Если нужно, могу подготовить готовый bash‑скрипт, docker‑образ или пример на Puppeteer для конкретного сайта.