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

Рабочее окно здесь фактически заменяет терминал: пользователь вводит имя входного файла, набор параметров и путь к результату, а программа сообщает предупреждения, ошибки и сведения о созданном документе. Базовая схема выглядит как qpdf вход.pdf параметры выход.pdf. Для операций, которые только исследуют файл, выходной PDF не нужен; для преобразований он обязателен. Такое разделение быстро становится привычным: сначала документ проверяют или запрашивают его свойства, затем формируют новую копию и в конце снова запускают проверку.

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

Как устроена работа с командами QPDF

Начинать удобнее с интерактивной справки. Команда qpdf --help показывает не сплошную стену параметров, а перечень тематических групп: выбор страниц, шифрование, вложения, инспекция, JSON, преобразования, наложение и общие настройки. Затем можно запросить отдельную тему, например qpdf --help=page-selection, или конкретный ключ. Полная справка полезна для поиска по имени параметра, однако в ежедневной работе тематический вывод быстрее подсказывает правильный порядок аргументов и обязательный завершающий разделитель --.

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

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

Коды завершения и предупреждения

Автоматизация строится не только на тексте в терминале, но и на коде завершения. Нулевое значение означает успешную операцию без предупреждений. Код 2 сообщает об ошибке, а 3 — о результате, созданном с предупреждениями. Код 1 программа намеренно не использует, чтобы его можно было отличить от ситуации, когда оболочка вообще не смогла запустить исполняемый файл. Проверки --is-encrypted и --requires-password имеют специальные коды, поэтому в скрипте нельзя трактовать любое ненулевое значение как поломку документа без учёта выбранной команды.

Предупреждение не всегда требует выбросить результат. QPDF умеет восстанавливать таблицу ссылок, игнорировать отдельные повреждённые записи и продолжать запись. Но сообщение operation succeeded with warnings означает именно компромисс: файл сформирован, однако часть исходной структуры была подозрительной. Надёжный процесс сохраняет журнал, проверяет выходной PDF отдельным запуском --check и при важных документах сравнивает страницы в просмотрщике. Подавление предупреждений допустимо только после того, как причина понятна и повторяется на контролируемом наборе файлов.

Проверка целостности и первичная диагностика

Команда qpdf --check документ.pdf проверяет общую синтаксическую целостность, декодирует потоки, которые может обработать, анализирует шифрование и сообщает, является ли файл линеаризованным. Она обнаруживает множество повреждений таблиц перекрёстных ссылок, неверные длины потоков, потерянные объекты и проблемы в служебных деревьях. Это не полный валидатор стандарта PDF: отсутствие сообщений не доказывает корректность графических операторов, шрифтов, логической разметки или соответствие PDF/A. Зато для пакетной сортировки входящих документов проверка быстрая и хорошо подходит как первый фильтр.

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

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

Быстрые запросы без создания нового файла

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

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

Объединение PDF и выбор страниц

Выбор страниц задаётся после --pages. Для сборки документа с нуля вместо основного входного файла указывают --empty, затем перечисляют файлы и диапазоны, завершают список двойным дефисом и называют результат. Например, команда qpdf --empty --pages cover.pdf 1 report.pdf 1-z appendix.pdf 2-5 -- combined.pdf берёт обложку, весь отчёт и четыре страницы приложения. Порядок в команде становится порядком в готовом PDF; пересортировать исходники заранее не требуется.

Диапазоны поддерживают прямой и обратный порядок. Запись 3-7 выбирает страницы с третьей по седьмую, 7-3 разворачивает тот же фрагмент, 1-z означает весь документ, а z-1 — весь документ с конца к началу. Обозначение r1 ссылается на последнюю страницу, r2 — на предпоследнюю. После набора можно добавить :odd или :even; фильтр применяется к позициям в уже сформированном наборе, а не всегда к исходным номерам. Исключение страниц задаётся диапазонами с префиксом x.

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

Перемежение документов

Ключ --collate не просто соединяет файлы, а берёт страницы по очереди из нескольких источников. Это удобно для сканов, где нечётные страницы лежат в одном PDF, а чётные — в другом, либо для параллельных языковых версий. Без числа берётся по одной странице из каждого источника. Значение --collate=2 переключает файлы блоками по две страницы, а список вроде --collate=2,1,3 задаёт отдельный размер блока для каждого набора. Когда страницы одного файла заканчиваются, остальные продолжают участвовать.

Перед перемежением важно правильно развернуть один из сканов. Для стопки, отсканированной с обратной стороны, часто нужен диапазон z-1. Сначала лучше сформировать пробный PDF из шести–восьми страниц и проверить последовательность, потому что ошибка в направлении создаёт формально исправный, но логически перепутанный документ. Автоматическая проверка структуры такого дефекта не увидит: все объекты и ссылки будут корректны.

Разделение на отдельные файлы

--split-pages записывает каждую страницу в отдельный PDF, а числовое значение группирует страницы. Команда qpdf report.pdf --split-pages=10 section.pdf создаёт части по десять страниц и последнюю неполную часть. Если в шаблоне имени есть %d, на его месте появляется диапазон с ведущими нулями; без шаблона номера добавляются к базовому имени. Это подходит для передачи глав по отдельности, разбиения огромного скана и параллельной обработки частей.

Быстрый режим разделения создаёт для каждой части новый документ и копирует страницы, поэтому некоторые сведения уровня всего файла не сохраняются. Закладки, статьи, общая логическая структура и другие элементы, которые не принадлежат конкретной странице, могут исчезнуть. Если такие данные критичны, каждую часть формируют отдельной командой через --pages, используя исходный документ как основной. Это медленнее, зато позволяет контролировать контекст и затем проверить сохранность нужных словарей.

После разделения полезно сверить суммарное число страниц и отсутствие пустых частей. В shell это делается циклом с --show-npages; в PowerShell можно собрать результаты в таблицу. Размер файла не является надёжным показателем: одна страница со сканом может весить больше десятка текстовых страниц. Для юридических комплектов также проверяют порядок, поскольку сортировка имён без ведущих нулей способна поставить часть 10 перед частью 2.

Поворот, нормализация поворота и геометрия страниц

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

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

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

Наложение штампов, водяных знаков и подложек

--overlay размещает страницы другого PDF поверх результата, а --underlay — под исходным содержимым. Это не растровая склейка: страницы добавляются как PDF-содержимое, поэтому векторные линии и текст штампа сохраняют качество. По умолчанию первая страница файла-наложения применяется к первой странице результата, вторая ко второй и так далее, пока один из наборов не закончится. Параметры --to, --from и --repeat управляют страницами назначения, начальным диапазоном и повторяемым шаблоном.

Чтобы повторить один водяной знак на всех листах, указывают пустой начальный диапазон и повтор первой страницы: --from= --repeat=1. Двухстраничный колонтитул для нечётных и чётных страниц задаётся повтором 1,2. Несколько подложек и наложений можно складывать; порядок параметров определяет порядок слоёв. Сначала идут подложки, затем исходная страница, затем наложения. Если штамп имеет непрозрачный белый фон, он действительно закроет исходный текст — QPDF не делает фон прозрачным автоматически.

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

Линеаризация для последовательной загрузки

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

--check-linearization проверяет согласованность подсказок, а --show-linearization выводит их подробности. Обычная команда --check также сообщает, линеаризован ли файл, но специализированная проверка полезнее после передачи через систему, которая могла дописать данные или изменить метаданные. Любое последующее сохранение другим редактором способно нарушить оптимизированный порядок, поэтому линеаризацию выполняют ближе к концу конвейера.

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

Пароли, шифрование и разрешения PDF

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

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

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

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

Сжатие и уменьшение размера файла

QPDF оптимизирует структуру без полноценного рендеринга страниц. --object-streams=generate помещает подходящие объекты в сжатые объектные потоки, --recompress-flate повторно сжимает потоки Flate, а уровень сжатия регулирует усилие алгоритма. Это может уменьшить PDF с большим числом мелких объектов, форм и векторной графики. Режим preserve сохраняет исходную организацию, а disable записывает обычные несжатые объекты, что полезно для совместимости со старыми программами и ручного анализа.

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

Удаление неиспользуемых объектов происходит при обычной переписи, поэтому файл иногда уменьшается даже без специальных ключей. Но размер способен и вырасти: отключение объектных потоков, распаковка потоков, QDF-режим или линеаризация добавляют служебные данные. Сравнивать следует не только мегабайты, но и визуальное качество, скорость открытия и совместимость. Для радикального уменьшения сканов обычно нужен инструмент, который меняет разрешение и цветность; QPDF не анализирует, сколько точек на дюйм достаточно для чтения.

Метаданные, метки страниц и логическая структура

--remove-info очищает словарь информации документа, сохраняя дату изменения, --remove-metadata исключает каталог XMP-метаданных, а --remove-page-labels убирает пользовательские обозначения страниц. Эти источники независимы: название и автор могут присутствовать одновременно в старом словаре Info и в XMP. Поэтому удаление только одного блока не гарантирует очистку всех описательных полей. Вложенные файлы, аннотации, JavaScript и видимый текст также не относятся к метаданным и требуют отдельных действий.

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

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

Формы и аннотации

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

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

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

Работа с вложениями

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

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

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

QDF: подготовка PDF для ручного исследования

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

После ручного изменения длины потоков и смещения объектов становятся неверными. Утилита fix-qdf, поставляемая вместе с QPDF, пересчитывает служебные значения. Типичный процесс: создать QDF-копию, сохранить оригинал, найти нужный объект, внести минимальное изменение, пропустить файл через fix-qdf и затем обычным QPDF сформировать чистый результат. Если требуется найти объект проще, QDF совмещают с --object-streams=disable.

QDF удобен для обучения синтаксису PDF, исправления одного словаря и диагностики генератора документов. Он неудобен для редактирования текста на странице: строка может быть разбита на глифы, закодирована пользовательским шрифтом и позиционироваться десятками операторов. Изменение одного символа способно нарушить метрики, переносы и подмножество шрифта. Для содержательного редактирования нужен инструмент более высокого уровня.

JSON-представление структуры

--json выводит однозначное представление объектов PDF и отдельные сводные разделы. Формат имеет версию, указанную в поле version, поэтому скрипт может проверять совместимость. Без имени результата JSON идёт в стандартный вывод; при необходимости его записывают в файл. Повторяемый --json-key ограничивает верхнеуровневые разделы, а --json-object выбирает конкретные объекты или трейлер. Это снижает объём при анализе больших документов.

Потоки по умолчанию не включаются либо управляются отдельным режимом. Их можно встроить в JSON в Base64 или сохранить рядом отдельными файлами с заданным префиксом. Встроенный вариант удобен для единого переносимого артефакта, но резко увеличивает размер и расход памяти. Раздельный вариант проще для двоичных сравнений и внешних декодеров. Уровень декодирования следует выбирать осознанно: не каждый фильтр можно безопасно развернуть, а сырые данные важны при расследовании повреждения.

JSON допускает обратное преобразование и обновление PDF, что открывает путь к автоматическому редактированию объектов из любого языка с поддержкой JSON. Но ответственность за корректные ссылки, типы объектов, словари ресурсов и содержимое потоков остаётся на авторе скрипта. Формально корректный JSON может описывать визуально неправильный документ. После импорта всегда выполняют --check, открывают контрольные страницы и сравнивают важные поля.

Восстановление повреждённых документов

При чтении QPDF сверяет таблицу перекрёстных ссылок с фактическими объектами и при необходимости сканирует файл, пытаясь восстановить расположение объектов. Обычная команда переписи уже запускает эту логику: qpdf broken.pdf repaired.pdf. Успешный результат часто избавляет от предупреждений incorrect startxref pointer, неверных смещений и некоторых ошибок длины потока. Однако программа не дорисовывает пропавшие изображения и не восстанавливает байты, которых физически нет.

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

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

Безопасная замена исходного файла

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

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

Если появляется permission denied, проверяют не только права на сам PDF, но и возможность создать временный файл в каталоге. Документ может быть открыт программой просмотра с блокировкой, каталог — доступен только для чтения, а антивирус — удерживать только что созданный результат. Запуск от администратора маскирует причину и не является первым решением; лучше выбрать доступный рабочий каталог и затем перенести проверенный файл.

Пакетная обработка в shell и PowerShell

Для папки с документами цикл должен формировать уникальное имя результата и корректно обрабатывать пробелы. В shell используют нулевые разделители или аккуратные кавычки, в PowerShell — объекты файлов, а не конкатенацию строк. Перед запуском на всей коллекции создают тестовый каталог с зашифрованным, повреждённым, линеаризованным и обычным PDF. Скрипт обязан различать успешный код, предупреждение и ошибку, иначе один проблемный файл останется незамеченным среди сотен.

mkdir -p checked
for f in *.pdf; do
  out="checked/${f%.pdf}-checked.pdf"
  if qpdf "$f" "$out"; then
    qpdf --check "$out" || printf '%s
' "Проверка не пройдена: $out" >&2
  else
    printf '%s
' "Не обработан: $f" >&2
  fi
done

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

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

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

QPDF не отображает страницу и не оценивает, правильно ли выглядят шрифты, прозрачность, цветовые профили и сложные эффекты. Структурно исправный файл может иметь пустую страницу из-за неверного потока рисования. Для визуального контроля нужен рендерер. По той же причине программа не конвертирует PDF в DOCX, изображения или текст, не распознаёт сканы и не выполняет OCR.

Редактирование макета не относится к её высокоуровневым возможностям. Нельзя щёлкнуть по заголовку, изменить шрифт, перетащить картинку или автоматически переформатировать таблицу. Через QDF, JSON или библиотеку возможно изменить низкоуровневые объекты, но это требует знания спецификации PDF и не даёт гарантий удобного результата. Пользователю, которому нужно исправить опечатку или собрать документ мышью, практичнее графический редактор.

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

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

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

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

Оболочка не видит исполняемый файл, если его каталог отсутствует в PATH или окно терминала было открыто до изменения переменной среды. Сначала запускают QPDF по полному пути и проверяют --version, затем добавляют каталог и открывают новый терминал. В Windows не стоит полагаться на текущую папку: PowerShell может требовать явный префикс .\. В Linux и macOS проверяют, какой файл найден командой оболочки, чтобы не использовать неожиданную старую копию.

Usage error и неверный порядок аргументов

Сообщение о синтаксисе часто появляется из-за пропущенного выходного файла, незакрытой секции --pages, --overlay или --encrypt. Двойной дефис завершает параметры соответствующей секции; он не всегда взаимозаменяем с концом всей команды. Исправление начинают с минимальной команды на двух тестовых файлах, затем добавляют диапазоны и опции по одной. Тематическая справка показывает точную форму выбранного ключа.

Неверный пароль

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

Операция завершилась с предупреждениями

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

После разделения исчезли закладки

Быстрый --split-pages создаёт новые документы из отдельных страниц и не переносит все данные уровня файла. Для частей с закладками используют отдельные команды --pages, выбирая диапазон из исходника. Затем проверяют назначения закладок: те, что ссылались за пределы части, потребуют удаления или правки специализированным инструментом.

Водяной знак смещён или закрывает текст

Причина обычно в различии размеров страниц, повороте или непрозрачном фоне шаблона. Сначала сравнивают MediaBox и CropBox исходника и штампа, затем готовят шаблон соответствующего размера. Если знак должен быть под текстом, применяют --underlay; если поверх — обеспечивают прозрачность при создании самого PDF-шаблона. QPDF не угадывает желаемое масштабирование.

Файл стал больше после оптимизации

Некоторые параметры повышают читаемость структуры ценой размера. QDF, распаковка потоков и отключение объектных потоков почти неизбежно увеличивают документ. Повторное JPEG-сжатие уже компактных изображений может не дать выигрыша. Сравнивают отдельные стратегии на копии, не соединяют диагностические и производственные ключи и используют --object-streams=generate только там, где совместимость это допускает.

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

Программа	Лучше подходит для	Главное ограничение
QPDF	Скриптовой перестройки PDF, выбора страниц, шифрования, проверки структуры, QDF и JSON	Не рендерит страницы и не даёт визуального редактирования
PDF Commander	Редактирования текста и страниц в графическом интерфейсе, сборки документов без командной строки	Не предназначен для низкоуровневого анализа объектов и серверных CLI-конвейеров
pdfcpu	Пакетных операций, валидации, оптимизации и управления PDF одной утилитой на Go	Строгая совместимость и результат отдельных операций зависят от особенностей конкретного PDF
Ghostscript	Рендеринга, преобразования PostScript и PDF, пересоздания страниц и сильного уменьшения сканов	Пересоздание может изменить графику, шрифты, ссылки и интерактивные элементы
PDFtk	Простых серверных задач: объединение, разделение, заполнение форм и работа с фоновыми страницами	Меньше инструментов для детального исследования современной структуры PDF
MuPDF mutool	Рендеринга, очистки, извлечения ресурсов и диагностики с компактным набором команд	Синтаксис и модель операций отличаются между подкомандами и требуют отдельного освоения
Apache PDFBox	Java-приложений, программного извлечения текста, создания и модификации PDF	Для многих задач требуется JVM и код либо специализированная подкоманда

QPDF выбирают, когда важно сохранить визуальное содержимое и управлять внутренним устройством файла воспроизводимыми командами. PDF Commander удобнее для ручной правки и пользователей, которым нужен предварительный просмотр. Ghostscript полезнее при обязательном рендеринге или глубоком пересоздании, mutool — когда вместе со структурными командами нужна визуализация, pdfcpu — для близкого по духу пакетного набора, а PDFBox — для интеграции в Java и операций более высокого уровня. На сложном конвейере инструменты не исключают друг друга: QPDF проверяет и собирает, рендерер контролирует внешний вид, а редактор исправляет содержимое.

Практические сценарии

Подготовка отчёта к публикации

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

Сборка комплекта из разных источников

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

Проверка входящих PDF на сервере

Процесс ограничивает размер и время, сохраняет исходный хэш, запускает --check, определяет шифрование и число страниц. Зашифрованные файлы направляются в отдельную ветку, повреждённые — в карантин. Для допустимых документов создаётся нормализованная копия без замены оригинала. QPDF не заменяет антивирус и песочницу, поэтому вложения и активное содержимое анализируются другими средствами.

Расследование неожиданного поведения формы

Сначала получают JSON разделов формы и страниц, затем создают QDF-копию с отключёнными объектными потоками. Сравнивают словарь AcroForm, виджет-аннотацию и appearance-поток. Если значения расходятся, становится понятно, почему один просмотрщик показывает старый текст, а другой новый. Исправление тестируют на копии; выравнивание аннотаций выполняют только после подтверждения правильного внешнего вида.

Разбор книги на главы и обратная сборка

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

Как получить предсказуемый результат

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

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

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

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

Дополнительные параметры для точной настройки

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

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

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

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

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

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

Контроль после преобразования

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

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

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

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

Чтение низкоуровневого вывода

Ссылка вида 12 0 R означает косвенный объект номер 12 поколения 0. Трейлер указывает корневой каталог и размер пространства объектов, дерево Pages связывает страницы, а массив Contents перечисляет потоки рисования. Понимание этих обозначений помогает сопоставить вывод --show-pages, JSON и QDF. Номер объекта не является номером страницы и может измениться после переписи.

Перекрёстные ссылки бывают классической таблицей или потоком xref. Объектные потоки дополнительно упаковывают несколько объектов внутрь одного потока. Поэтому поиск строки по сырым байтам не всегда находит нужный словарь. Режим QDF с отключёнными объектными потоками делает структуру наблюдаемой, а JSON предоставляет устойчивый синтаксис для программы.

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

Страница наследует часть свойств от узлов дерева Pages. Если смотреть только словарь самой страницы, можно не увидеть размер, поворот или ресурсы, которые пришли от родителя. Высокоуровневые команды QPDF учитывают наследование при копировании. При ручном редактировании JSON или QDF эту особенность нельзя игнорировать, иначе новая страница потеряет нужные параметры.

Инкрементальные обновления дописывают новые объекты в конец PDF, оставляя старые версии внутри файла. Обычная перепись QPDF собирает актуальное состояние и удаляет недостижимые объекты, из-за чего прежние значения метаданных обычно исчезают из результата. Это полезно для очистки, но меняет байты и уничтожает возможность исследовать историю обновлений. Для экспертизы сначала сохраняют исходник.

Job JSON для воспроизводимых заданий

Помимо JSON-представления самого PDF, QPDF поддерживает файл задания QPDFJob. Это другой формат: он описывает команду, её входы, выход и параметры, а не объекты документа. Файл задания передают через --job-json-file. Такой подход удобен, когда оболочка плохо справляется с длинными аргументами, диапазонами, несколькими паролями и повторяющимися секциями. Конфигурацию можно сформировать приложением, проверить как обычный JSON и хранить вместе с журналом обработки.

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

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

Job-интерфейс особенно полезен разработчикам, которые вызывают библиотеку QPDF: одна и та же модель задания доступна из командной утилиты и программного API. Сначала сценарий отлаживают в терминале, затем переносят в приложение без ручного повторения всей логики параметров. Это снижает риск расхождения между тестовой командой и производственным кодом, но не отменяет проверку результата.

Стандартный вывод, каналы и большие данные

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

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

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

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

Сохранение совместимости с просмотрщиками

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

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

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

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

Управление датами и идентификаторами

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

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

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

Страницы, ресурсы и внутренние ссылки

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

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

Закладки находятся в дереве Outline и относятся к документу целиком. Простое копирование страницы не гарантирует перенос подходящей ветви дерева. При разделении по главам это особенно заметно: страницы присутствуют, а панель содержания пуста. Для сохранения навигации нужен процесс, который копирует или заново строит соответствующие закладки. QPDF предоставляет низкоуровневые средства через JSON и библиотеку, но не интерактивный редактор дерева.

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

Работа с потоками содержимого

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

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

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

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

Ограничение активного содержимого

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

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

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

Рекомендованный порядок сложного конвейера

1. Сохранить исходный файл и вычислить его хэш.
2. Проверить структуру, шифрование, число страниц и вложения.
3. Расшифровать рабочую копию при наличии законного пароля.
4. Выполнить выбор, объединение, поворот и наложения.
5. Обработать формы, метаданные, структуру и вложения по политике.
6. Оптимизировать потоки и изображения на проверенных настройках.
7. Линеаризовать результат, если это нужно каналу доставки.
8. Снова проверить структуру и провести визуальный контроль.
9. Зашифровать или подписать финальный документ в правильном порядке.
10. Сохранить журнал, хэш результата и сведения о предупреждениях.

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

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

Итоговый выбор сценария

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

Осваивать программу лучше от простого к сложному: проверка, число страниц, копирование одного диапазона, объединение двух файлов, затем шифрование и наложения. QDF и JSON нужны, когда стандартных операций уже недостаточно и есть понимание объектов PDF. Такой порядок снижает риск применить низкоуровневый инструмент к задаче, которую проще и безопаснее решить на уровне страницы или визуального редактора.

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