Quarto 1.10.18 Mac 导出 PDF 失败怎么办？2026 排查

先复制完整命令、终端输出、出错文档和项目配置。失败后不要立刻清理缓存、更新 TeX 或改 YAML；这些动作可能改变故障现场，让你失去前后对照依据。需要更详细诊断时，可按 Quarto 故障排查文档 使用 --log-level debug，并保留原始日志。

在项目副本或临时目录建立一份不含研究数据的最小 .qmd 文件，只保留简单标题和一段正文，然后运行：

quarto --version
quarto check
quarto render mini.qmd --to pdf --log-level debug

先确认本机实际报告的版本，再与 Quarto 官方发布页 对照；该页面列有 1.10.18。不要因为文章标题含有这个版本，就假定你的终端正在运行它。

Quarto 官方文档说明，PDF 输出可使用不同的 PDF 引擎，并提供 TeX 环境与故障排查建议。不同症状需要检查的环节不同，不能把所有失败都当成 LaTeX 故障。引擎与 PDF 配置可查阅 Quarto PDF 配置参考。

确认执行的是预期的 Quarto，而不是其他安装路径中的旧版本：

command -v quarto
quarto --version
pwd

然后检查输入文件是否在预期目录、项目根目录是否有 _quarto.yml，以及最终渲染命令是否指向正确的文件和格式。Quarto 项目会合并项目级、目录级与文档级配置；文档选项可以覆盖上层设置。因此，单看 .qmd 文件里的 YAML，未必能知道最终生效的参数。配置继承规则可参阅项目配置说明。

继续检查 YAML 缩进、模板、过滤器、引用文件和图片路径。不要一次改多个设置：每次只改一项，记录修改前后的错误行及实际渲染结果。如果模板或过滤器来自项目外部，先在副本中暂时移除，再确认错误是否消失。

如果命令报输入文件不存在、格式不支持，或解析阶段就失败，先停在这里。基础文档尚未通过渲染前，不要动 TeX 安装。

有代码块时，Quarto PDF 渲染至少涉及两个不同环节：先按文档设置执行代码，再由 PDF 工具链排版输出。判断哪一步先失败，可以在副本中尝试跳过执行：

quarto render report.qmd --to pdf --no-execute

如果跳过执行后仍在相近位置报错，检查日志是否进入 TeX 编译阶段。如果 PDF 能生成但代码结果是空的或过期的，重点检查执行环境、冻结输出和缓存；不要把旧结果误认为刚刚成功执行的结果。渲染命令支持控制代码执行，具体参数见 Quarto render 命令参考。

在 Python 项目中，quarto check jupyter 可用于检查 Jupyter 配置；Python 版本会受系统 PATH 或 QUARTO_PYTHON 影响。对于 R 或 Python 代码块，先用不含敏感数据的代表性代码复现，再分别验证解释器、内核和项目依赖。若执行阶段先失败，优先检查运行环境；若已经进入 TeX 编译阶段，再转查 PDF 工具链。

看到 lualatex、缺少宏包或 TeX 相关错误时，先从调试日志确认 Quarto 实际运行了什么命令。再检查配置中的 pdf-engine、引擎路径和当前工具链：

quarto list tools
command -v lualatex
lualatex --version

command -v 展示的是当前 shell 的查找结果；若 Quarto 配置指定了其他路径，或工具由 Quarto 管理，二者可能不同。Quarto 支持多个 PDF 引擎，默认值还可能随输出格式而不同，因此不能只凭电脑上安装过哪套 TeX，就断定渲染时使用了它。引擎选项和路径配置见 PDF 选项参考。

提醒：不要同时切换 PDF 引擎、更新 TeX、重装宏包。一次只动一套工具链，否则即使故障消失，也很难知道真正起作用的改动。

如果现有 TeX 与 Quarto 管理的 TinyTeX 都可能参与编译，先依据日志确认实际使用者，再决定是否进行对照测试。

Quarto 文档说明，它可以安装和管理 TinyTeX，也可通过 latex-tinytex: false 避免使用其管理的安装；自动安装缺失宏包的行为还取决于所用 TeX 发行版。要测试 TinyTeX，先在项目副本中验证同一最小文档，并保存切换前后的日志。相关细节见 PDF 引擎与 TinyTeX 说明。

字体或中文字符缺失

先确认 PDF 引擎、字体配置和字体实际名称。LuaLaTeX 支持 Unicode，但特定字符仍要求所选字体具备相应字形；可用 mainfont、CJKmainfont 等选项配置字体。字体能在你自己的 Mac 上找到，不代表隔离环境中也有相同字体。应在目标环境用只包含问题汉字、符号和标题的文档测试，不要未经验证就把某个字体名写进正式模板。

图表异常或文件丢失

核对资源路径是相对于文档目录还是项目执行目录，并确认图像文件格式与生成步骤能在副本中复现。若图表来自代码块，先确认代码是否运行、输出文件是否生成，再查 PDF 编译日志；路径错误和字体错误不是同一类问题。

文献没有更新或交叉引用不完整

检查 bibliography 路径、引用键和文献处理方式。Quarto 的引用处理可使用 Pandoc 的 citeproc，也可为 PDF 配置 natbib 或 biblatex；不同方式可能需要不同依赖和编译步骤。先看日志中缺失的是文献文件、引用键还是后端工具，再做对应处理。可参阅引用与参考文献说明。

Quarto 在 Mac 上出现 LaTeX 错误，先查哪一项？
先看调试日志中最后一个失败命令和引擎路径，再用最小文档渲染。最小文档失败，优先检查 PDF 引擎和 TeX；它通过而原项目失败，则回查模板、字体、引用或图表依赖。不要先重装 Quarto，也不要仅凭错误提示中的一个宏包名称就批量安装依赖。

中文字体或字形缺失，换成 XeLaTeX 就能解决吗？
不一定。更换引擎不能保证目标环境已安装所需字体，也不能保证字体覆盖文档中的全部字符。先核对字体名称与字符覆盖，再用少量代表性汉字和符号复测；若最小样例成功，继续检查项目模板是否覆盖字体配置，以及最终 PDF 中的字体和页面效果。

怎么确认找不到 lualatex 是路径问题还是引擎没安装？
对照 Quarto 调试日志、项目中的 pdf-engine 设置、quarto list tools 和 command -v lualatex。这几项回答的问题不同：前两者帮助确认 Quarto 的实际配置与调用，后两者用于查看 Quarto 管理工具和当前 shell 的查找结果。仍无法确认时，先停止改动环境，保留命令和日志。

R 或 Python 代码执行失败，怎样判断不是 PDF 编译问题？
在项目副本中跳过代码执行并再次渲染，同时查看错误是否发生在执行阶段或 TeX 阶段。跳过执行仍报 TeX 错误，继续查引擎；跳过后通过，但正常执行失败，就单独检查 R 环境、Python 解释器、Jupyter 内核和依赖。两种故障也可能同时存在，需分别记录。

最小样例通过，只能说明基础渲染路径可用，不代表论文的研究结果正确，也不代表格式已经满足投稿或学校要求。将原项目复制到隔离目录，逐类恢复组件：先配置与模板，再代码执行，然后字体、图表和文献。每加回一类就重新渲染；出现故障时回退到上一个通过状态。

• ✅ 确认版本与入口：记录 quarto --version、工作目录、输入文件和输出格式。
• ✅ 确认执行结果：复核代码块确实重新运行；检查结果是否来自当前环境，而非缓存或冻结输出。
• ✅ 确认文献与资源：检查引用、交叉引用、图表文件和项目相对路径。
• ✅ 确认 PDF 页面：抽查页面完整性、中文和符号字形、图表显示及参考文献格式。
• ✅ 保存复现条件：归档渲染命令、环境信息和错误日志；项目含敏感数据时，改用脱敏样例。
• ⚠️ 触发停止条件：故障尚未缩小到单一组件时，不继续改原项目；无法在本机稳定复现时，转到隔离环境验证同一份脱敏项目。

如果你的 Mac 环境反复失败，先比较“继续修当前工具链”和“隔离环境复测”的代价。前者可能受到多份 Quarto 或 TeX 安装、共享配置及项目依赖的干扰；后者能帮助判断故障是否随项目迁移，但不能替你验证科研结果或完成论文格式验收。若课题确实依赖 macOS，可先查看 CALMVPS 的使用方案与费用信息，再用脱敏项目确认隔离环境是否适合你的渲染流程；确认匹配后，再了解按周期使用 macOS 环境的方式。如果需要长期稳定的本地重负载处理，或必须连接实验室物理设备，则先评估自有 Mac 或实验室现有设备是否更合适。