Quarto 1.10.18 Mac 匯出 PDF 失敗怎麼辦？2026 排查

截至任務書所列的核對日，Quarto 官方發布頁列有 1.10.18。這只確認版本資訊，不能證明特定 macOS、字型或科研專案一定相容；請先用 quarto --version 核對實際執行的版本，再保存失敗時的完整命令與終端輸出。官方發布頁

先分清故障型態。完全沒有 PDF 產生，通常要從文件解析、程式執行或編譯錯誤找線索；命令報錯但有部分產物，要查看日誌在哪個階段停止；PDF 已產生但內容不完整，則要檢查字型、圖表、引用與舊的快取輸出。這三種情況不應用同一個「重裝」動作處理。

先保留以下證據，再改環境：

• [ ] 複製原始 .qmd、專案設定與完整錯誤輸出；另存一份失敗 PDF 或部分產物。
• [ ] 記下執行命令、目前工作目錄，以及 quarto --version 的結果。
• [ ] 保留 quarto check 的診斷輸出；若錯誤只在特定文件出現，也保存該文件副本。
• [ ] 用不含敏感研究資料的最小文件測試基本 PDF 渲染。
• [ ] 每次只改一項設定，記錄變更前後的第一個錯誤訊息。

Quarto 官方故障排查文件也建議先收集診斷資訊並縮小問題範圍；在證據尚未保存前清除環境，可能讓你失去定位線索。Quarto 故障排查說明

如果同一份文件在不同終端或資料夾中結果不同，先別把問題直接歸到 Quarto。Mac 上可能存在不同安裝位置，終端找到的命令未必是你以為的那一個。執行 quarto --version，並核對渲染命令指向的輸入文件、目前工作目錄和輸出格式。

接著確認專案設定。Quarto 專案常透過 _quarto.yml 設定輸出格式、資源、過濾器或其他項目；設定檔的位置會影響渲染時讀取的內容。對照專案設定文件，確認你是從預期的專案目錄執行，而不是在子資料夾誤用另一份設定。

依序查看 YAML 縮排與標點、檔案名稱、模板和過濾器路徑，再確認命令指定的格式。Quarto 的 render 命令參考列出渲染用法；PDF 相關選項則應對照官方 PDF 設定參考。先不要同時修改模板、輸出格式和工作目錄，否則即使故障消失，也難以判斷是哪項變更生效。

R 或 Python 區塊出錯，不一定是 LaTeX 問題。若日誌停在啟動執行環境、載入套件或執行程式碼的階段，先確認文件使用的執行引擎、R 或 Python 路徑、核心，以及專案所需依賴。若程式碼已完成並產生輸出，之後才出現 PDF 編譯錯誤，才轉查 TeX 與版面設定。

複製一個不含敏感資料的代表性區塊，放進最小文件測試。若最小程式碼仍無法執行，暫時退出 PDF 流程，先單獨處理執行環境；若程式碼輸出正常，則保留執行結果，轉查後續編譯階段。

特別留意快取與凍結輸出。它們可能讓舊結果仍出現在新文件中，造成程式碼已執行或資料已更新的錯覺。復測時確認結果確實來自當前程式碼；若清理快取會影響原專案，先在副本上操作。

Quarto PDF 渲染會使用 PDF 引擎與 TeX 工具鏈。不要只看自己安裝了哪個 TeX，也不要預設 Quarto 一定呼叫系統中的預設版本。從日誌確認實際執行的引擎名稱和路徑，再檢查對應的 TeX 安裝、缺少的套件，以及自動安裝套件時是否發生錯誤。

官方引擎文件列出可用的引擎選項，例如 lualatex、xelatex 和 pdflatex；這些名稱是選項，不代表每個科研專案都適合任一引擎。文件亦說明 TinyTeX 相關作法。比較既有 TeX 與 Quarto 管理的 TinyTeX 時，應分開測試與保存日誌，不要一次切換多套工具鏈。PDF 引擎與 TinyTeX 說明

中文或符號缺失時，逐項核對 PDF 引擎、設定中的字型名稱，以及字型涵蓋的字形。先用只含少量中文、標點和特殊符號的樣例測試；字型已安裝，不等於當前引擎一定能找到或正確使用它。若問題集中在圖表，則確認資源路徑、圖檔格式與圖表產生步驟，不要把圖表缺失一概歸因於 LaTeX。

引用或交叉引用異常時，檢查文獻檔路徑、引用鍵、處理階段和日誌訊息。Quarto 的引用與參考文獻文件可用來核對引用設定；如果只有引用內容未更新，先確認渲染是否讀取了正確的文獻檔，而非直接更換整套 TeX。

提醒： 引擎或字型調整後能產生 PDF，只代表該次渲染通過。論文引用、圖表內容與研究結果仍須由你按專案要求另外核對。

以下問題可協助你快速選擇下一步；實際處理仍以失敗日誌和最小樣例的結果為準。

Mac 上的 Quarto 出現 LaTeX 錯誤，從哪裡開始？

保留終端完整輸出，找到最早出現的具體錯誤，再確認日誌中的引擎命令與路徑。用不含研究資料的最小文件重現後，才針對缺少的套件或設定做單一修改。不要只依賴最後一行「PDF 未產生」的摘要訊息。

Quarto 找不到 lualatex，怎樣確認實際呼叫路徑？

查看渲染日誌中呼叫引擎的命令，並比對 PDF 格式設定指定的引擎與目前終端可找到的執行檔。若 Mac 裝有多套 TeX，先確認命令搜尋路徑，再在副本中調整。不要先假定 Quarto 使用系統預設引擎，也不要同時改動多套安裝。

中文字形缺失或顯示異常，應檢查哪些設定？

從引擎、字型名稱和字形涵蓋範圍查起，用最小文件測試中文字、標點與特殊符號。閱讀編譯日誌，確認引擎是否找到指定字型；圖表標籤也要單獨檢視。只有最小樣例與原文件使用相同設定時，復測結果才足以指向專案中的實際問題。

R 或 Python 區塊出錯，怎麼分辨核心執行和 PDF 編譯問題？

看日誌中止的位置：若停在啟動核心、載入套件或執行程式碼，優先核對文件指定的引擎和專案依賴；若程式碼已有輸出，之後才出現 TeX 訊息，則查 PDF 引擎。用脫敏程式碼重現，並排除快取或凍結輸出顯示舊結果的可能。

不要直接在唯一的論文專案上做大幅度清理。先複製專案，再按類別逐步加回原有元件；每次只恢復一類，讓故障重新出現時仍能指出最可能的觸發項目。

1. 確認基線： 在副本中執行最小 .qmd，保存命令、版本與完整輸出。
2. 恢復格式設定： 加回 YAML、_quarto.yml、模板與過濾器；每次渲染後記錄第一個差異。
3. 恢復程式碼： 分別加入 R 或 Python 區塊，確認執行引擎、依賴與輸出都符合預期。
4. 恢復文件資源： 加回字型、圖表、資料路徑與文獻檔，確認相對路徑在專案副本中仍有效。
5. 驗收交付 PDF： 檢查頁面、中文字形、引用、圖表及程式碼結果，並保存可重複執行的渲染命令與環境資訊。

決策時可按以下條件分流：

• 若最小文件也無法渲染： 先處理 Quarto 命令、PDF 引擎或 TeX 工具鏈；不要繼續改論文內容。
• 若最小文件通過、恢復某類元件後失敗： 保留該版本副本，將排查範圍縮到剛加入的設定、程式碼或資源。
• 若副本可渲染、本機原環境仍不穩定： 暫停改動原專案，改在隔離的 macOS 環境以同一份脫敏副本驗證；這只能協助定位環境差異，不能代替學術內容審核。
• 若 PDF 通過但數值、引用或版面未核對： 不要將文件標記為已驗收；先按研究流程確認結果與交付規範。

當本機反覆失敗，而專案確實需要 macOS 工具鏈，隔離環境可作為驗證選項；但它不能保證你的特定字型、套件或論文模板必然相容。你可先查看 CALMVPS 的 Mac 使用方案，再按週期、預算與環境需求核對方案與費用資訊。若目前使用的是固定本機環境且長期重負載，或工作必須直接連接特定實體設備，應先評估自購設備或實驗室現有資源，不必為了短期排錯而租用。

如果要驗證的是一次性渲染流程，且本機缺少可控的 macOS 測試環境，可先用脫敏專案確認遠端環境是否符合你的工具鏈要求；確認適用後，再考慮透過 CALMVPS 了解使用方式。PDF 成功產生是故障排查的一個結果，不是論文內容與科研結果的最終驗收。