# LaTeX 引擎與套件

選擇 Tectonic 或 latexmk 編譯器、使用既有的 TeX 發行版，或安裝 Oleafly 管理的 TinyTeX。

Oleafly 內建 Tectonic，也可以透過 `latexmk` 編譯。專案的編譯器選單控制日常的建置。**設定 → 引擎** 會顯示你機器上可用的 TeX 發行版和套件。

## Tectonic：日常使用的引擎

在你於 **設定 → 引擎 → LaTeX** 的 **預設編譯引擎** 中改選其他引擎之前，**Tectonic** 都是預設的編譯引擎。它不需要另外安裝，會視需要取得套件，並快取起來供離線使用。它適合大多數專案，而且即使沒有安裝系統 TeX 發行版，它仍然可用。請參閱 [為新專案設定預設值](/docs/engines/#set-a-default-for-new-projects)。

若要產生 **標記式 PDF**，請使用 LuaLaTeX 工作流程。標記描述文件結構，供輔助科技使用。編譯後請用預檢檢查結果。

### 內建引擎上的字型

Tectonic 以 XeTeX 為基礎，會直接讀取字型檔。Oleafly 做了一些調整，讓為 pdfLaTeX 撰寫的文件保有原本的字型和文字：

- Times、Helvetica、Courier、Palatino、Bookman、New Century Schoolbook 和 Avant Garde 會使用它們的 TeX Gyre 版本，而不是退回 Latin Modern。
- `\usepackage[T1]{fontenc}` 在這個引擎上會破壞輸入的重音符號和符號，所以 Oleafly 讓文件維持使用 Unicode 文字。如果文件使用的某個字型只有 T1 版本，文件就會維持在 T1，而編譯會警告 ß、§、«、彎引號和 € 等字元可能印錯或消失。警告會提供一個只在 pdfLaTeX 下才載入 T1 的寫法：

  ```latex
  \usepackage{iftex}
  \ifPDFTeX
    \usepackage[T1]{fontenc}
  \fi
  ```

- 設定了 `\pdfoutput=1` 的文件（arXiv 要求這麼做）會照原樣編譯。
- 沒有設定 `fontset` 的 `ctex` 文件會使用 Fandol 字型，讓它在每台電腦上看起來都一樣。若要使用 Mac 自己的字型，請在文件類別選項中加入 `fontset=mac`。
- 內建引擎隨附的字型要用檔案名稱尋找。`\setmainfont{UnBatang}` 會失敗，錯誤訊息會告訴你改寫成 `UnBatang.ttf`。

離線模式會略過字型和編碼的調整，所以這類文件的離線建置看起來可能與線上建置不同。

## latexmk 與系統 TeX

當專案依賴傳統的 TeX Live 或 MiKTeX 工作流程時，請從專案的編譯器選單選擇 pdfLaTeX、XeLaTeX、LuaLaTeX、upLaTeX 或 pLaTeX。Oleafly 會透過 `latexmk` 執行這些編譯器。**自動** 會讀取主檔案並選出其中一個：最上方的 `% !TeX program = xelatex` 這一行優先，其次是日文文件類別，再其次是需要 XeLaTeX 或 LuaLaTeX 的套件，例如 `fontspec`、`ctex`、`xeCJK` 或 `luatexko`。如果主檔案無法決定，自動也會檢查專案中的 `latexmkrc` 和序言區載入的檔案。其餘的一律使用 pdfLaTeX。如果某個套件需要的編譯器與自動選出的不同，編譯會提議切換，例如 **使用 XeLaTeX**。

有兩種方式可以提供這套工具鏈：

1. **使用現有的安裝。** Oleafly 會偵測你系統上的 MacTeX、TeX Live、MiKTeX 和 TinyTeX。它會查看與你的終端機相同的 `PATH`，在 Windows 上也會查看系統和使用者的 `Path` 設定，所以即使應用程式是從 Dock 或開始功能表開啟的，你手動安裝的 TeX 也找得到。只有當系統安裝的執行檔目錄中含有 `latexmk`、pdfLaTeX、XeLaTeX、LuaLaTeX、`kpsewhich` 和 Biber 時，它才會優先於 Oleafly 管理的副本。不完整的安裝不可能悄悄地超越運作正常的託管 TinyTeX。
2. **安裝託管的 TinyTeX。** 下載大小約 250 MB，不需要管理員權限。請參閱[安裝與更新 TinyTeX](#install-and-update-tinytex)。

**設定 → 引擎 → LaTeX** 中的 **管理 TeX 發行版** 會列出 Oleafly 找到的每個發行版。**使用中** 標示 `latexmk` 用來編譯的那一個，**latexmk** 徽章則標示每個可以編譯的發行版。在另一列選擇 **用於編譯** 即可切換過去。你選的那一列接著會顯示 **自動**，讓 Oleafly 重新自行挑選：先選完整的系統 TeX，再選 TinyTeX。

如果 TeX 安裝在 Oleafly 不會尋找的資料夾中，請按一下 **選擇 TeX 資料夾**，然後選取其中有 `latexmk` 的資料夾，或是上一層的 TeX Live 年度資料夾，例如 `texlive/2026`。Oleafly 會在裡面找到 `latexmk`，並用那個安裝來編譯，清單中會把它標示為 **使用中**。**自動** 會取消這項選擇。如果資料夾中沒有 `latexmk`，訊息會告訴你該改選哪個資料夾。

`latexmk` 不是檔案系統的沙箱。即使 shell 命令被阻擋，TeX 仍然可以讀取你帳戶能存取的檔案。Oleafly 也會停用專案、使用者和系統的 `.latexmkrc` 檔案，因為它們是可執行的 Perl。只有對你信任的專案才使用系統 TeX。匯入的專案只有在你選擇時才會使用系統 TeX，不論是設為預設編譯引擎，還是從專案的編譯器選單選擇。你原地開啟的資料夾，在你信任它之前會一直使用 Tectonic。

### 沒有安裝 TeX 時

在沒有可用 TeX 發行版的電腦上選擇 pdfLaTeX、XeLaTeX、LuaLaTeX、upLaTeX、pLaTeX 或自動，會開啟標題為 **這個編譯器需要可用的 TeX 發行版** 的對話方塊。它依序顯示三個選項：

- **下載 TinyTeX**，標示為 **推薦**。**下載並使用 TinyTeX** 會安裝 TinyTeX，並用它編譯專案。
- **使用我的系統 LaTeX（latexmk）**，說明找不到任何 TeX 發行版，或這台電腦上的那一個為什麼無法編譯。它沒有按鈕。
- **繼續使用 Tectonic**。**切換回 Tectonic** 會讓專案回到內建引擎。

如果你先編譯，預覽會提供同樣的出路：**下載並使用 TinyTeX**、**使用 Tectonic** 和 **開啟引擎設定**。你在 TinyTeX 還在下載時啟動的編譯會等待，並在安裝完成時自動開始。

有 TeX 發行版但沒有 `latexmk` 時，也會出現同樣的提議。當發行版缺少 `latexmk`、所選的編譯器或 Biber 時，如果 Oleafly 認得該發行版，訊息也會指出要安裝什麼，例如 MacTeX 上的 `sudo tlmgr install latexmk`，或 Ubuntu 上的 `sudo apt install latexmk`。

在共用專案中，按鈕會顯示 **讓所有人使用 Tectonic**，因為編譯器儲存在專案中，會對每位共同作者生效。安裝 TinyTeX 只會變更你的電腦。

### 安裝與更新 TinyTeX

開啟 **設定 → 引擎 → LaTeX**，在 **管理 TeX 發行版** 下選擇 **下載 TinyTeX（約 250 MB）**，或使用編譯對話方塊中的提議。TinyTeX 是精簡的 TeX Live，不需要管理員權限。期刊範本之後可能會加入套件，總共最多約 1 GB，而 Oleafly 在開始之前會檢查是否有約 2 GB 的可用磁碟空間。TinyTeX 安裝在 `~/.oleafly/tinytex` 下。

- **取消** 會停止下載並保留已經收到的部分。按鈕接著會顯示 **繼續下載** 和已完成的量。安裝期間結束 Oleafly 也會以同樣方式暫停，並在你下次開啟應用程式時繼續。
- 下載會先從 Oleafly 的鏡像站取得，再從 GitHub 取得。如果某個來源失敗，或有一分鐘沒有送出資料，Oleafly 會換到下一個來源，並從中斷的地方繼續。**設定 → 下載 → 下載來源** 可以變更下載的來源。請參閱[下載來源分頁](/docs/settings/downloads/#sources-tab)。
- 當託管的 TinyTeX 比這個版本的 Oleafly 預期的版本舊時，它那一列會顯示 **更新**。**移除** 會刪除它。

如果已有另一個發行版處於 **使用中**，安裝 TinyTeX 不會切換過去。想讓 TinyTeX 負責編譯時，請在 TinyTeX 那一列選擇 **用於編譯**。

在 Linux 上，TinyTeX 使用系統的 Perl。Oleafly 在下載任何東西之前會先檢查 Perl。如果缺少 Perl 或它的某個標準模組，訊息會給出安裝它的指令：`sudo apt install perl`、`sudo dnf install perl` 或 `sudo pacman -S perl`。

在 Windows 上，TeX Live 無法從名稱含有重音字母或非拉丁字母的資料夾執行。如果你的使用者資料夾有這樣的名稱，Oleafly 會改把 TinyTeX 放在 ProgramData 下的資料夾。如果防毒軟體在 TinyTeX 移入定位時占住某個檔案，Oleafly 會再試一次；如果仍無法完成，請稍等一下再重試安裝。

### MiKTeX 與 Perl

MiKTeX 的 `latexmk` 是 Perl 指令碼，而 MiKTeX 不含 Perl。沒有 Perl 時，設定會把 MiKTeX 標示為 **latexmk 需要 Perl**，如果已安裝 TinyTeX，Oleafly 會改用 TinyTeX 編譯。若沒有其他可用的東西，編譯會停止，並給你三個出路：從 **設定 → 引擎 → LaTeX** 安裝 TinyTeX（它自帶 Perl）、安裝 Strawberry Perl，或把專案切回 Tectonic。

MiKTeX 在 MiKTeX Console 中管理它的套件，所以 **套件** 清單和 **尋找並安裝** 不適用於它。MiKTeX 在編譯時也不會轉換 EPS 圖片，所以請先把它們轉成 PDF，或使用 TinyTeX。

### 日文文件：upLaTeX 與 pLaTeX

在日文文件的 **編譯器（本專案）** 下選擇 **upLaTeX** 或 **pLaTeX**，或把編譯器留在 **自動**。自動會為 `jsarticle`、`jsbook` 和 `jsreport` 選 pLaTeX（類別有 `uplatex` 選項時選 upLaTeX），為 `uj` 類別和 `jlreq` 選 upLaTeX，為 `ltjsarticle` 和其他 LuaTeX-ja 文件選 LuaLaTeX。

兩個編譯器都需要 TeX Live 的日文支援。如果託管的 TinyTeX 或 Oleafly 可以寫入的 TeX Live 缺少它，失敗的編譯會提供 **安裝日文支援（約 450 MB）**。它會安裝日文支援並再編譯一次。在其他安裝上，訊息會指出你的發行版適用的指令，例如 `sudo apt install texlive-lang-japanese`。

## 當 Tectonic 不夠用時

有些文件需要內建 Tectonic 引擎做不到的功能，例如 EPS 圖片或強制使用 `pdftex` 驅動程式。你開啟專案後的第一次編譯，或你自己啟動的編譯，遇到這類情況時，引擎對話框會自動開啟。由自動編譯或代理程式啟動編譯時，對話框不會開啟，而是會出現 **選擇引擎**。選擇它就能開啟對話框。這個按鈕會一直保留到下一次編譯，所以你關閉對話框之後，也可以用它重新開啟。它在哪裡取決於檢視方式：

- 編譯失敗後，當 **記錄檔** 開啟時，它在預覽工具列的右側。編譯沒有產生 PDF 時，預覽會自動切換到 **記錄檔**。如果仍然顯示著 PDF，請選擇 **記錄檔** 才看得到這個按鈕。
- 在空白的預覽中，它在 **重試編譯** 旁邊。
- 在僅編輯器檢視中、PDF 在自己的視窗時，或編譯成功後，它在 **重新編譯** 的左邊。

對話框的標題是 **這次編譯需要的功能超出內建引擎**，並列出它發現的問題。標示為 **推薦** 的選項排在最前面：

- **下載 TinyTeX** 在沒有安裝可用的 TeX 發行版時出現。它的按鈕 **下載並使用 TinyTeX** 會安裝 TinyTeX、把專案切換到 `latexmk`，然後重新編譯。
- **使用我的系統 LaTeX（latexmk）** 有 **使用系統 LaTeX**，會把專案切換到 Oleafly 找到的 TeX 發行版上的 `latexmk`。如果文件需要 pdfLaTeX，這個選項會顯示為 **在我的系統 LaTeX 上使用 pdfLaTeX（latexmk）**，按鈕則是 **切換至 pdfLaTeX 並重新編譯**。沒有安裝 TeX 時，這個選項沒有按鈕。
- **繼續使用 Tectonic** 有 **保留 Tectonic**，會讓專案留在內建引擎上。當切換可以解決對話框列出的問題時，這個選項會說明那些問題不會自行消失。

你保留 Tectonic 之後，同樣的問題在這台電腦上不會再為這個專案開啟對話框或顯示 **選擇引擎**。若之後想切換，請在 **編譯器（本專案）** 下選擇編譯器。

如果專案也需要執行外部命令，切換到系統 LaTeX 或 TinyTeX 時也會允許它們，對話框會在你按下之前先說明這點。你選擇的編譯器會儲存在專案中，所以共同作者會得到相同的設定。

## 允許外部命令

`minted` 和 PythonTeX 這類套件，以及使用 `\write18` 的文件，會在編譯時執行其他程式。Oleafly 預設會阻擋這點。編譯被阻擋，或記錄顯示專案需要這些命令時，編輯器上方的橫幅會提供 **允許外部命令**。

內建引擎也維持同樣的阻擋。Tectonic 從專案資料夾之外啟動，而 Oleafly 隨附的 Biber 會把文件的參考文獻設定當作純文字，並在編譯期間略過 `biber.conf`。

只對你信任其檔案的專案才允許外部命令，因為這樣 LaTeX 就能以你的權限執行任何程式。這項權限只對系統 LaTeX 有效，而且只留在這台電腦上。它絕不會存入 `project.json` 或提交到 Git，所以共同作者必須在自己的電腦上允許。在 [共用專案](/docs/collaboration/) 中，Oleafly 會在你開啟之前提出警告，因為任何能編輯專案的人，都可能在你編譯時於你的電腦上執行程式。把專案切回 Tectonic 或刪除專案，就會移除這項權限。在你原地開啟的資料夾中，請先信任該資料夾。信任資料夾本身並不會允許外部命令。

有引擎在時，[預檢](/docs/preflight/) 面板的 **編譯標記式輸出並驗證** 按鈕可以用 LuaLaTeX 產生標記式 PDF，並立即在一個步驟中稽核它。偏好用自己的工具鏈嗎？預檢的 **準備無障礙匯出** 會改寫你的原始碼以便加上標記，你再用 TeX Live 2026 的任何 LuaLaTeX，或是在 2025 年 11 月之後更新過的 TeX Live，在應用程式之外編譯。

## PDF 中缺少的字元

TeX 會略過字型沒有字形的任何字元，而編譯仍然成功。一段韓文、中文或日文可能變成空白而沒有任何錯誤。Oleafly 在每次編譯後都會讀取記錄檔，所以當字元缺少時，每個專案會收到一次通知，記錄檔會把它們列在 **缺少的字元** 之下，警告也會指出其中幾個。

在內建引擎和 XeLaTeX 上，警告也會為找到的每種文字提供一組設定，使用內建引擎隨附的字型。請把你需要的那一組貼到序言區：

```latex
% Korean
\usepackage[space]{xeCJK}
\setCJKmainfont[AutoFakeBold]{UnBatang.ttf}

% Simplified Chinese
\usepackage{xeCJK}
\setCJKmainfont[AutoFakeBold]{gbsn00lp.ttf}

% Traditional Chinese
\usepackage{xeCJK}
\setCJKmainfont[AutoFakeBold]{bsmi00lp.ttf}

% Japanese
\usepackage{xeCJK}
\setCJKmainfont{ipaexm.ttf}[BoldFont=ipaexg.ttf]
```

`space` 選項會保留韓文單字之間的空格，單純的 `xeCJK` 會把它們丟掉。

`CJKutf8` 和 `CJK` 套件只能在 pdfLaTeX 上運作。在內建引擎上載入它們的專案，編譯時會缺少中文、日文或韓文文字，所以通知會提供 **選擇引擎**，它會開啟切換到 pdfLaTeX 的選項。你也可以移除該套件和它的 `CJK` 環境，改用上面其中一組設定。

在 Mac 上使用 Mac 自己字型的 `ctex` 文件，可能讓 macOS 詢問是否下載字型，而編譯會等待你的回答。請回答該對話方塊後再編譯一次，或在 `\documentclass` 選項中加入 `fontset=fandol`。

其他缺少的字元，例如符號或另一種文字的字母，需要有這些字元的字型。請在序言區改用這樣的字型。Typst 專案請參閱[顯示為方框的字元](/docs/typst/#characters-that-show-as-boxes)。

## 套件管理員

引擎狀態下方是可篩選的 **套件** 清單，用於 LuaLaTeX 這一側，由 `tlmgr` 驅動：

- 從建議的套件清單開始，或輸入至少兩個字元並選擇 **搜尋 TeX Live** 來查詢完整的目錄。
- 可以用套件名稱或它包含的檔案來搜尋。當名稱不同時，Oleafly 會顯示擁有該檔案的 TeX Live 套件。
- 一鍵 **新增** 或 **移除** 套件。已安裝的列會顯示套件位於系統樹、你的個人樹，還是兩者皆有。
- 無障礙匯出之前，請檢查標記徽章：**標記：注意** 表示可能降低標記品質的套件，**破壞標記** 則表示已知的衝突。

這個套件管理員適用於 `latexmk` 所使用的 TeX Live 和 TinyTeX 發行版。Tectonic 自行管理它的套件快取。若是 MiKTeX，請使用 MiKTeX Console。

### 從缺少檔案中恢復

套件的名稱不一定與編譯記錄中提到的檔案相同。例如，`tikz.sty` 是由 `pgf` 套件安裝的。安裝一個猜測的、名為 `tikz` 的套件會失敗。

當 `latexmk` 編譯回報缺少檔案時，請使用訊息中的 **尋找並安裝**。這涵蓋套件、文件類別、參考文獻樣式、字型檔、babel 語言檔和 TikZ 程式庫。Oleafly 會詢問 TeX Live 哪個套件擁有該檔案、安裝那個套件，然後重新編譯。如果沒有任何 TeX Live 套件含有該檔案，它大概來自你的大學或出版社範本，請從原始範本把它加入專案。如果有數個套件含有它，訊息會列出這些套件，讓你選擇範本需要的那一個。如果無法連上目錄，或安裝沒有解決編譯問題，訊息會說明是哪一種情況。

如果你在沒有權限的情況下嘗試變更系統安裝，Oleafly 可以改為安裝到你的個人 TeX 樹中，而且在該樹還不存在時會先建立它。套件那一列會標明它最後裝在哪裡。移除擁有者套件時，也會移除它提供的其他檔案，所以移除之前請閱讀 **包含在** 的說明。

### 讓 tlmgr 與較舊的 TeX Live 版本繼續運作

TeX Live 的套件管理員 `tlmgr` 可能落後於線上的 TeX Live 儲存庫，這時它會拒絕安裝任何東西，直到更新自己。對於 Oleafly 管理的 TinyTeX，Oleafly 會更新 `tlmgr` 並重新安裝。對於你自己安裝的 TeX Live 或 TinyTeX，訊息會告訴你執行 `tlmgr update --self`。

一旦儲存庫進入新的 TeX Live 年度，較舊的安裝就無法從中安裝。Oleafly 接著會從你所用版本的最終封存安裝。如果封存中也沒有該套件，訊息會請你更新 TeX Live，或在設定中對託管的 TinyTeX 使用 **更新**。

### 選擇套件的來源

`tlmgr` 會從 TeX Live 套件庫安裝套件。Oleafly 管理的 TinyTeX 使用最近的 CTAN 鏡像站，除非你在 **設定 → 下載 → 下載來源** 的 **TeX 套件庫** 下，選擇指定套件庫，例如你大學的 CTAN 鏡像站。你自己安裝的 TeX Live 會保留它自己的套件庫，除非你在那裡輸入位址。Oleafly 在每次執行時把位址交給 `tlmgr`，絕不會變更它已儲存的設定。

必須連到套件庫的套件搜尋，在網路慢時可能要花一段時間。Oleafly 最多會等 10 分鐘，如果放棄，訊息會指出它在等哪個套件庫。請參閱[下載來源分頁](/docs/settings/downloads/#sources-tab)。

### Linux 發行版的 TeX Live

在 Debian、Ubuntu 和 Fedora 上，TeX Live 來自系統的套件管理員，所以 Oleafly 不會對它加入套件。**套件** 清單會說明改用 `apt` 或 `dnf`，缺少檔案時會顯示附有提示的通知，而不是 **尋找並安裝**：

- 在 Debian 和 Ubuntu 上，用 `apt-file search` 加檔案名稱找出套件，或用 `sudo apt install texlive-full` 安裝全部。
- 在 Fedora 上，通知會為缺少的檔案給出 `sudo dnf install 'tex(file.sty)'` 指令。

當發行版的 TeX 不完整時，通知也會提供 **下載 TinyTeX（約 250 MB）**，Oleafly 可以為它管理套件。在 Debian 和 Ubuntu 上，如果你已用 `tlmgr init-usertree` 設定了個人樹，Oleafly 會把套件安裝到該樹中。

## 從編輯器加入套件

選擇 **LaTeX 套件**（LaTeX 編輯器工具列上的套件圖示），不必離開文件就能搜尋 CTAN。每個結果都會顯示文件是否已經載入它（**已在文件中**）。在 `latexmk` 專案中，它也會顯示你的 TeX 發行版有沒有它（**已安裝**），而 **安裝** 會用 `tlmgr` 加入缺少的套件。使用 Linux 發行版的 TeX Live 時，對話方塊會改為告訴你用 `apt` 或 `dnf` 安裝套件。

**加入序言區** 會把 `\usepackage` 那一行寫入序言區。**選項** 讓你先加入套件選項，**複製這一行** 則改為複製那一行。Tectonic 專案沒有東西需要安裝：Tectonic 會在文件第一次使用套件時下載它。

## 是哪個引擎編譯了我的 PDF？

- 編譯選單（**重新編譯** 旁的箭頭）中的 **編譯器（本專案）**，會顯示目前專案儲存的編譯器。
- Tectonic 建置使用內建的引擎。
- pdfLaTeX、XeLaTeX、LuaLaTeX、upLaTeX 和 pLaTeX 的建置使用 `latexmk` 和設定中標示為 **使用中** 的 TeX 發行版。
- 預檢的標記式匯出使用 LuaLaTeX，並寫入一般的建置位置。

## 範本與套件

範本會宣告它們需要的套件，而 Tectonic 會在第一次編譯時取得。使用隨選字型的範本會另外處理這些字型。請參閱 [範本](/docs/templates/#on-demand-fonts-the-setup-badge)。
