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

Работа строится вокруг команды pdfcpu и подкоманд по назначению: validate проверяет файл, info выводит его характеристики, merge собирает несколько документов, split и trim формируют новые наборы страниц, а stamp, watermark, encrypt и permissions меняют содержимое или правила доступа. Параметры показываются через --help, сокращённые флаги можно использовать в сценариях, а выбор страниц задаётся отдельным выражением, одинаковым для большинства операций.

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

Как устроена работа с pdfcpu

У программы нет окна с панелью инструментов: роль интерфейса выполняет командная строка, а состояние операции видно по текстовым сообщениям и коду завершения процесса. Это не означает, что приходится запоминать весь синтаксис. Команда без аргументов показывает список доступных разделов, команда с --help раскрывает аргументы и флаги конкретного действия, а completion генерирует автодополнение для Bash, Zsh, Fish или PowerShell. Практический подход состоит в том, чтобы один раз подобрать рабочую команду, сохранить её в сценарии и затем менять только имена файлов, диапазоны страниц и параметры оформления.

Общая форма вызова выглядит как имя программы, подкоманда, обязательные аргументы и флаги. Порядок позиционных аргументов важен: в merge сначала указывается выходной файл, затем входные документы; в validate выходного файла нет; в crop описание геометрии ставится перед входным PDF; в stamp и watermark после действия add указываются текст или файл, строка параметров, входной и необязательный выходной документ. Когда команда не принимается, первым делом нужно открыть её справку, потому что разные группы используют похожие флаги, но ожидают разный порядок аргументов.

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

После распаковки архива исполняемый файл можно оставить рядом с документами или добавить каталог с ним в переменную PATH. На Windows используется pdfcpu.exe, а в Unix-подобных системах — файл pdfcpu с правом на выполнение. Проверку установки выполняют командой version. Затем стоит создать отдельную рабочую папку, положить туда копию PDF и выполнить info и validate. Такой порядок сразу показывает, видит ли оболочка программу, читается ли файл, требуется ли пароль и есть ли структурные ошибки, которые могут повлиять на последующие преобразования.

pdfcpu version
pdfcpu info document.pdf
pdfcpu validate document.pdf

Если путь содержит пробелы, имя нужно заключить в кавычки. В PowerShell запуск файла из текущей папки обычно требует префикса .\, поэтому команда выглядит как .\pdfcpu.exe validate "Мой документ.pdf". В Bash и Zsh для файла рядом с документом используется ./pdfcpu. Эти отличия относятся к оболочке, а не к самой программе; набор подкоманд и смысл параметров остаются одинаковыми.

Справка, общие флаги и конфигурация

Флаг -v включает подробный журнал, а -vv выводит максимально детальную диагностику, полезную при отчёте об ошибке или разборе проблемного PDF. Флаг -q подавляет обычный вывод и удобен в автоматических заданиях, где важны только код завершения и созданный файл. --force разрешает намеренную перезапись существующего выхода и запись в непустые каталоги для тех команд, которые это поддерживают. Без него программа старается не уничтожать готовый результат незаметно, поэтому старые сценарии после изменения поведения перезаписи могут останавливаться до добавления явного --force.

Флаг --offline запрещает исходящие сетевые обращения. Он особенно уместен при обработке конфиденциальных документов и при проверке ссылок или заполнении элементов, для которых разрешено получение удалённых ресурсов. Флаг --conf задаёт каталог конфигурации либо отключает его значением disable. В конфигурации хранятся пользовательские шрифты, сертификаты доверия и лимиты обработки, поэтому при переносе сценария на другой компьютер нужно учитывать не только бинарный файл, но и содержимое каталога настроек.

Команда config list показывает активные параметры, а config reset создаёт конфигурацию, соответствующую поддерживаемой структуре настроек. Сброс полезен, если после обновления программа предупреждает о несовместимой схеме или новых обязательных полях. Перед сбросом стоит сохранить копию каталога, потому что в нём могут находиться установленные шрифты и импортированные сертификаты. Лимиты на размер потоков, число объектов, объём декодированных данных, количество пикселей, глубину рекурсии и элементы таблицы перекрёстных ссылок защищают от чрезмерно сложных или повреждённых файлов; их повышение должно быть осознанным.

Единицы измерения и сокращения

Геометрические команды принимают точки, дюймы, сантиметры или миллиметры. Единицу задают через --unit; если она не указана, параметры интерпретируются в точках. Для кратких сценариев можно использовать уникальные префиксы названий параметров, но слишком короткий префикс бывает неоднозначным. Например, буква o может совпасть с opacity и offset, тогда как op однозначно означает прозрачность. В производственных сценариях лучше применять полные или очевидные сокращения: так команду проще читать спустя несколько месяцев и меньше риск, что новый параметр сделает прежнее сокращение неоднозначным.

Выбор страниц: диапазоны, чётные и нечётные

Флаг --pages или -p используется в rotate, trim, crop, watermark, stamp, extract, nup и многих других командах. Он принимает список выражений через запятую. Отдельное число выбирает одну страницу, запись 2-5 — непрерывный диапазон, 7- — страницы с седьмой до конца, -3 — первые три страницы. Ключевые слова odd и even выбирают нечётные и чётные страницы. Несколько выражений объединяются, поэтому можно обработать первые три страницы, пятую и всё с седьмой до конца одной строкой.

pdfcpu rotate -pages 1-3,5,7- document.pdf 90 rotated.pdf
pdfcpu trim -pages odd document.pdf odd-pages.pdf
pdfcpu watermark add "Черновик" "rot:0, op:.4" document.pdf marked.pdf --mode text --pages 2-

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

Выбор страниц не всегда означает, что остальные страницы исчезнут. В rotate выбранные страницы поворачиваются, а остальные сохраняются; в watermark и stamp отметка наносится только на выбранные листы; trim создаёт документ из выбранной последовательности; collect позволяет собрать страницы в заданном порядке и повторять их. Поэтому перед запуском нужно понимать модель конкретной команды: изменение части исходного документа, извлечение набора или создание новой раскладки.

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

validate читает структуру PDF и проверяет согласованность объектов, таблиц перекрёстных ссылок, деревьев страниц, ресурсов и других элементов. Режим relaxed терпимее к распространённым отклонениям, которые встречаются в файлах, открывающихся в популярных просмотрщиках, а strict предъявляет более жёсткие требования к соответствию спецификации. Если документ предстоит архивировать, подписывать или передавать в систему с формальной проверкой, полезно прогнать оба режима и сохранить подробный журнал -vv. Успешная проверка не означает соответствие PDF/A или PDF/UA: для профильной валидации нужны специализированные средства.

pdfcpu validate report.pdf
pdfcpu validate --mode strict report.pdf
pdfcpu validate -vv damaged.pdf

info выводит свойства файла: версию PDF, число страниц, размеры, наличие шифрования, форм, подписей, вложений и другие характеристики, доступные анализатору. Команда удобна перед объединением документов с разными форматами листа и перед выбором способа печатной раскладки. Если файл защищён пользовательским паролем, его передают через --upw; владелец может использовать --opw. Пароли не стоит хранить прямо в общих сценариях или истории командной оболочки: безопаснее получать их из защищённой переменной окружения или интерактивного ввода оболочки.

Повреждённый файл может открываться в просмотрщике, но отклоняться pdfcpu из-за некорректного дерева страниц, неверного счётчика объектов или ошибочной ссылки. В таком случае подробный validate показывает участок разбора. Сначала нужно проверить, не обрезан ли файл при копировании, затем пересохранить его в доверенном просмотрщике или обработать инструментом, умеющим перестраивать таблицу ссылок. После восстановления следует снова выполнить validate, а не предполагать, что успешное открытие гарантирует корректность всех операций.

Оптимизация и контроль размера файла

optimize удаляет неиспользуемые и дублирующиеся ресурсы страниц, перестраивает внутреннюю структуру и записывает обработанный PDF. Эффект зависит от источника документа. Файл с повторяющимися шрифтами, изображениями или объектами может заметно уменьшиться, а уже хорошо оптимизированный PDF почти не изменится. Команда не является универсальным растровым компрессором: она не должна автоматически ухудшать качество всех изображений ради минимального размера. Поэтому размер до и после нужно сравнивать вместе с визуальной проверкой и validate результата.

pdfcpu optimize input.pdf optimized.pdf
pdfcpu optimize -v input.pdf optimized.pdf

Во многих изменяющих командах оптимизация уже является частью записи результата. Не следует без причины добавлять отдельный optimize после merge, trim, rotate, stamp или watermark: лишний проход увеличивает время, а выигрыш может отсутствовать. Отдельный шаг оправдан, если нужно нормализовать внешние файлы перед загрузкой, убрать избыточные ресурсы без других изменений или получить диагностический отчёт по структуре.

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

Объединение, разделение и сборка нужной последовательности

Merge: объединение нескольких PDF

merge создаёт один документ из нескольких входных файлов. Выход указывается первым, затем идут источники в нужном порядке. Имена можно перечислять явно или формировать средствами оболочки, но при использовании шаблонов нужно проверить сортировку: строковый порядок поставит file10.pdf перед file2.pdf, если номера не дополнены ведущими нулями. Для юридических и отчётных пакетов безопаснее сформировать точный список источников и записать его в журнал задания.

pdfcpu merge combined.pdf cover.pdf chapter01.pdf chapter02.pdf appendix.pdf

Закладки при объединении можно оборачивать в отдельные ветви по исходным документам либо сохранять их структуру. Режим bookmark-mode wrap удобен, когда нужен верхний уровень с названиями файлов; preserve подходит, если исходные деревья уже организованы и их следует соединить без дополнительной обёртки. После merge необходимо проверить не только число страниц, но и переходы закладок, особенно если в исходниках встречались одинаковые цели или нестандартные назначения.

Split, trim и collect

split разбивает многостраничный документ на отдельные файлы. Без дополнительной схемы он создаёт одностраничные PDF, а параметр span группирует страницы блоками заданного размера. Команда пишет результаты в каталог, поэтому важно заранее выбрать пустую папку или явно разрешить запись в непустую через --force. Для тысяч страниц стоит проверить правила именования и свободное место: множество маленьких файлов создаёт заметную нагрузку на файловую систему.

trim формирует новый PDF только из выбранных страниц и сохраняет их естественный порядок. Это самый прямой способ оставить главы 1-3 и приложение, удалить рекламные листы или собрать нечётные страницы. collect отличается тем, что создаёт пользовательскую последовательность и допускает повторение страниц. С его помощью можно переставить листы, продублировать титульный лист или составить учебный комплект по схеме 1,3,2,3. Для простой выборки без повторов обычно понятнее trim, а для точной перестановки — collect.

pdfcpu split manual.pdf pages
pdfcpu split manual.pdf chunks 20
pdfcpu trim -pages 1-12,25-30 manual.pdf selected.pdf
pdfcpu collect -pages 1,3,2,3 source.pdf custom-order.pdf

Вставка, удаление и поворот страниц

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

rotate поворачивает выбранные страницы на угол, кратный 90 градусам. Положительное значение обычно означает поворот по часовой стрелке, отрицательное — в обратную сторону. Операция меняет геометрию страницы и учитывает связанные элементы, однако сложные аннотации и поля после преобразований следует проверять в просмотрщике. Если скан визуально лежит боком из-за самого изображения внутри страницы, поворот страницы исправляет отображение целиком; отдельное вращение встроенного изображения потребует другой обработки.

pdfcpu pages remove -pages 2,5-7 input.pdf cleaned.pdf
pdfcpu rotate -pages even input.pdf 90 rotated.pdf
pdfcpu rotate -pages 1 input.pdf -90 first-page-fixed.pdf

После поворота или удаления страниц полезно повторить validate и проверить закладки. Закладка может указывать на страницу, которая была удалена или перемещена; программа старается поддерживать согласованность структуры, но смысл навигации зависит от содержимого. В документах с формами также нужно проверить порядок табуляции и расположение виджетов. Если целью является только временно повернуть отображение в просмотрщике, изменение файла может быть лишним; rotate нужен тогда, когда ориентацию следует закрепить в самом PDF.

Обрезка, границы страниц и изменение геометрии

PDF хранит несколько прямоугольников страницы: MediaBox задаёт физическую область, CropBox определяет видимую часть, а TrimBox, BleedBox и ArtBox используются в издательских процессах. Команда boxes list показывает присутствующие границы, boxes add создаёт или меняет их, boxes remove удаляет выбранные типы. crop устанавливает CropBox по описанию отступов, размера или позиции. Важно отличать скрытие содержимого за границей от физического удаления объектов: обрезка меняет область отображения, но данные вне неё могут оставаться в файле.

Для удаления конфиденциального текста crop не подходит. Скрытая область может быть восстановлена изменением CropBox или извлечением объектов. Настоящее обезличивание требует удаления содержимого специализированным редактором и последующей проверки. В pdfcpu crop полезен для устранения полей скана, подготовки страниц к печати, выравнивания размеров и выделения области, которую должен показывать просмотрщик.

pdfcpu boxes list input.pdf
pdfcpu crop "margins:20" input.pdf cropped.pdf
pdfcpu boxes add "crop:10 10 585 832" input.pdf boxed.pdf

resize меняет размер страницы и масштабирует содержимое согласно описанию; zoom увеличивает или уменьшает отображаемую область; poster разрезает одну страницу на несколько листов для печати плаката; cut и ndown делят страницы по сетке и создают отдельные части. Эти команды используют единицы измерения, ориентацию, поля и фон. При подготовке к печати нужно сверять фактический формат бумаги, допустимые непечатаемые поля принтера и порядок частей, иначе математически правильная раскладка окажется неудобной для сборки.

Изменение размеров особенно чувствительно к аннотациям, ссылкам и полям форм, потому что их прямоугольники должны трансформироваться вместе со страницей. После resize или zoom следует открыть документ в двух разных просмотрщиках и проверить кликабельные области, поля ввода и комментарии. Если исходный PDF использует нестандартные повороты, вложенные формы XObject или некорректные координаты, сначала стоит выполнить validate и тест на одной странице.

N-up, Grid и Booklet для печати и раздаточных материалов

nup размещает несколько исходных страниц на одном листе. Поддерживаются значения 2, 3, 4, 8, 9, 12 и 16, которым соответствуют определённые сетки для книжной и альбомной ориентации. Описание задаёт формат листа, собственные размеры, направление заполнения, рамки, поля, фон и автоматический поворот содержимого. Типичный сценарий — четыре слайда на листе A4 для раздаточного материала или девять миниатюр для быстрого просмотра длинного документа.

pdfcpu nup "form:A4L, margin:8, border:on" handout.pdf 4 slides.pdf
pdfcpu nup "form:A4, border:off" contact-sheet.pdf 9 pages.pdf

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

booklet переставляет страницы для двусторонней печати и последующей фальцовки. Значение 2 создаёт по две страницы на стороне листа, 4 — макет небольшого зина, доступны и другие схемы. Параметры binding и btype выбирают длинную или короткую сторону переплёта, обычную брошюровку, расширенную схему либо perfect bound. Для длинных документов multifolio делит книгу на тетради; foliosize задаёт число листов в одной тетради. Направляющие, поля и фон помогают понять линии реза и сгиба.

Перед печатью booklet нужно проверить настройку двусторонней печати и переворот по длинной или короткой стороне. Ошибка драйвера принтера даст перевёрнутую обратную сторону даже при правильном PDF. Надёжный тест — создать восьмистраничный образец с крупными номерами, напечатать один лист, сложить его и убедиться в порядке. Только после этого следует обрабатывать книгу на сотни страниц и выбирать размер тетради.

Импорт изображений и работа с графическими ресурсами

import создаёт PDF из одного или нескольких изображений. Поддерживаемые растровые форматы зависят от декодеров программы; практические сценарии включают JPEG, PNG, TIFF и WebP, а многостраничный TIFF превращается в последовательность PDF-страниц. Описание позволяет выбрать формат листа, позицию, масштаб, поля и фон. Если выходной PDF уже существует, поведение добавления страниц нужно проверять по справке команды и использовать отдельное имя, когда важно сохранить исходный файл.

Для фотографий следует решить, должна ли страница соответствовать размеру изображения или заданному бумажному формату. В первом случае PDF удобен как контейнер без лишних полей, во втором — как документ для печати на A4, Letter или другом листе. Масштаб relative вписывает изображение относительно доступной области, absolute использует физический размер. Единица измерения влияет на числовые параметры, поэтому один и тот же сценарий нельзя без проверки переносить между points и mm.

images list показывает встроенные изображения, их объектные номера, страницы, размеры и другие характеристики. images extract извлекает исходные графические ресурсы, а не визуально отрисовывает страницу целиком. Это принципиальное ограничение: если страница состоит из текста, векторных линий и нескольких картинок, extract вернёт картинки, но не готовый снимок страницы. Для преобразования каждой страницы в PNG нужен рендерер, например MuPDF, Poppler или Ghostscript.

pdfcpu images list brochure.pdf
pdfcpu images extract brochure.pdf extracted-images
pdfcpu images update brochure.pdf replacement.png updated.pdf 25

images update заменяет конкретное изображение по номеру объекта либо по сочетанию страницы и идентификатора. Перед заменой нужно выполнить list, сохранить исходный ресурс и подобрать файл подходящего размера и цветовой модели. Одна и та же картинка может использоваться на нескольких страницах через общий объект; замена такого объекта изменит все места использования. Если требуется изменить только одно появление, сначала нужно выяснить, создаёт ли документ отдельный ресурс для этой страницы.

Штампы и водяные знаки

В терминологии pdfcpu stamp помещается поверх существующего содержимого, а watermark — позади него. Оба инструмента работают с текстом, изображением или страницей другого PDF и поддерживают позицию, смещение, поворот, масштаб, прозрачность, цвет, шрифт, рамку и фон. Разница слоёв особенно важна для сканов: полноразмерное растровое изображение страницы может полностью закрыть фоновой watermark, поэтому для видимой пометки на скане лучше stamp с уменьшенной прозрачностью.

Текстовый режим поддерживает шаблоны номера текущей страницы и общего числа страниц. Это позволяет добавить нижний колонтитул вида Страница 3 из 42 без предварительного вычисления для каждого листа. Позиции задаются якорями: верхний левый, верхний центр, верхний правый, центр, нижние позиции и боковые центры. Для точного размещения используются offset и единицы измерения. Параметр rotation задаёт угол, opacity — прозрачность, scale — относительный или абсолютный размер.

pdfcpu stamp add "Страница %p из %P" "pos:bc, rot:0, scale:1 abs" input.pdf numbered.pdf --mode text
pdfcpu watermark add "ЧЕРНОВИК" "rot:45, op:.25, scale:.8" input.pdf draft.pdf --mode text

Штампы можно наслаивать. Сначала наносится диагональная пометка, затем логотип в углу и нижний колонтитул. update меняет существующий штамп или водяной знак, remove удаляет их с выбранных страниц или из всего документа. Чтобы удаление было предсказуемым, лучше выполнять полный жизненный цикл одним инструментом и хранить команды создания. Если PDF уже содержал похожий графический элемент, программа не обязана распознать его как добавленный watermark.

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

Аннотации, закладки и навигация

Группа annotations перечисляет аннотации и позволяет удалять выбранные типы или объекты. В PDF аннотациями могут быть текстовые заметки, ссылки, выделения, штампы-комментарии, виджеты форм и другие интерактивные элементы. Перед удалением нужно получить список и убедиться, что фильтр не затрагивает поля формы или полезные ссылки. Вывод list доступен в обычном и JSON-представлении, что удобно для автоматического анализа и отчётов.

Закладки управляются командами list, export, import и remove. Экспорт сохраняет дерево в JSON, где видны заголовки, уровни вложенности и назначения. Такой файл можно редактировать программно, затем импортировать обратно. При создании закладок нужно проверять, что целевые страницы существуют после trim, merge или удаления листов. Если сначала импортировать дерево, а затем менять структуру документа, навигация может потребовать повторной генерации.

pdfcpu annotations list --json input.pdf
pdfcpu bookmarks export input.pdf bookmarks.json
pdfcpu bookmarks import input.pdf bookmarks.json output.pdf

Ссылки и аннотации зависят от координат страницы. После crop, resize, zoom или поворота нужно проверить кликабельные прямоугольники. Автоматическая трансформация не заменяет визуальный контроль сложных документов, созданных разными библиотеками. Для теста полезно открыть результат в просмотрщике, перейти по всем закладкам первого уровня, щёлкнуть несколько внутренних и внешних ссылок и убедиться, что всплывающие заметки остаются на своих местах.

Формы: просмотр, экспорт и заполнение

Команды form позволяют перечислять поля, экспортировать структуру и значения в JSON, заполнять форму из JSON и создавать несколько заполненных документов из набора данных. list показывает имена, типы и текущее состояние полей; JSON-вывод упрощает интеграцию. export формирует шаблон данных, который можно изменить без ручного поиска внутренних имён. fill применяет один набор значений к форме, а multifill создаёт серию файлов из таблицы или JSON-данных в зависимости от поддерживаемого формата входа.

Имена полей в PDF могут не совпадать с видимыми подписями. Два визуально одинаковых поля иногда имеют разные полные имена из-за иерархии AcroForm, а группа радиокнопок использует экспортные значения. Поэтому правильный процесс начинается с form list или export, а не с угадывания ключей. После заполнения нужно проверить кириллицу, перенос строк, размер шрифта и внешний вид в нескольких просмотрщиках. Поле может хранить значение, но выглядеть пустым, если поток внешнего вида не создан ожидаемым образом.

pdfcpu form list --json form.pdf
pdfcpu form export form.pdf form-data.json
pdfcpu form fill form.pdf form-data.json filled.pdf

Пользовательские шрифты позволяют заполнять поля символами, отсутствующими в базовых шрифтах. Шрифт сначала устанавливают через fonts install, затем указывают в данных или описании, если это поддерживает конкретная операция. Файлы с XFA требуют особого внимания: pdfcpu ориентирован на стандартные AcroForm и не является универсальным редактором динамических XFA-форм. Если форма открывается только в определённом просмотрщике и содержит XFA, её нужно тестировать отдельно или предварительно преобразовать в обычную форму.

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

Вложения и PDF-портфели

attachments управляет обычными встроенными файлами: list выводит список, add добавляет файл с необязательным описанием, remove удаляет выбранные вложения, extract сохраняет их в каталог. Вложение остаётся самостоятельным бинарным объектом внутри PDF и не становится видимой страницей. Это удобно для исходных таблиц, XML, изображений или приложений к отчёту, но получатель должен использовать просмотрщик, который показывает вложения.

portfolio работает с коллекцией файлов и дополнительной структурой портфеля. Не все просмотрщики одинаково отображают PDF-портфели, поэтому перед распространением нужно проверить целевую среду. Если требуется максимальная совместимость, надёжнее объединить представимые документы в страницы, а дополнительные материалы добавить как обычные attachments и перечислить их в тексте документа. Портфель подходит для управляемых процессов, где известен используемый просмотрщик.

pdfcpu attachments list package.pdf
pdfcpu attachments add package.pdf data.xlsx,"Исходная таблица"
pdfcpu attachments extract package.pdf attachments-out

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

Шрифты, кириллица и другие письменности

fonts list показывает базовые шрифты и установленные пользовательские гарнитуры. Базовые PDF-шрифты удобны для латиницы, потому что просмотрщики ожидают их наличие и файл не требует встраивания полного шрифта. Для кириллицы, греческого, арабского, CJK и других наборов символов обычно устанавливается TrueType-шрифт. fonts install копирует шрифт в каталог конфигурации, а fonts cheatsheet создаёт образец поддерживаемых символов, полезный для проверки покрытия.

При выборе шрифта важно учитывать лицензию на встраивание, наличие нужных начертаний и полноту Unicode. Один файл может содержать обычное начертание, но не жирное; подмена синтетическим жирным не всегда возможна. Для арабского и иврита используется параметр направления справа налево, а для CJK может указываться код письменности. Наличие глифов не гарантирует правильное формирование сложного письма, поэтому текстовый штамп и заполненную форму нужно проверять на реальных строках, а не только на латинском тесте.

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

Шифрование, пароли и разрешения

encrypt применяет стандартный обработчик безопасности PDF. По умолчанию используется AES с 256-битным ключом; также доступны другие длины и режим RC4, который считается устаревшим и не должен выбираться для новых документов. Пароль владельца обязателен: он открывает полный доступ и позволяет менять ограничения. Пользовательский пароль нужен для открытия документа и настоятельно рекомендуется, если содержимое действительно требуется защитить.

pdfcpu encrypt input.pdf protected.pdf --opw "owner-password" --upw "open-password"
pdfcpu decrypt protected.pdf plain.pdf --upw "open-password"

Разрешения определяют, что просмотрщик должен позволять пользователю после открытия с пользовательским паролем: печать, извлечение, аннотации, заполнение форм и изменения. permissions list показывает биты, permissions set принимает none, print, all либо точную маску. Эти ограничения зависят от соблюдения просмотрщиком спецификации и не заменяют контроль доступа к самому файлу. Получатель с паролем владельца получает полный доступ, а некоторые программы могут игнорировать отдельные ограничения.

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

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

Цифровые подписи и сертификаты

signatures validate проверяет целостность подписей, строит доступные цепочки сертификатов и может выполнять более полный анализ с данными отзыва. Опции all и full расширяют область и подробность проверки. Результат нужно трактовать осторожно: проверка криптографической целостности и цепочки не равна юридическому заключению, полной eIDAS-оценке или гарантии долгосрочной валидности. В отчёте важны время подписи, доверие к корню, доступность промежуточных сертификатов, сведения об отзыве и изменения после подписи.

certificates list показывает доверенные сертификаты, inspect анализирует файл сертификата, import добавляет совместимые сертификаты, reset возвращает хранилище к состоянию сборки. Обычная сборка может начинать с пустого каталога доверия, а вариант, собранный со специальным тегом, включает снимок европейских списков. Поэтому одинаковая команда на двух компьютерах способна дать разный результат доверия, если хранилища различаются. Для воспроизводимой проверки нужно управлять каталогом сертификатов как частью окружения.

pdfcpu certificates list
pdfcpu certificates inspect signer.pem
pdfcpu certificates import root.pem intermediate.p7c
pdfcpu signatures validate -af signed.pdf

Проверка отзыва может обращаться к CRL или OCSP и зависит от сети. Таймауты и предпочтительный механизм задаются в конфигурации; --offline запрещает обращения. В закрытом контуре отсутствие сети не означает, что подпись недействительна, но статус отзыва останется непроверенным без заранее загруженных данных. Результат автоматической проверки следует хранить вместе с версией конфигурации, хранилищем доверия и временем запуска.

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

Метаданные, ключевые слова и параметры просмотра

properties list, add и remove управляют пользовательскими свойствами документа. keywords выполняет аналогичные операции с ключевыми словами. Эти данные удобны для внутреннего поиска и интеграции, но не заменяют полноформатную систему метаданных. Удаление свойства из информационного словаря может сопровождаться обновлением связанного XMP; после очистки конфиденциальных метаданных следует проверить файл специализированным анализатором, потому что значения могут встречаться в других объектах, вложениях или содержимом страниц.

pagelayout задаёт расположение страниц в просмотрщике: одна страница, одна колонка, развороты и другие варианты. pagemode определяет, что показать при открытии, например панель закладок или миниатюр. viewerpref управляет предпочтениями интерфейса просмотрщика, такими как скрытие панели инструментов или способ печати. Это рекомендации внутри PDF, а не жёсткие команды: конкретный просмотрщик может игнорировать часть настроек или дать пользователю приоритет.

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

Конвейеры, стандартный ввод и пакетные сценарии

Многие команды принимают символ - вместо входного или выходного PDF. В позиции входа он означает чтение из стандартного ввода, в позиции выхода — запись в стандартный вывод. Это позволяет соединять операции без промежуточных файлов, получать PDF из другой программы и сразу передавать результат дальше. Не все вспомогательные форматы поддерживают поток: JSON, изображения, шрифты и CSV обычно остаются обычными файловыми аргументами. Перед построением конвейера нужно сверить матрицу поддержки конкретной команды.

cat input.pdf | pdfcpu optimize - - > optimized.pdf
cat input.pdf | pdfcpu encrypt --opw "$OPW" --upw "$UPW" - - > protected.pdf

При записи бинарного PDF в stdout нельзя смешивать его с диагностическим текстом. Обычные сообщения должны идти в stderr либо быть отключены флагом quiet; перенаправление нужно проверить на простой команде. Если оболочка или планировщик добавляет собственный текст в поток, PDF будет повреждён. Для отладки сначала используйте выходной файл, затем заменяйте его на - после подтверждения корректности.

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

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

Использование Go API

Те же операции доступны из Go-кода через пакеты API и модели конфигурации. Это подходит для серверов, очередей заданий и приложений, где запуск внешнего процесса неудобен. Функции уровня File принимают имена файлов, а многие низкоуровневые варианты работают с потоками чтения и записи. Конфигурация передаёт режим проверки, пароли, единицы и другие параметры. Ошибку нужно возвращать вызывающему коду, а не игнорировать: библиотека сообщает о повреждённых объектах, неверных паролях и невозможности записи.

package main

import (
    "log"
    "github.com/pdfcpu/pdfcpu/pkg/api"
)

func main() {
    if err := api.ValidateFile("input.pdf", nil); err != nil {
        log.Fatal(err)
    }
}

При интеграции важно зафиксировать версию модуля в go.mod и обновлять её после тестов на собственном наборе PDF. Формат сложен, поэтому регрессии чаще проявляются на редких файлах: сканах с необычными фильтрами, формах, повреждённых деревьях страниц, старом шифровании и документах с подписями. Набор тестов должен включать реальные обезличенные образцы и проверять не только отсутствие ошибки, но и число страниц, свойства, размер, изображения, формы и подписи.

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

Типовые ошибки и способы устранения

Команда не найдена

Если оболочка сообщает, что pdfcpu не найден, нужно проверить путь к исполняемому файлу и право на запуск. Запуск из текущей папки требует ./pdfcpu в Bash или .\pdfcpu.exe в PowerShell. После добавления каталога в PATH иногда нужно открыть новое окно терминала. На macOS файл, загруженный из сети, может потребовать разрешения в настройках безопасности; на Linux после распаковки может понадобиться chmod +x pdfcpu.

Файл уже существует

Сообщение о существующем выходе защищает от случайной перезаписи. Лучшее решение — выбрать новое имя или удалить устаревший результат после проверки. --force следует добавлять только там, где повторный запуск действительно должен заменять файл. В автоматическом процессе удобнее писать во временное имя и затем переименовывать, чем постоянно разрешать перезапись всех путей.

Please provide the correct password

Ошибка означает, что документ требует пользовательский или владельческий пароль. Для чтения обычно достаточно --upw, для изменения разрешений нужен --opw. Нужно убедиться, что оболочка не интерпретирует специальные символы пароля; секрет заключают в подходящие кавычки или передают через переменную. Пустой пароль и отсутствующий пароль — не всегда одно и то же состояние PDF.

Повреждённое дерево страниц или таблица ссылок

Ошибки page tree corrupted, xref или trailer указывают на структуру PDF. Сначала файл копируют заново и проверяют размер. Затем запускают validate -vv и пробуют открыть в доверенном просмотрщике. Если просмотрщик умеет пересохранить документ, новая копия часто получает исправленную таблицу ссылок. После восстановления нужно сравнить число страниц и содержимое, потому что автоматический ремонт может отбросить недоступные объекты.

Лимит ресурсов превышен

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

Штамп не виден

Фоновый watermark скрывается за полноразмерным изображением скана или непрозрачной заливкой. В этом случае используют stamp поверх содержимого и уменьшают opacity. Также нужно проверить pages, position, scale и цвет: светлый текст на белом фоне либо объект за пределами CropBox будет незаметен. Для PDF-штампа проверяют номер страницы источника и масштаб.

Кириллица отображается квадратами

Причина обычно в базовом шрифте без нужных глифов или в неверно установленном пользовательском шрифте. Нужно выбрать TrueType-гарнитуру с кириллицей, установить её через fonts install, проверить fonts list и указать точное имя. Затем создаётся короткий тест со всеми нужными символами. Если текст виден в одном просмотрщике и отсутствует в другом, следует проверить встраивание и внешний вид потока.

Практические рабочие процессы

Подготовка комплекта документов к отправке

Сначала каждый входной PDF проверяют validate и записывают число страниц через info. Затем файлы переименовывают с числовыми префиксами, чтобы порядок был однозначным, и объединяют merge. После этого импортируют или создают закладки, добавляют нижнюю нумерацию через stamp и при необходимости шифруют. Финальный файл снова проходит validate, открывается в просмотрщике, проверяются первые и последние страницы, переходы закладок и пароль. Такой порядок важен: подпись или шифрование выполняются после структурных изменений, а не до них.

Очистка скана и добавление отметки

Для скана сначала смотрят размеры страниц и поля, затем применяют crop к копии. Если каждая страница имеет одинаковые лишние поля, используется один набор margins; при разных полях потребуется предварительное разделение или другой инструмент. После обрезки добавляют полупрозрачный stamp, потому что watermark за изображением скана не виден. Затем выполняют optimize и сравнивают качество. OCR pdfcpu не выполняет, поэтому поиск по тексту появится только после отдельного распознавания.

Раздаточный материал из презентации

Исходную презентацию экспортируют в PDF, проверяют ориентацию и используют nup на четыре или шесть подходящих страниц в зависимости от поддерживаемого значения. Для четырёх слайдов выбирают A4L, добавляют умеренные поля и при необходимости отключают рамку. После генерации открывают несколько листов и убеждаются, что мелкий текст читаем. Если нужны заметки докладчика, их следует включить на этапе экспорта презентации; nup только перестраивает готовые страницы.

Персональные бланки

Шаблон формы проверяют form list и export, затем готовят тестовый JSON с кириллицей, датой, числом и длинной строкой. После fill проверяют внешний вид полей. Для серии используют multifill и безопасные имена файлов. Если документ должен быть неизменяемым, после заполнения его можно дополнительно преобразовать или растрировать внешним инструментом, потому что само заполнение не обязательно делает поля плоскими. Затем применяют шифрование или подпись согласно процессу.

Извлечение вложений из архива PDF

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

Ограничения, которые важно учитывать

Главное пользовательское ограничение — отсутствие графического редактора. Нельзя мышью перетащить страницу, выделить область обрезки или увидеть итог штампа до запуска. Точность достигается через копии, короткие тесты, просмотр результата и сохранённые команды. Для единичного ручного исправления это медленнее, чем GUI; для сотен одинаковых операций — наоборот, быстрее и воспроизводимее.

Программа не превращает страницу PDF в PNG или JPEG как готовый снимок. Извлечение изображений возвращает встроенные ресурсы, а не композицию текста, вектора и графики. Для рендеринга нужен отдельный движок. Также не следует ожидать полноценного визуального редактирования текста внутри существующей страницы, OCR сканов или удобной ручной разметки редактирования. Сильная сторона — структурные и пакетные операции, а не интерактивная верстка.

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

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

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

Программа	Лучше подходит для	Главное ограничение
pdfcpu	Пакетной структурной обработки PDF, сценариев и интеграции с Go	Нет визуального редактора и рендеринга страниц в изображения
PDF Commander	Ручного редактирования, перестановки страниц и работы через понятный интерфейс	Автоматизация сложных серверных конвейеров менее естественна
qpdf	Проверки структуры, шифрования и безопасных преобразований без изменения визуального содержимого	Меньше инструментов для штампов, форм и печатных раскладок
PDFtk Server	Простого объединения, разделения, вращения и заполнения форм из сценариев	Ограниченные современные операции с ресурсами и геометрией
MuPDF mutool	Рендеринга страниц, очистки, извлечения и низкоуровневой диагностики	Командный набор и модель параметров отличаются между задачами
Ghostscript	Растеризации, преобразования, печати и уменьшения размера через повторную генерацию	Может менять качество, шрифты и внутреннюю структуру документа

Для повторяемых операций над страницами, вложениями, формами, шифрованием и печатными раскладками разумно выбирать pdfcpu. PDF Commander удобнее, когда результат нужно видеть и править вручную. qpdf хорошо дополняет проверку и структурные преобразования, MuPDF закрывает отсутствующий рендеринг страниц, Ghostscript полезен для печатного конвейера и растрового пересоздания, а PDFtk остаётся понятным вариантом для базовых старых сценариев. На практике эти инструменты часто не заменяют, а дополняют друг друга.

Как проверить результат перед использованием

Минимальная проверка состоит из четырёх этапов. Сначала сравнивают код завершения и наличие непустого файла. Затем запускают validate на результате. После этого через info сверяют число страниц, шифрование, формы, вложения и подписи с ожидаемым состоянием. Наконец документ открывают в просмотрщике и проверяют визуально страницы, на которых выполнялось изменение. Для пакетной работы такую проверку автоматизируют, а визуальный контроль делают выборочно по заранее определённой доле файлов.

• При merge сверить порядок, общее число страниц и закладки.
• При split проверить число созданных файлов и границы групп.
• При crop убедиться, что важное содержимое не скрыто и конфиденциальные данные не считаются удалёнными.
• При stamp и watermark проверить слой, прозрачность, масштаб и диапазон страниц.
• При encrypt открыть файл пользовательским паролем и проверить permissions list.
• При form fill проверить кириллицу, переносы, радиокнопки и внешний вид полей.
• При signatures validate сохранить отчёт, время проверки и используемое хранилище доверия.

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

Итоговая схема работы

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

Начинать лучше с validate, info и простых операций на копии. Затем осваиваются выражения выбора страниц, явные выходные файлы и --help. После этого можно переходить к строкам описания для штампов и раскладок, конфигурации шрифтов, сертификатам и потокам stdin/stdout. Такой порядок уменьшает число труднообъяснимых ошибок: сначала контролируется структура документа, затем содержимое и только в конце безопасность и автоматизация.

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

Дополнительные рецепты для автоматизации

Для ежедневного входящего каталога удобно разделить процесс на четыре папки: incoming, working, done и failed. Сценарий атомарно переносит один файл в working, запускает validate, выполняет нужное преобразование во временный путь, проверяет результат и только затем перемещает его в done. При любой ошибке исходник отправляется в failed вместе с текстовым журналом. Такая схема предотвращает повторную обработку одного файла и не оставляет частично записанный PDF под финальным именем.

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

При создании штампа для разных форматов листа абсолютный размер может выглядеть слишком крупным на A5 и слишком маленьким на A3. Для смешанного пакета лучше использовать относительный scale либо разделить документы по размеру страницы. Позиция относительно CropBox также может различаться, если у части документов заданы нестандартные границы. boxes list помогает выявить такие файлы до нанесения отметки.

Для удаления пустых страниц pdfcpu не определяет визуальную пустоту автоматически. Сначала нужен внешний анализ содержимого или заранее известный диапазон, затем pages remove или trim. Нельзя считать страницу пустой только потому, что на ней нет текста: она может содержать белое изображение, невидимый слой OCR, аннотацию или форму. Автоматическое удаление требует отдельного правила и визуальной выборочной проверки.

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

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

При проверке подписей в изолированной сети нужно заранее определить, какие корневые и промежуточные сертификаты считаются доверенными и как обновляются данные отзыва. Запуск с --offline делает проверку воспроизводимой относительно локального хранилища, но не даёт свежий статус CRL или OCSP. Отчёт должен явно различать криптографически целую подпись, доверенную цепочку и непроверенный отзыв.

При импорте изображений с прозрачностью следует проверить фон и совместимость просмотрщиков. PNG с альфа-каналом может выглядеть иначе после размещения на цветном фоне, а JPEG не хранит прозрачность. TIFF может содержать несколько кадров, разную ориентацию и метаданные. После import нужно сверить число страниц, ориентацию каждого кадра и физический размер при печати.

При замене изображения объектным номером важно понимать, что номера не являются стабильными между пересохранениями. Сценарий должен выполнять images list непосредственно перед update для того же файла, а не хранить номер навсегда. После optimize, merge или другого преобразования объект может получить новый номер. Более устойчивый поиск строится по странице, идентификатору, размеру и контрольной сумме извлечённого ресурса.

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

Контроль сложных документов

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

Файлы с нестандартными цветовыми пространствами, ICC-профилями и прозрачностью следует тестировать на печати или в том просмотрщике, где они будут использоваться. Структурная операция может сохранить объекты корректно, но различия движков рендеринга проявятся в оттенках, наложениях и масках. Для полиграфии полезно сравнить несколько контрольных страниц до и после преобразования, проверить размеры MediaBox и TrimBox и не заменять управление цветом простой визуальной оценкой на одном мониторе.

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

Файлы с JavaScript, действиями открытия и внешними ссылками требуют отдельной политики. validate проверяет структуру в пределах поддерживаемых правил, но наличие допустимого объекта не означает, что его действие безопасно или желательно. Для входящих документов следует инвентаризировать действия и аннотации, использовать офлайн-режим и открывать результат в защищённом просмотрщике. Удаление метаданных не удаляет сценарии автоматически.

Если операция выполняется на сетевом диске, временные файлы и переименование могут вести себя иначе, чем на локальной файловой системе. Для надёжности рабочий файл копируют в локальный каталог, обрабатывают, валидируют и только затем передают обратно. Так снижается риск частичной записи при разрыве соединения. Контрольная сумма результата позволяет подтвердить, что переданная копия совпадает с проверенной.

В системах с очередью заданий полезно делать операции идемпотентными. Имя результата формируют из идентификатора задания и контрольной суммы входа, а перед запуском проверяют, не существует ли уже подтверждённый выход. --force не заменяет эту логику: он лишь разрешает перезапись. Идемпотентность предотвращает повторное шифрование, повторное добавление штампа и дублирование страниц после повторной доставки сообщения.

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

Проверка качества изображения не сводится к размеру файла. После import, nup, booklet, stamp или watermark нужно оценить читаемость мелкого текста, отсутствие ступенчатых линий, сохранение прозрачности и корректный поворот. Для печатных задач создают контрольный PDF с линейкой, тонкими линиями, цветными плашками и текстом разных размеров. Один такой образец быстро показывает влияние новой команды или изменённой конфигурации.