LaTeX 引擎與套件
選擇 Tectonic 或 latexmk 編譯器、使用既有的 TeX 發行版,或安裝 Oleafly 管理的 TinyTeX。
Oleafly 內建 Tectonic,也可以透過 latexmk 編譯。專案的編譯器選單控制日常的建置。設定 → 引擎 會顯示你機器上可用的 TeX 發行版和套件。
Tectonic:日常使用的引擎
標題為「Tectonic:日常使用的引擎」的段落在你於 設定 → 引擎 → LaTeX 的 預設編譯引擎 中改選其他引擎之前,Tectonic 都是預設的編譯引擎。它不需要另外安裝,會視需要取得套件,並快取起來供離線使用。它適合大多數專案,而且即使沒有安裝系統 TeX 發行版,它仍然可用。請參閱 為新專案設定預設值。
若要產生 標記式 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 的寫法:\usepackage{iftex}\ifPDFTeX\usepackage[T1]{fontenc}\fi -
設定了
\pdfoutput=1的文件(arXiv 要求這麼做)會照原樣編譯。 -
沒有設定
fontset的ctex文件會使用 Fandol 字型,讓它在每台電腦上看起來都一樣。若要使用 Mac 自己的字型,請在文件類別選項中加入fontset=mac。 -
內建引擎隨附的字型要用檔案名稱尋找。
\setmainfont{UnBatang}會失敗,錯誤訊息會告訴你改寫成UnBatang.ttf。
離線模式會略過字型和編碼的調整,所以這類文件的離線建置看起來可能與線上建置不同。
latexmk 與系統 TeX
標題為「latexmk 與系統 TeX」的段落當專案依賴傳統的 TeX Live 或 MiKTeX 工作流程時,請從專案的編譯器選單選擇 pdfLaTeX、XeLaTeX、LuaLaTeX、upLaTeX 或 pLaTeX。Oleafly 會透過 latexmk 執行這些編譯器。自動 會讀取主檔案並選出其中一個:最上方的 % !TeX program = xelatex 這一行優先,其次是日文文件類別,再其次是需要 XeLaTeX 或 LuaLaTeX 的套件,例如 fontspec、ctex、xeCJK 或 luatexko。如果主檔案無法決定,自動也會檢查專案中的 latexmkrc 和序言區載入的檔案。其餘的一律使用 pdfLaTeX。如果某個套件需要的編譯器與自動選出的不同,編譯會提議切換,例如 使用 XeLaTeX。
有兩種方式可以提供這套工具鏈:
- 使用現有的安裝。 Oleafly 會偵測你系統上的 MacTeX、TeX Live、MiKTeX 和 TinyTeX。它會查看與你的終端機相同的
PATH,在 Windows 上也會查看系統和使用者的Path設定,所以即使應用程式是從 Dock 或開始功能表開啟的,你手動安裝的 TeX 也找得到。只有當系統安裝的執行檔目錄中含有latexmk、pdfLaTeX、XeLaTeX、LuaLaTeX、kpsewhich和 Biber 時,它才會優先於 Oleafly 管理的副本。不完整的安裝不可能悄悄地超越運作正常的託管 TinyTeX。 - 安裝託管的 TinyTeX。 下載大小約 250 MB,不需要管理員權限。請參閱安裝與更新 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 時」的段落在沒有可用 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
標題為「安裝與更新 TinyTeX」的段落開啟 設定 → 引擎 → LaTeX,在 管理 TeX 發行版 下選擇 下載 TinyTeX(約 250 MB),或使用編譯對話方塊中的提議。TinyTeX 是精簡的 TeX Live,不需要管理員權限。期刊範本之後可能會加入套件,總共最多約 1 GB,而 Oleafly 在開始之前會檢查是否有約 2 GB 的可用磁碟空間。TinyTeX 安裝在 ~/.oleafly/tinytex 下。
- 取消 會停止下載並保留已經收到的部分。按鈕接著會顯示 繼續下載 和已完成的量。安裝期間結束 Oleafly 也會以同樣方式暫停,並在你下次開啟應用程式時繼續。
- 下載會先從 Oleafly 的鏡像站取得,再從 GitHub 取得。如果某個來源失敗,或有一分鐘沒有送出資料,Oleafly 會換到下一個來源,並從中斷的地方繼續。設定 → 下載 → 下載來源 可以變更下載的來源。請參閱下載來源分頁。
- 當託管的 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 與 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」的段落在日文文件的 編譯器(本專案) 下選擇 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 不夠用時」的段落有些文件需要內建 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,所以共同作者必須在自己的電腦上允許。在 共用專案 中,Oleafly 會在你開啟之前提出警告,因為任何能編輯專案的人,都可能在你編譯時於你的電腦上執行程式。把專案切回 Tectonic 或刪除專案,就會移除這項權限。在你原地開啟的資料夾中,請先信任該資料夾。信任資料夾本身並不會允許外部命令。
有引擎在時,預檢 面板的 編譯標記式輸出並驗證 按鈕可以用 LuaLaTeX 產生標記式 PDF,並立即在一個步驟中稽核它。偏好用自己的工具鏈嗎?預檢的 準備無障礙匯出 會改寫你的原始碼以便加上標記,你再用 TeX Live 2026 的任何 LuaLaTeX,或是在 2025 年 11 月之後更新過的 TeX Live,在應用程式之外編譯。
PDF 中缺少的字元
標題為「PDF 中缺少的字元」的段落TeX 會略過字型沒有字形的任何字元,而編譯仍然成功。一段韓文、中文或日文可能變成空白而沒有任何錯誤。Oleafly 在每次編譯後都會讀取記錄檔,所以當字元缺少時,每個專案會收到一次通知,記錄檔會把它們列在 缺少的字元 之下,警告也會指出其中幾個。
在內建引擎和 XeLaTeX 上,警告也會為找到的每種文字提供一組設定,使用內建引擎隨附的字型。請把你需要的那一組貼到序言區:
% 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 專案請參閱顯示為方框的字元。
套件管理員
標題為「套件管理員」的段落引擎狀態下方是可篩選的 套件 清單,用於 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 版本繼續運作
標題為「讓 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 分鐘,如果放棄,訊息會指出它在等哪個套件庫。請參閱下載來源分頁。
Linux 發行版的 TeX Live
標題為「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?
標題為「是哪個引擎編譯了我的 PDF?」的段落- 編譯選單(重新編譯 旁的箭頭)中的 編譯器(本專案),會顯示目前專案儲存的編譯器。
- Tectonic 建置使用內建的引擎。
- pdfLaTeX、XeLaTeX、LuaLaTeX、upLaTeX 和 pLaTeX 的建置使用
latexmk和設定中標示為 使用中 的 TeX 發行版。 - 預檢的標記式匯出使用 LuaLaTeX,並寫入一般的建置位置。
範本與套件
標題為「範本與套件」的段落範本會宣告它們需要的套件,而 Tectonic 會在第一次編譯時取得。使用隨選字型的範本會另外處理這些字型。請參閱 範本。