# Typst 專案

為每個專案鎖定 Typst 版本、從 Typst Universe 加入套件、控制字型、建置變體與可重現的 PDF，並把 LaTeX 專案轉換為 Typst。

Oleafly 隨附 Typst 0.15.1 與 Tinymist 0.15.8 語言伺服器，所以新的 Typst 專案不必安裝任何東西就能編譯。本頁說明你可以更改的部分：專案使用哪個 Typst、套件與字型從哪裡來，以及同一份原始碼如何建置出多份 PDF。關於語法與工具列，請先閱讀[用 Typst 寫作](/docs/writing/typst/)。

## Typst 版本

開啟 **「設定 → 引擎 → Typst」**。第一張卡片是 **「Typst（內建）」**，也就是隨應用程式提供的版本。如果你的電腦上已經安裝了 `typst`，不論是在 `PATH` 中、Homebrew 的資料夾，還是 `~/.cargo/bin`，第二張卡片就會把它顯示為 **「這台電腦上的 Typst」**。鎖定該確切版本的專案，可以用它編譯。

卡片下方，**「版本」** 列出 Typst 0.11 到 0.15，最新的在前。每一列會顯示發布日期、下載大小、副本的來源（**「內建」**、**「已下載」** 或 **「系統」**），以及安裝之後它所使用的 Tinymist 版本。

- **「安裝」** 會下載該版本。Oleafly 會先試自己的鏡像，再試 GitHub，並以內建在應用程式中的 SHA-256 檢查碼，核對壓縮檔與其中的程式。不符的檔案會被丟棄，失敗或取消的安裝不會留下任何東西。下載的檔案放在 `~/.oleafly/toolchains/typst/`。
- 已安裝那一列左側的圓形按鈕，會把該版本設為預設。
- **「移除」** 會刪除已下載的版本。預設版本無法移除，所以請先選擇另一個預設版本。

### 預設版本與專案鎖定

新的 Typst 專案會鎖定預設版本。從範本建立的專案、匯入的專案與已連結資料夾也一樣。鎖定值以版本號碼（不是路徑）的形式存在專案的 `project.json` 中，所以在你搬移專案，或在另一台電腦上開啟時，仍然有效。

之後更改預設版本，不會連動既有的專案。這是刻意的：Oleafly 隨附較新的 Typst 時，已鎖定的論文仍保持相同的換行與頁數。

若要更改單一專案的版本，請開啟 **「重新編譯」** 旁邊的箭頭，並看 **「Typst 版本（本專案）」** 底下的內容。**「預設」** 會跟隨設定中選擇的版本，並清除鎖定。其他項目是這台電腦上已安裝的版本，適用時會標示 **[內建]** 或 **[系統]**。若要使用未列出的版本，請先在設定中安裝它。

### 鎖定的版本不存在時

如果你開啟的專案鎖定了這台電腦沒有的版本，Oleafly 不會悄悄改用不同的 Typst 來建置。編譯會停下來並顯示「未安裝 Typst 0.13.1」，預覽則提供兩個按鈕：

- **「下載 Typst 0.13.1」** 會安裝鎖定的版本並重新編譯。當該版本是 Oleafly 提供的版本時才會出現。
- **「使用 Typst 0.15.1」**（以你的預設版本命名）會清除鎖定，並用預設版本重新編譯。

在你選擇其中一個之前，編譯選單會把該鎖定標示為 **[未安裝]**。

### 切換之前先試用較新的版本

開啟 Typst 專案時，只要安裝了較新的 Typst，設定中的 Typst 分頁就會顯示 **「試用較新版本」**。選擇 **「以 Typst 0.15.1 檢查」**（或它所指名的任何版本）。Oleafly 會在暫存資料夾中建置專案兩次，一次用專案目前的版本，一次用較新的版本。你的專案不會有任何變動。

報告會顯示每次建置是否成功、頁數，以及錯誤與警告。頁數有變動時，它會告訴你。**「Typst 0.15.1 新增」** 列出只有較新版本才會回報的訊息，**「Typst 0.15.1 不再回報」** 則列出會消失的訊息。點擊訊息，就能在該行開啟它的檔案。

如果你滿意所見，**「切換到 Typst 0.15.1」** 會把專案鎖定到較新的版本。**「重新檢查」** 會在你修正問題之後，重新執行兩次建置。

### 語言伺服器跟隨版本

Tinymist 為 Typst 檔案提供自動完成、懸停說明、重新命名與格式化（參閱[程式碼智慧](/docs/code-intelligence/#typst-files)）。每個 Typst 次要版本都有自己的 Tinymist 版本，專案會與符合其 Typst 版本的那一個溝通。

內建的 Tinymist 涵蓋 Typst 0.15。當你開啟鎖定在較舊系列的專案時，Oleafly 會在背景下載對應的 Tinymist，並做同樣的檢查碼驗證，狀態會顯示「正在下載 Tinymist 0.13.30，以配合此專案的 Typst 版本。」如果下載失敗，Oleafly 之後會再試。當設定發現有已不再被任何已安裝 Typst 需要的 Tinymist 下載時，會提供 **「移除未使用的語言伺服器下載」**。

### 各版本能做什麼

保留較舊的版本，是為了讓以它們開始的專案能以相同的方式持續建置。有些功能取決於 Typst 版本本身支援什麼：

| 功能 | 0.11 | 0.12 | 0.13 | 0.14 及更新版本 |
| --- | --- | --- | --- | --- |
| 僅限專案字型 | 否 | 是 | 是 | 是 |
| 可重現建置 | 否 | 是 | 是 | 是 |
| PNG 與 SVG 匯出的頁面範圍 | 否 | 是 | 是 | 是 |
| PDF/A | 否 | PDF/A-2b | PDF/A-2b、PDF/A-3b | Typst 提供的所有 PDF/A 等級 |
| PDF/UA-1 | 否 | 否 | 否 | 是 |
| 保留在專案資料夾中的套件 | 否 | 是 | 是 | 是 |
| HTML 匯出，以及透過 Typst 的 HTML 進行的 Word 或 Markdown 匯出 | 否 | 否 | 是 | 是 |
| [原始碼與 PDF 同步](/docs/synctex/) | 否 | 否 | 是 | 是 |
| 每次編譯都產生標記式 PDF | 否 | 否 | 否 | 是 |

在 Typst 0.15 及更新版本上，字型選擇器能說明每個字型的來源。當某個設定無法套用到專案所用的版本時，編譯選單會把它標示為 **「需要較新的 Typst」**。

## 來自 Typst Universe 的套件

選擇 **「Typst 套件」**，也就是 Typst 工具列最右端的套件圖示。依名稱、關鍵字或類別搜尋 Typst Universe。每個套件都會顯示它的最新版本；需要比專案所用更新的 Typst 的套件會註明：「需要 Typst 0.14.0。此專案使用 Typst 0.13.1。」

**「插入 import」** 會把 `#import` 行寫在開啟的 Typst 檔案頂端。**「複製 import」** 則改為把它放到剪貼簿。

Typst 會在編譯第一次匯入 `@preview` 套件時下載它，並保存在所有專案共用的快取中。套件清單也會快取。離線時，對話方塊會顯示它上次取得的清單及其日期。

### 較新的版本

當 import 指定的版本比 Typst Universe 上的舊時，它的版本號碼會加上底線，並附上類似「cetz 0.4.2 已推出。這個 import 使用的是 0.3.4。」的提示。提示卡片提供 **「更新到 0.4.2」**，它會變更 import 中的版本號碼。接受之前請先閱讀套件的變更記錄，因為新版本可能改變套件的呼叫方式。將滑鼠移到 import 上，也會出現 **「在 Typst Universe 開啟」**。

### 把套件保留在專案內

在同一個對話方塊的 **「專案套件」** 底下，**「將套件複製到專案」** 會把專案匯入的每個套件，複製到專案最上層的 `typst-packages` 資料夾。它也會複製那些套件所匯入的套件，並開啟 **「使用專案資料夾中的套件」**。

從此 Typst 會先在 `typst-packages` 中尋找。已把套件複製進專案的專案，可以離線編譯，也能在任何電腦上編譯，這個資料夾也可以和你的原始碼一起放進 Git。你沒有複製的套件，仍然來自共用的快取。這需要 Typst 0.12 或更新版本，而在鎖定為 0.11 的專案上，對話方塊會請你先切換版本。

如果套件還不在快取中，對話方塊會指名它：「這些套件不在套件快取中：…」。請在連網時編譯一次，然後再複製一次。

### 離線模式

在 **「設定 → 一般」** 中開啟 **「離線模式」** 後，Typst 就無法下載任何東西。每個套件都必須已經在共用快取或 `typst-packages` 中。如果有套件不在，編譯會失敗，訊息會指出套件名稱，讓你知道下次連網時要取得什麼。

## 字型

Typst 會在四個地方尋找字型：Typst 內建的字型、你電腦上安裝的字型、你在 Oleafly 中下載的字型套件，以及專案內的字型資料夾。把字型檔案放在專案最上層名為 `fonts` 的資料夾中，編譯器與語言伺服器就都會讀取。額外的資料夾可以列在 `project.json` 的 `typst.font_paths` 底下。專案之外的資料夾會被忽略。

在編譯選單的 **「字型（本專案）」** 底下，**「使用系統字型」** 是預設值。**「僅限專案字型」** 會讓 Typst 不再讀取這台電腦上安裝的字型。這樣一來，PDF 在每台機器上都會一致；而且如果文件要求專案不包含的字型，你會在自己的電腦上發現，而不是在共同作者的電腦上。

若要選擇內文字型，請開啟 **「文件設定」**（Typst 工具列上的滑桿圖示），然後點擊 **「內文字型」**。清單會依專案目前的字型設定，列出 Typst 找得到的每個字型家族。在 Typst 0.15 及更新版本上，每個字型家族都帶有 **「專案」**、**「系統」**、**「字型套件」** 或 **「內建」** 標籤。選一個並選擇 **「套用」**，Oleafly 就會把它寫進文件的 `#set` 規則。

### 字型套件

**「設定 → 下載 → 字型」** 提供五個給 Typst 使用的免費字型套件：**「中文、日文和韓文」**、**「經典內文」**、**「現代無襯線與襯線」**、**「程式碼」** 和 **「圖示與表情符號」**。套件下載完成後，每個 Typst 專案都可以依名稱使用其中的字型，該分頁上下載的 Lato、PT Sans 和 PT Serif 也一樣。套件只會在整個下載完成後才加入編譯，所以只下載到一半的內容絕不會影響建置。

設為 **「僅限專案字型」** 或 **「可重現建置」** 的專案不會讀取字型套件。對這些專案，請把字型檔案複製到專案的 `fonts` 資料夾。

### 顯示為方框的字元

每次編譯之後，Oleafly 會檢查有沒有任何可用字型都畫不出來的字元。Typst 會把這些字元畫成方框。找到時，編譯會出現警告，編輯器上方也會出現通知：

- **空方框** 表示 Typst 能用的字型都沒有這些字元，警告會指出其中幾個。當字型套件涵蓋它們時（例如中文、日文和韓文套件涵蓋 CJK 文字，圖示與表情符號套件涵蓋表情符號），通知會提供 **「下載字型」** 和下載大小，記錄檔則提供 **「下載並編譯」**。否則，請把含有這些字元的字型加入專案的 `fonts` 資料夾。
- **帶問號的方框** 表示 Typst 用了預留位置字型來畫這些字元。請在 **「文件設定」** 的 **「內文字型」** 下指定含有它們的字型，或在字型清單中指定，例如 `#set text(font: ("Libertinus Serif", "Apple SD Gothic Neo"))`。
- 在設為 **「僅限專案字型」** 的專案中，字型套件和系統字型都不適用。請把字型加入 `fonts` 資料夾，或把專案切換為 **「使用系統字型」** 和 **「標準建置」**。

通知中的 **「文件設定」** 會開啟選擇內文字型的面板。關閉通知即可隱藏該警告的通知。

## 建置變體與 sys.inputs

建置變體是文件透過 `sys.inputs` 讀取的一組有名稱的值。當同一份原始碼需要產生不同的 PDF 時，請使用變體，例如匿名審查版與定稿版，或帶浮水印的草稿。

每個值要做什麼，由文件決定。值一律以文字的形式送達：

```typst
#let draft = sys.inputs.at("draft", default: "false") == "true"

#if draft [*Draft. Do not circulate.*]
```

設定變體的方式：

1. 開啟 **「文件設定」**，並捲動到 **「建置變體」**。
2. 選擇 **「新增變體」** 並為它命名，例如 `review`。
3. 選擇 **「新增值」**，然後在 **「名稱」** 下輸入 `draft`，在 **「值」** 下輸入 `true`。
4. 選擇 **「套用」**。
5. 開啟編譯選單。**「變體（本專案）」** 現在會列出 `review`。選擇它並編譯。

**「無變體」** 會在不帶任何變體值的情況下建置。你選擇的變體只會記在這台電腦上，所以共同作者可以從同一個專案建置不同的變體。變體本身儲存在 `project.json` 中。匯出時也會使用所選的變體。

每次建置都該取得的值，放在 `project.json` 的 `typst.inputs` 底下。當變體設定了同名的值時，以變體為準。

## 可重現的建置

在編譯選單的 **「建置（本專案）」** 底下，**「可重現建置」** 讓相同的原始碼在任何電腦上都產生相同的 PDF。它只使用專案字型與 Typst 內建的字型，並把 PDF 的日期設為最後一次 Git 提交的日期。不是 Git 儲存庫的專案，會得到固定的日期 1970 年 1 月 1 日。

當 PDF 必須符合檢查碼時，這就很重要，例如存放到典藏庫，或在 CI 中比對。它需要 Typst 0.12 或更新版本。開啟期間，**「使用系統字型」** 無法使用。**「標準建置」** 是預設值。

![Typst 邊輸入邊編譯：每新增一行，PDF 中就會隨之出現。](https://cdn.oleafly.com/images/gifs/desktop/typst-live.gif?v=2)

## 使用自動編譯的即時預覽

在編譯選單中，把 **「自動編譯」** 設為 **「開啟」**。在 Typst 專案中，Oleafly 接著會讓一個 Typst 處理程序持續執行。你停止輸入片刻後，開啟的檔案會自動儲存，Typst 隨即編譯，預覽則在相同的捲動位置重新載入。沒有另外的即時預覽設定：自動編譯就是即時預覽。

Typst 啟動期間，選單會顯示「正在啟動 Typst」。如果它因重複出錯而停止，選單會告訴你，而你的下一次編輯會讓它重新啟動。**「停止編譯」** 會結束該處理程序，下一次編輯同樣會讓它重新啟動。LaTeX 與 Markdown 專案處理自動編譯的方式不同；請參閱[編譯](/docs/compiling/#auto-compile)。

## 從命令列建置

`oleafly` 指令可以在不開啟應用程式的情況下建置專案。它隨 Oleafly 提供，[命令列工具](/docs/cli/#install)說明如何把它放到你的 PATH 上。

對於 Typst 專案，`oleafly build` 與 `oleafly watch` 會讀取 `project.json`，並使用與應用程式相同的設定：鎖定的版本、複製進專案的套件、字型資料夾、系統字型開關、輸入值與可重現建置。

- `--variant review` 會建置變體。專案沒有定義的名稱會讓建置停止，訊息會列出它確實擁有的變體。
- `--offline` 會封鎖套件下載，就像應用程式中的離線模式。
- 鎖定版本的專案只會用那個確切的 Typst 建置。CLI 會依序查看 `OLEAFLY_TYPST`、應用程式下載的版本、CLI 旁邊的 `typst`，然後是你的 `PATH`。如果都沒有回報鎖定的版本，建置會在 Typst 執行之前停止，並告訴你如何安裝。
- 沒有鎖定的專案，會在設定了 `OLEAFLY_TYPST` 時使用它。否則會使用你在 **「設定 → 下載」** 中，或用 `oleafly typst default` 選擇的預設版本；沒有選擇預設版本時，則使用內建的 Typst 或 `PATH` 上的 Typst。
- `oleafly doctor` 會列出它找到的每個 Typst，以及建置會使用的設定。鎖定的版本不存在時，它會失敗。

如果某個設定無法套用到正在使用的 Typst，建置會印出一則備註，例如 Typst 0.11.1 無法忽略系統字型。終端機中的錯誤包含 Typst 自己的提示。

## 將 LaTeX 專案轉換為 Typst

開啟 LaTeX 專案，按 ⌘K（Ctrl+K）並執行 **「轉換為 Typst 專案」**。為新專案命名並選擇 **「轉換」**。LaTeX 專案會維持原樣。Oleafly 會依它建立另一個獨立的 Typst 專案：

- Pandoc 會轉換文字、數學式、圖片與表格。如果 Pandoc 尚未設定，Oleafly 會先設定它。
- 以 `\input`、`\include` 或 `\subfile` 引入的每個檔案，都會成為獨立的 `.typ` 檔案。
- BibTeX 檔案會原樣複製。
- Typst 會編譯新專案來進行檢查。

接著報告會說明專案是否能編譯，並統計轉換了什麼：原始碼檔案、圖片、表格、行間公式、交互參照、數學轉換器修正的公式，以及複製的檔案，連同它選擇的參考文獻樣式。**「需要處理」** 會列出需要手動修正的項目，例如缺少的引入檔案或影像、Typst 無法顯示的影像格式、轉換器無法處理的數學式、沒有 Typst 對應的 BibTeX 樣式，或是多行公式其中一行上的標籤（它現在指向整個公式）。編譯錯誤與警告會連結到它們的檔案與行。

選擇 **「開啟 Typst 專案」** 以切換過去。新專案會鎖定你的預設 Typst 版本。只要 Oleafly 保持開啟，命令面板中的 **「顯示 Typst 轉換報告」** 就能把報告叫回來。

如果只想轉換單一檔案而不是整個專案，請在工具頁面使用 [LaTeX 轉 Typst](/docs/tools/latex-to-typst/)。

## 相關頁面

- [用 Typst 寫作](/docs/writing/typst/)：工具列與第一份文件。
- [編譯](/docs/compiling/)：記錄檔、編譯選單與離線模式。
- [匯出與轉換專案](/docs/export/#typst-images-and-html)：PNG、SVG、HTML、PDF/A 與 PDF/UA。
- [預檢](/docs/preflight/#typst-projects)：讀取 Typst 原始碼的檢查。
