跳到內容
Oleaflyv0.4.12

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

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

在你於 設定 → 引擎 → 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。

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

當專案依賴傳統的 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。

設定 → 引擎 → 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 發行版的電腦上選擇 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 只會變更你的電腦。

開啟 設定 → 引擎 → 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 的 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,或把編譯器留在 自動。自動會為 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 引擎做不到的功能,例如 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,在應用程式之外編譯。

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 分鐘,如果放棄,訊息會指出它在等哪個套件庫。請參閱下載來源分頁。

在 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 會在文件第一次使用套件時下載它。

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

範本會宣告它們需要的套件,而 Tectonic 會在第一次編譯時取得。使用隨選字型的範本會另外處理這些字型。請參閱 範本。

圖片預覽

無法載入 AI 回答

請再試一次,或搜尋文件。