Quarto 1.10.18: что делать, если не удаётся экспортировать PDF на Mac? Диагностика 2026

Не переустанавливайте Quarto первым делом: сохраните полный журнал ошибки и проверьте минимальный документ, а затем последовательно исключайте разбор документа, выполнение кода, PDF-движок и шрифты. Такой порядок подходит, если установленная у вас версия действительно соответствует Quarto 1.10.18 в официальном списке выпусков; наличие этой версии в списке само по себе не гарантирует совместимость конкретного проекта, macOS и локальных зависимостей.

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

Сначала определите, что именно произошло. «Файл PDF не появился», «команда завершилась ошибкой» и «PDF появился, но в нём нет части результата» — разные симптомы. Не удаляйте кэш, не меняйте сразу несколько настроек и не устанавливайте новый пакет до сохранения исходных свидетельств. Иначе вы можете потерять причину сбоя и получить другое состояние проекта, которое уже нельзя сопоставить с первоначальным.

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

quarto --version
quarto check
quarto render report.qmd --to pdf

Команды quarto render и формат --to pdf описаны в справочнике Quarto по запуску рендеринга. Не делайте вывод по одному сообщению в конце лога: полезны первая ошибка, имя файла или пакета рядом с ней и этап, на котором перестал обновляться вывод.

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

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

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

Для базового сравнения подготовьте новый документ без научных данных и без исполняемых блоков. Оставьте простой YAML и короткий текст, затем попробуйте получить PDF тем же способом. Если минимальный документ тоже падает, сосредоточьтесь на пути к Quarto, конфигурации рендеринга и PDF-инструментах. Если он проходит, а копия проекта — нет, причина вероятнее связана с документом или его зависимостями. Это не доказывает, что содержимое проекта научно корректно; проверка подтверждает только то, что сборка завершилась.

Ведите небольшой журнал изменений: что поменяли, какое сообщение исчезло и появилась ли новая ошибка. Изменяйте один фактор за раз. Например, сначала уберите фильтр, верните его и только затем проверьте шаблон. Если несколько параметров меняются одновременно, успешная сборка не покажет, какое именно изменение помогло.

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

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

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

Отсутствующий график или таблица не обязательно означают неисправность LaTeX. Сначала сопоставьте место сбоя с этапом выполнения кода. Если журнал указывает на R, Python или ядро, повторите соответствующий фрагмент в том же проектном окружении без сборки PDF. Если блок работает отдельно, а проблема появляется позже, переходите к проверке рендеринга и включения результата в документ.

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

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

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

При сообщении о недоступном lualatex или другом PDF-движке сначала выясните фактическую команду и путь, которые использует Quarto. Не исходите из предположения, что сборка обязательно обращается к системной версии TeX или к тому же исполняемому файлу, который запускается из вашей оболочки. Проверяйте полный журнал и результат диагностики, а также сверяйте выбранный pdf-engine с документацией Quarto о PDF-движках и TinyTeX.

С чего начинать проверку Mac LaTeX ошибки?

Начните с первой конкретной ошибки в журнале: отсутствующего исполняемого файла, пакета, некорректной команды или ошибки самого документа. Если сообщение говорит о недоступном движке, проверьте его путь и доступность из той же оболочки, где запускаете Quarto. Если назван пакет, выясните, относится ли он к используемой TeX-установке и есть ли в логе попытка его установить. Отсутствие результата установки — отдельный симптом, его нельзя автоматически трактовать как ошибку YAML.

Посмотрите настройку pdf-engine в документе или конфигурации проекта. Quarto документирует несколько вариантов движка; выбор зависит от параметров проекта и требований к документу, а не от общего правила «на Mac всегда нужен один и тот же». Сверьте настройку с разделом PDF engines и повторите тест на минимальном документе. Не переключайте движок, TeX-установку и шрифты одновременно: при успешной сборке вы не узнаете, какая перемена была необходима.

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

Quarto TinyTeX — вариант, который стоит проверять, когда журнал указывает на TeX-зависимость и вы хотите изолировать её от другой установки. Это не универсальное исправление ошибки документа, неработающего кода или отсутствующего шрифта. Если минимальный пример компилируется, а основной проект нет, возвращайтесь к компонентам проекта, а не продолжайте без разбора перестраивать TeX.

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

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

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

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

• [ ] Скопируйте исходный проект и уберите из копии закрытые данные.
• [ ] Зафиксируйте исходный журнал, версию Quarto, рабочий каталог и команду.
• [ ] Проверьте YAML и основное содержимое без фильтров и пользовательского шаблона.
• [ ] Верните один фильтр или шаблон и повторите рендеринг.
• [ ] Отдельно добавьте исполнение R или Python и подтвердите обновление результатов.
• [ ] Верните рисунки и проверьте пути к ресурсам.
• [ ] Подключите библиографию и проверьте цитаты и перекрёстные ссылки.
• [ ] Сравните готовый PDF с требованиями к работе: страницы, шрифты, рисунки, цитирование и результаты анализа.

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

Условие выбора следующего действия

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

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

Локальная машина остаётся удобнее для постоянной интенсивной работы и задач, которым нужны физические интерфейсы. Удалённая среда не устраняет ошибки проекта, требует сетевого подключения и добавляет шаги передачи файлов и управления доступом. Но если сейчас у вас нет подходящего Mac, покупка отдельной машины для разовой диагностики может быть неоправданной, а нестабильное локальное окружение затрудняет воспроизведение. В этом случае аренда Mac от CALMVPS может дать отдельную macOS-среду для проверки рендеринга — при условии, что вы используете только разрешённую обезличенную копию.

Начните с сохранения журнала и минимального примера. Если понадобится проверить тот же процесс в изолированной macOS-среде, изучите варианты доступа к удалённому Mac от CALMVPS и до переноса проекта проверьте ограничения по данным, доступу и требованиям вашей лаборатории.