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

Такая ошибка особенно неприятна, когда документы нужны сразу после заказа, оплаты или заявки.

Коротко: нужно проверить библиотеку генерации, HTML-шаблон, шрифты, права на папки, память и системные зависимости сервера.

Почему возникает проблема

PDF-генераторы часто зависят от внешних бинарников, доступных шрифтов, временных папок и корректного HTML. На локальном компьютере все может работать, а на сервере падать из-за отсутствующей зависимости или запрета записи.

Что проверить сначала

  • ошибка в логах PHP или веб-сервера
  • наличие нужных шрифтов и кириллицы
  • права на временную папку и папку документов
  • лимиты памяти и времени выполнения
  • работает ли генератор из консоли

Как я подхожу к исправлению

Я проверяю генерацию на минимальном шаблоне, потом постепенно возвращаю реальные данные, стили и изображения.

  • нахожу точную ошибку генератора
  • исправляю системные зависимости и права
  • подключаю корректные шрифты
  • упрощаю или чиню HTML-шаблон
  • добавляю логирование и обработку неудачных генераций

Что подготовить перед работой

  • пример документа, который не создается
  • ссылку на страницу генерации
  • лог ошибки или скрин
  • доступ к серверу
  • пример ожидаемого PDF

Какой результат нужен

PDF должен стабильно создаваться на сервере, корректно показывать кириллицу, изображения и таблицы, а при ошибке оставлять понятный лог.

Чего лучше не делать

Не скрывайте ошибки генератора общим сообщением. Без логов следующая поломка снова превратится в угадывание.

FAQ

Почему PDF работает локально, но падает на сервере?

На сервере могут отсутствовать шрифты, бинарники, права на папки или нужные расширения PHP.

Что лучше: wkhtmltopdf или headless Chrome?

Зависит от шаблона и окружения. Chrome лучше понимает современный CSS, но требует больше ресурсов.

Можно ли ускорить генерацию?

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

Что делать с битым PDF?

Проверить размер, HTTP-заголовки и ошибки, которые могли попасть внутрь файла вместо PDF-данных.

Нужна похожая задача?

Напишите в Telegram @rabotator_support или оставьте заявку на сайте. Коротко опишите проблему, приложите ссылку, скриншот или лог ошибки, и я подскажу, с чего безопасно начать исправление.

Итог

Падение PDF-генерации обычно лечится системной диагностикой: библиотека, шаблон, шрифты, права, ресурсы и понятные логи.