追溯 ONLYOFFICE PDF 匯出失敗的源頭

請先儲存來源文檔，然後確定故障是發生在 ONLYOFFICE 的 PDF 轉換過程中，還是瀏覽器最終下載過程中。如果編輯器報告轉換錯誤，請檢查文件伺服器日誌，確認伺服器可以存取來源檔案。如果轉換成功但瀏覽器顯示“下載失敗”，請檢查瀏覽器的下載狀態、網站權限和可用磁碟空間。

範例場景：假設管理員 Jordan 使用自架的 ONLYOFFICE Docs 編輯器，選擇「檔案」>「下載為」>「PDF」來下載專案報告。編輯器顯示錯誤，並且沒有產生 PDF 文件。這只是一個假設範例，並非實際測試案例；同樣的問題可能出現在流程的不同階段，因此以下檢查將從流程停止點開始。

1. 保護原始碼並重現故障一次

在進行故障排除之前，請使用「儲存」或 Ctrl+S 儲存目前編輯。在 ONLYOFFICE 線上文件編輯器中，PDF 匯出路徑顯示為「檔案」>「下載為」>「PDF」。編輯器可能會先生成 PDF 文件，然後再將結果傳送給瀏覽器，因此瀏覽器下載失敗並不總是意味著轉換本身失敗。

使用同一份報告進行一次受控重試。注意編輯器是否顯示錯誤對話方塊、瀏覽器是否建立了下載失敗條目，以及該問題是否僅影響此文件或影響所有文件。避免重複點擊「匯出」：重複的匯出任務會使時間戳與對應的伺服器日誌項目相符變得更加困難。

2. 如果瀏覽器顯示 PDF 下載失敗

開啟瀏覽器的「下載」頁面，檢查下載失敗的檔案。重試一次。檢查瀏覽器是否阻止了從 ONLYOFFICE 網站下載文件，是否在其他標籤頁中顯示下載確認訊息，以及目標驅動器是否有足夠的可用空間。如果您是瀏覽器管理員，請在目前使用的其他瀏覽器或乾淨的瀏覽器設定檔中測試同一個已儲存的文件。如果測試成功，請專注於檢查瀏覽器設定、擴充功能或本機安全軟體；暫時不要變更文件伺服器的配置。

Jordan 的假設案例表明，編輯器完成 PDF 準備工作後，瀏覽器下載清單會報告網路或權限故障。一個可行的解決方法是使用“文件”>“列印”，然後選擇瀏覽器或作業系統的“儲存為 PDF”選項（如果可用）。請檢查列印輸出的頁面、字體和鏈接，因為列印輸出可能與編輯器直接導出的 PDF 不同。此方法無法修復伺服器端轉換錯誤。

3. 如果轉換或來源檢索失敗

對於自託管安裝，請管理員在重試時檢查文檔伺服器日誌。 ONLYOFFICE 會將 Linux 日誌保存在 `/etc/logs/logs` 目錄下/var/log/onlyoffice/documentserver；對於 Docker，日誌位於容器內部的對應路徑下，也可以使用 `docker output` 指令查看 Docker 輸出docker logs <container>。具體的元件和日誌內容取決於安裝方式和版本。請尋找轉換錯誤、逾時、請求失敗、HTTP 狀態碼或 DNS 和連線錯誤。如果日誌中包含私有 URL、存取權杖、使用者名稱或文件名稱，請勿公開完整的日誌行。

當日誌或 API 偵測到來源文件下載問題時，請驗證文件伺服器是否能從其自身的網路命名空間存取來源文件 URL。管理員可以從伺服器或容器測試授權 URL，並檢查 DNS、路由、防火牆規則、代理設定、TLS 憑證以及儲存應用程式的回應。即使在桌面瀏覽器中可以開啟的 URL，文檔伺服器也可能無法存取。反之，如果來源檔案下載成功但轉換失敗，則應調查轉換器錯誤，而不是更改網路存取方式。

對於基於 API 的轉換工作流程，請使用傳回的錯誤代碼來縮小問題範圍。 ONLYOFFICE 將轉換錯誤定義-4為下載輸入檔案-2時發生錯誤、逾時、-3轉換錯誤以及-8無效令牌。這些程式碼特定於轉換 API 的回應；編輯器中顯示的通用「下載失敗」訊息本身並不能證明 PDF 轉換回傳了其中任何一個錯誤代碼。

4. 只有在有證據顯示有問題時才檢查存取權限、權限範圍和大小。

如果只有儲存在某個連接平台上的文件發生故障，請檢查連接器的文檔伺服器位址和內部存取設定。編輯服務必須能夠從其儲存系統中檢索文件。 ONLYOFFICE 的故障排除文件將編輯器載入期間的「下載失敗」描述為編輯服務無法存取文件 URL。當報表無法開啟或載入時，此指南非常有用；如果編輯器正常打開，但只有 PDF 匯出失敗，請先檢查匯出或下載階段。

如果 API 報告令牌無效，請比較雙方的 JWT 金鑰、標頭和令牌配置。切勿為了圖方便而禁用 JWT。如果 API 指示存在大小限制，請將檔案與部署中配置的限制進行比較。大型檔案或不受支援/損壞的來源可能需要不同的解決方法；更換瀏覽器或網路無法解決轉換限製或損壞的文件。

僅當普通日誌無法顯示請求停止的位置時才啟用偵錯日誌，並在收集到所需證據後將其關閉。調試日誌可能包含敏感的請求詳細資訊。請按照 ONLYOFFICE 針對您的安裝類型的說明進行操作，並將經過編輯的日誌摘錄分享給您的管理員或支援團隊，而不是暴露文件 URL 或令牌。

驗證結果

• 確認下載的檔案存在、大小不為零，並且能夠用 PDF 閱讀器開啟。
• 對照原文檢查首頁和末頁、頁數以及一些關鍵字體或圖片。
• 相關修復完成後，請重複匯出一次。如果仍然失敗，請記錄時間、ONLYOFFICE Docs 版本、匯出階段以及已編輯的錯誤代碼或日誌摘錄。

ONLYOFFICE 的文件區分了 PDF 下載步驟和轉換錯誤。請參閱文件編輯器下載和列印說明、官方整合故障排除指南、轉換 API 錯誤代碼以及偵錯日誌指南，以取得與您的部署相符的詳細資訊。