# 編譯

編譯 LaTeX、Typst 和 Markdown 專案、依引擎選擇編譯選項、讀取記錄檔，並控制離線時的套件取得。

新的 LaTeX 專案會使用 **設定 → 引擎 → LaTeX** 中的預設編譯引擎。預設是 **Tectonic**，這是隨 Oleafly 一起提供、以 XeTeX 為基礎的引擎。當專案需要傳統的 TeX 工具鏈時，也可以使用 `latexmk`，可以只用於單一專案，也可以設為預設。Typst 專案使用內建的 Typst 或專案鎖定的其他版本來編譯，Markdown 專案則透過 Pandoc 和 Tectonic 處理。LaTeX 編譯器和 Typst 版本屬於專案本身，所以變更其中一個專案不會影響其他專案。

## 開始編譯

![在專案工具列使用「重新編譯」；旁邊的箭頭會開啟編譯選項。](https://cdn.oleafly.com/images/screenshots/desktop/docs/llama-writing-dark-window-v2.png#view=1265,0,330,48)

- 在任何地方按 ⌘↵（Ctrl+Enter）。
- 工具列右上角的 **編譯** 按鈕。專案有編譯結果之後，它會顯示為 **重新編譯**。
- ⌘K 指令面板中的 **重新編譯**。
- 以顯示 PDF 窗格的檢視開啟專案時，會自動編譯一次，讓你看到的是最新的預覽。
- 在終端機或腳本中執行 `oleafly build`。請參閱[命令列工具](/docs/cli/)。

編譯時一律會先儲存使用中的檔案，讓 PDF 與你看到的內容相符。如果你處於僅編輯器的檢視，編譯時會顯示分割檢視，讓你看到結果。

## 編譯選項

**重新編譯** 旁邊的箭頭會開啟編譯選項。選單只會顯示對專案的引擎有作用的選項。

| 群組 | 使用 Tectonic 的 LaTeX | 使用 `latexmk` 的 LaTeX | Typst | Markdown |
|---|---|---|---|---|
| **自動編譯** | 是 | 是 | 是 | 是 |
| **編譯模式**（一般或快速） | 是 | 否 | 否 | 否 |
| **語法檢查** | 是 | 是 | 否 | 否 |
| **編譯器（本專案）** | 是 | 是 | 否 | 否 |
| **Typst 版本**、**字型**、**建置**、**變體** | 否 | 否 | 是 | 否 |
| **編譯錯誤處理** | 是 | 是 | 否 | 否 |

**停止編譯** 和 **從頭重新編譯** 位於每個引擎選單的底部。Typst 專案有建置變體之後，就會出現 **變體** 群組。

在 **編譯器（本專案）** 下，**Tectonic** 是內建的。**自動** 會透過 `latexmk` 執行你的系統 TeX，並根據原始碼挑選編譯器。**pdfLaTeX**、**XeLaTeX** 和 **LuaLaTeX** 會鎖定該編譯器，同樣透過 `latexmk` 執行；**upLaTeX** 和 **pLaTeX** 用來編譯日文文件。除了 Tectonic 之外，每個選項都需要 TeX 發行版。如果這台電腦沒有，在你選擇其中一個時，Oleafly 會提議安裝 TinyTeX。請參閱[沒有安裝 TeX 時](/docs/latex-engines/#when-no-tex-is-installed)。Typst 的各個群組在 [Typst 專案](/docs/typst/)中說明。

## 自動編譯

在編譯選項中把 **自動編譯** 設為 **開啟**，或從 ⌘K 面板執行 **啟用自動編譯**。它預設是關閉的，適用於每個專案，用同樣的控制項可以再把它關閉。

在 LaTeX 或 Markdown 專案中，Oleafly 會在你停止輸入約 2.5 秒後重新編譯。只有真正的編輯才會觸發。切換分頁或開啟檔案不會。

在 Typst 專案中，自動編譯就是即時預覽。Oleafly 會讓一個 Typst 程序持續執行，開啟中的檔案會在你停止輸入片刻後自行儲存，而 PDF 會在相同的捲動位置重新整理。請參閱[使用自動編譯的即時預覽](/docs/typst/#live-preview-with-auto-compile)。

編譯不會堆積。如果你在自動編譯執行中編輯，Oleafly 會停止它，並用你最新的文字重新開始，讓 PDF 更快跟上。在以下情況，它會讓編譯完成：編譯是你或代理程式啟動的、正在下載套件、已接近完成，或它本身就是一次重新開始。在這些情況下，會恰好排入一次後續編譯，所以最終的 PDF 仍會反映你最新的編輯。

## 查看進度

建置期間，預覽頂端會有一條細細的進度列，在第一份 PDF 出現之前，窗格會顯示百分比估計值。建置完成時，工具列會顯示一個 **狀態標籤**，內有編譯時間和嚴重程度圖示：

- 綠色勾號：編譯成功。
- 琥珀色三角形：編譯完成但有警告。你仍然會得到 PDF。
- 紅色叉號：編譯時有錯誤。

成功時，預覽會自動切換到 PDF。只有真正的失敗（沒有產生 PDF）才會把你切換到記錄檔檢視。

![編譯失敗後，錯誤在編輯器與記錄中被標示，修正後重新編譯成功。](https://cdn.oleafly.com/images/gifs/desktop/compile-errors.gif?v=2)

## 讀取記錄檔

![記錄檔和上一次建置所需的時間位於預覽工具列的左側。](https://cdn.oleafly.com/images/screenshots/desktop/docs/llama-writing-dark-window-v2.png#view=1146,44,239,42)

預覽工具列左側的 **記錄檔** 按鈕可以在 PDF 和編譯記錄檔之間切換，並附有計算錯誤（紅色）或警告（琥珀色）數量的徽章：

- 最上方是解析過的**診斷清單**：每個錯誤或警告都附有種類，以及在已知時的 `l.42` 行參照。字型無法顯示的字元會歸在 **缺少的字元** 之下。
- 下方是完整的原始編譯器記錄檔，並加上顏色：錯誤為粗紅字、行參照會醒目提示、檔案的巢狀層級會縮排。
- **複製記錄檔** 按鈕會取得全部內容，可用於錯誤回報或論壇貼文。在記錄檔中按 ⌘A 再按 ⌘C 也會複製全部內容。
- **複製記錄檔** 旁邊的 **清除** 會隱藏記錄檔和其中的錯誤，直到下一次編譯為止。你的建置檔案會保留，下一次編譯會寫出新的記錄檔。

很長的記錄檔也會立刻開啟，即使有 100,000 行也一樣，而且捲動時不會出現空白區域。

編譯錯誤也會透過[檢查器管線](/docs/editor/#the-built-in-latex-linter)在編輯器中變成波浪底線，當你要求[AI 助理](/docs/ai-chat/)修正錯誤時，它可以用 `get_log` 工具讀取同一份記錄檔。

Typst 錯誤會標示在編輯器中 Typst 回報的確切範圍，並附上原始碼行和 Typst 自己的提示。常見的錯誤也會附上簡單的說明，解釋哪裡出了問題。

## 套件與離線編譯

Tectonic 會在文件第一次需要某個 LaTeX 套件時下載它，然後在本機快取。這台電腦的第一次編譯也會一次取得一批常用的套件。第一次編譯可能比較慢，而且需要網路連線。之後的編譯會使用快取。如果 Oleafly 的套件鏡像站失敗，編譯會改用上游來源，記錄檔也會說明這一點。

「設定」的「一般」頁面或指令面板中的 **離線模式**，讓 Tectonic 的這件事成為保證。編譯器會以 `--only-cached` 執行，絕不取得套件。需要未快取套件的文件會失敗，並顯示訊息，可能時會指出檔案名稱，而 **關閉並編譯** 會關閉離線模式並重新編譯。

離線模式也涵蓋 Typst。Typst 在離線模式開啟時無法下載套件，所以每個 `@preview` 套件都必須已在快取中，或已隨附在專案的 `typst-packages` 資料夾中。請參閱[來自 Typst Universe 的套件](/docs/typst/#packages-from-typst-universe)。Markdown 專案會忽略離線模式，記錄檔也會說明這一點。

`latexmk` 使用你機器上已安裝的 TeX 發行版。Oleafly 會先檢查系統發行版，包括 MacTeX、TeX Live、MiKTeX 和 TinyTeX，而 **設定 → 引擎 → LaTeX** 會把它用來編譯的那一個標示為 **使用中**。如果都沒有，應用程式可以安裝並管理自己的 TinyTeX 副本。MiKTeX 也需要 Perl 才能執行 `latexmk`；請參閱 [MiKTeX 與 Perl](/docs/latex-engines/#miktex-and-perl)。由於系統的 TeX 程序可以讀取你的使用者帳號可存取的檔案，請只對你信任的專案使用 `latexmk`。

當 `latexmk` 建置找不到 `.sty`、`.cls`、參考文獻樣式、字型檔、babel 語言檔、TikZ 程式庫或其他 TeX 檔案時，Oleafly 可以在錯誤訊息中提供 **尋找並安裝**。檔案名稱和套件名稱通常不同：例如 `tikz.sty` 屬於 TeX Live 套件 `pgf`。Oleafly 會找出擁有者，用 `tlmgr` 安裝它，重新整理套件清單，然後重新編譯。在 Debian、Ubuntu 和 Fedora 上，TeX Live 由系統的套件管理員管理，所以 Oleafly 會改為提供 `apt` 或 `dnf` 指令。如果你想先搜尋或手動管理套件，請使用 **設定 → 引擎 → LaTeX** 中的 **套件** 清單。

## 限制與保護機制

- 每個專案同一時間只會執行一次編譯，並採用只保留最新要求的佇列：較新的要求會取代過時的要求，所以在建置途中切換專案，絕不會畫出錯誤的 PDF，你輸入時也不會形成大量編譯。
- 被取代或逾時的建置會被確實取消：Oleafly 會在每個平台上終止編譯器的整個程序樹，而不是讓它留在背景執行。
- 執行超過 5 分鐘的編譯會被停止，而不是讓它永遠空轉。Tectonic 還在下載套件時，每次下載都會把時限往後延，最多總共 30 分鐘。Markdown 轉 PDF 有 15 分鐘，Quarto 和 Calepin 有一小時。
- 結果帶有與要求綁定的識別，所以順序錯亂的完成所產生的過時 PDF 會被拒絕，而不是顯示出來。

## 常見失敗與快速修復

- **離線模式下的「Missing package」**：在訊息中選擇 **關閉並編譯**，或暫時為一次編譯關閉離線模式以取得並快取它，然後再把它開啟。
- **「這個編譯器需要可用的 TeX 發行版」**：pdfLaTeX 和其他 `latexmk` 編譯器需要這台電腦上有 TeX，所以在沒有 TeX 的情況下選擇其中一個，就會開啟這個對話方塊。選擇 **下載並使用 TinyTeX**，或選擇 **切換回 Tectonic** 回到內建引擎。如果編譯已經因為這個原因失敗，預覽會提供 **下載並使用 TinyTeX** 和 **使用 Tectonic**。請參閱[沒有安裝 TeX 時](/docs/latex-engines/#when-no-tex-is-installed)。
- **MiKTeX 上的「latexmk 需要 Perl」**：安裝 Strawberry Perl，或安裝自帶 Perl 的 TinyTeX。請參閱 [MiKTeX 與 Perl](/docs/latex-engines/#miktex-and-perl)。
- **`latexmk` 建置中缺少檔案**：使用 **尋找並安裝**。如果查詢失敗，請在 **設定 → 引擎 → LaTeX** 的 **套件** 清單中搜尋檔案或套件名稱。在 Debian、Ubuntu 或 Fedora 上，請用 `apt` 或 `dnf` 安裝。MiKTeX 套件由 MiKTeX Console 管理。
- **沒有安裝 upLaTeX 或 pLaTeX**：在提供時選擇 **安裝日文支援（約 450 MB）**，或執行訊息中指出的指令。請參閱[日文文件](/docs/latex-engines/#japanese-documents-uplatex-and-platex)。
- **PDF 中缺少文字**，通常是韓文、中文或日文：字型沒有這些字元的字形，TeX 會直接略過而不會失敗。Oleafly 會警告你，記錄檔也會提供可以貼上的設定。請參閱[PDF 中缺少的字元](/docs/latex-engines/#characters-missing-from-the-pdf)，Typst 則請參閱[顯示為方框的字元](/docs/typst/#characters-that-show-as-boxes)。
- **PDF 中缺少索引、詞彙表或符號表**：Tectonic 無法執行 `makeindex`。請把專案切換到 `latexmk`，或用 `\makenoidxglossaries` 建置詞彙表，它不需要外部工具。在 `latexmk` 上，用 `xindy` 或 `\newglossary` 產生的清單不會被建置。
- **編譯逾時**：再編譯一次。如果套件還在下載，下載會從停下來的地方繼續。在 Tectonic 上編譯很長的草稿時，請把 **編譯模式** 設為 **快速**。
- **Tectonic 中的 EPS 圖片、強制指定的 `pdftex` 驅動程式，或缺少的內建檔案**：會開啟引擎對話方塊。如果沒有開啟，或你把它關掉了，請選擇 **選擇引擎**。[Tectonic 不夠用時](/docs/latex-engines/#when-tectonic-isnt-enough)說明了它在每種檢視中的位置。請選擇標示為 **推薦** 的選項：當 Oleafly 找到可用的 TeX 發行版時是你的系統 LaTeX，找不到時則是 **下載並使用 TinyTeX**。對於缺少的套件，Oleafly 可以在切換後繼續進行安裝程式。
- **`minted`、PythonTeX 或 `\write18` 被封鎖**：如果你信任專案中的每個檔案，請在編輯器上方的橫幅中選擇 **允許外部命令**。請參閱[允許外部命令](/docs/latex-engines/#allow-external-commands)。
- **Tectonic 中的套件下載失敗**：請檢查網路連線，並在訊息中選擇 **重新編譯**。Oleafly 在鏡像站之後已經試過上游來源，下載會從停下來的地方繼續，如果電腦當時離線，連線恢復後編譯會自動再執行一次。
- **「未安裝 Typst 0.13.1」**：專案鎖定了這台電腦上沒有的 Typst 版本。在預覽中選擇 **下載 Typst 0.13.1**，或選擇 **使用 Typst** 後接你的預設版本以解除鎖定。請參閱[鎖定的版本遺失時](/docs/typst/#when-a-pinned-version-is-missing)。
- **未定義的引用或參照警告**：[預檢](/docs/preflight/#six-independent-checks)會指出每一個，並附上檔案和行號。
- **你看不懂的錯誤**：問 AI。「修正 LaTeX 錯誤」會觸發編譯、讀取記錄檔、有針對性的編輯和重新編譯的循環，並採用你所選的[核准政策](/docs/ai-chat/)。

## 其他文件引擎

LaTeX 編譯器的選擇與專案的文件引擎是分開的：

- **Typst 專案**使用內建的 Typst 0.15.1 或專案鎖定的版本來編譯。請參閱 [Typst 專案](/docs/typst/)。
- **Markdown 專案**透過受管理的 Pandoc，並以 Tectonic 作為 PDF 引擎，建置成 PDF。
- **Quarto 專案**使用 Quarto 把 `.qmd` 和 `.Rmd` 檔案算繪成 PDF 或網頁。請參閱 [Quarto](/docs/engines/#quarto)。
- **Calepin 專案**使用 Calepin 執行 Typst 文件中的程式碼，再用內建的 Typst 建置 PDF。請參閱 [Calepin](/docs/engines/#calepin)。在你[允許](/docs/engines/#allow-code-in-a-project)之前，這兩種引擎都不會執行專案的程式碼。
- **帶標籤的無障礙 PDF** 透過系統 TeX 安裝或 Oleafly 管理的 TinyTeX 使用 LuaLaTeX。請參閱 [LaTeX 引擎與套件](/docs/latex-engines/)。Typst 0.14 及更新版本不需要額外步驟就會為每個 PDF 加上標籤。

引擎是建立專案時為每個專案所做的選擇，介面會配合它調整：引擎無法支援的動作會被隱藏，而不是留著讓它失敗。若要把 LaTeX 專案移到 Typst，請[把它轉換成新的 Typst 專案](/docs/typst/#convert-a-latex-project-to-typst)。

## 在建置成功時保留原始碼

啟用[檢查點](/docs/checkpoints/)，可以保存成功編譯所用的原始碼。你可以比較並還原較早的建置，而不必改變你手動使用 Git 的工作流程。

若要把編譯出的 PDF 本身保留在專案資料夾中，請在預覽的儲存選單中開啟[編譯時同步 PDF](/docs/pdf-preview/#sync-pdf-on-compiles)。
