# 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** 会在打开的 Typst 文件顶部写入 `#import` 行。**复制 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 构建。命令行工具会依次查看 `OLEAFLY_TYPST`、应用下载的版本、命令行工具旁边的 `typst`，然后是你的 `PATH`。如果都没有报告出固定的版本，构建会在 Typst 运行之前停止，并告诉你如何安装。
- 没有固定版本的项目在设置了 `OLEAFLY_TYPST` 时使用它。否则使用你在 **设置 → 下载** 中或通过 `oleafly typst default` 选择的默认版本；没有选择默认版本时，则使用内置的 Typst 或你的 `PATH` 中的那个。
- `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 源码的各项检查。
