第一份文档：标记语法、编译与 watch

先看一个数字#

我很快就会让你去写 Typst，但在那之前我想先交代为什么值得换：同一份文档，Typst 比 LaTeX 快多少。

我用脚本 scripts/gen-bench.sh 生成了两份内容等价的文档（一份 .typ，一份 .tex）：8 节，30 个带编号的公式，5 张表，目录，20 处交叉引用，大段中英混排正文。两边都用同一个字体 Maple Mono NF CN 来排中文，LaTeX 用 fontspec + xeCJK + amsmath + booktabs + hyperref，由 latexmk -xelatex 编译。

为什么是 Maple Mono 而不是正文该用的 Noto Serif CJK？因为 xdvipdfmx 嵌不进可变字体版的 Noto TTC（报 sfnt: table not found），而我这台机器上唯一的静态 CJK 字体就是 Maple Mono。对比要公平，就得让两个引擎吃同一个静态 TTF。（顺带一提，这意味着这份基准不是排版好看的基准，只是引擎速度的基准。）

跑法是 make bench，里面是 hyperfine，每轮 LaTeX 之前先 latexmk -C 清掉辅助文件，所以 LaTeX 是冷启动：

1
$ make bench
2
Benchmark 1: typst compile --root . lab/ch01/bench/same.typ out/bench/same.pdf
3
  Time (mean ± σ):     226.1 ms ±   5.4 ms    [User: 145.9 ms, System: 85.8 ms]
4
  Range (min … max):   214.6 ms … 236.3 ms    13 runs
5

6
Benchmark 2: latexmk -xelatex -interaction=nonstopmode -outdir=out/bench/tex lab/ch01/bench/same.tex >/dev/null
7
  Time (mean ± σ):      3.131 s ±  0.072 s    [User: 2.416 s, System: 0.687 s]
8
  Range (min … max):    3.025 s …  3.252 s    10 runs
9

10
Summary
11
  typst compile --root . lab/ch01/bench/same.typ out/bench/same.pdf ran
12
   13.85 ± 0.46 times faster than latexmk -xelatex -interaction=nonstopmode -outdir=out/bench/tex lab/ch01/bench/same.tex >/dev/null

226 ms 对 3.131 s，14 倍。输出都是 9 页（pdfinfo 数的）。机器是 AMD Ryzen 7 PRO 6850U，16 个线程，LaTeX 是 TeX Live 2025（XeTeX 3.141592653-2.6-0.999997）。注意 nix develop 不提供 xelatex 和 latexmk，它们是我系统里自带的；你的机器上没有的话，make bench 会打印 skip: xelatex not found，然后只测 Typst 那一半。

几条诚实的限定：这是一台机器上、一份合成文档的数字，我猜换成你的论文会有出入。LaTeX 一侧我用的是 latexmk，它会按需要重复调用 xelatex 直到目录和引用稳定，我没有数它实际跑了几遍，所以这 14 倍里有多少是“遍数”、有多少是引擎本身，我说不清。但对“每次保存都想看结果”的日常写作来说，3 秒和 0.2 秒是两种体验，下面的 watch 会让你直接看到。

这个系列怎么读#

规矩有四条。

固定的代码快照。 参考实现是仓库 typst-lab 的 tutorial-v1 标签。这一篇的所有命令都在它上面跑过。每章末尾的检查点会告诉你哪些文件已经是最终版（必须和标签一致），哪些还是中间版本，后面的篇章会继续改它们。

每章一个实验目录。 第 N 篇对应仓库里的 lab/chNN/，里面是一堆小的 .typ 文件，make chNN 一次编译全部。我引用它们时会写出路径。文件我都按 typstyle -l 80 格式化过，贴在文中的就是它们的原样；太长的文件我会只贴有教学价值的部分并明说。

*.fail.typ 与 *.warn.typ。 凡是文件名带 .fail.typ 的，它的使命就是编译失败；带 .warn.typ 的必须编译成功但有警告。scripts/chapter.sh 会检查这个预期，期望失败却成功了，脚本本身就报错。仓库里文件的错误信息，我都是从 out/chNN/*.stderr 里原样贴出来的；少数是我在 /tmp 里为讲解临时写的小实验，我会明说。

真实输出。 本系列的所有命令输出，都是在 Typst 0.15.1（9dfd3a08）上跑出来的。输出偶尔会被我截断（用 ... 标出），但不会改写。版本不同时，错误信息的措辞可能略有出入。

下面是整个系列的地图：

顺序就是依赖顺序：每一篇只会用到前面讲过的东西。

装环境#

typst-lab 有一个 flake.nix，nix develop 进去就是我用的全部工具，字体也在里面：

1
git clone --branch tutorial-v1 https://github.com/bfmhno3/typst-lab.git
2
cd typst-lab
3
nix develop

进去的时候 shell 会打印一行横幅，我这边是：

1
typst-lab dev shell: typst 0.15.1 (9dfd3a08), 0.15.0, rustc 1.97.1 (8bab26f4f 2026-07-14) (built from a source tarball)

三个版本依次是 Typst 0.15.1、typstyle 0.15.0（代码格式化器，第 16 篇用）、Rust 1.97.1（第 15 篇用）。flake.lock 钉死的 nixpkgs 版本和这个博客的一样，所以你装出来的版本应该就是这几个。没有 Nix 的话，你需要自己装 Typst 0.15.1 和 Noto Serif CJK、Noto Sans CJK 字体，再把字体目录写进环境变量 TYPST_FONT_PATHS、把仓库里的 packages/ 写进 TYPST_PACKAGE_PATH；我没有在非 Nix 环境里验证过完整流程，所以这条路径上的输出我不替你担保。

shell 还做了三件事，后面都会用到：把字体目录放进 TYPST_FONT_PATHS，把仓库的 packages/ 放进 TYPST_PACKAGE_PATH（第 4 篇讲为什么），以及 unset SOURCE_DATE_EPOCH（不然 datetime.today() 在 nix shell 里永远是 1980-01-01）。

之后所有命令都在仓库根目录、nix develop 里执行，Makefile 开头有个守卫，不在 shell 里就报 run inside nix develop。

第一次编译#

最小的文件是 lab/ch01/hello.typ：

1
= 你好，Typst
2

3
这是第一份文档。保存后 `typst watch` 会立刻重新编译。

没有 \documentclass，没有 \begin{document}，没有导言区。第一行 = 加空格是一级标题，空一行是新段落，反引号包起来的是行内代码。编译：

1
$ typst compile hello.typ
2
$ ls
3
hello.pdf  hello.typ

没有输出就是成功。输出文件默认是同名的 .pdf。这个文件在我机器上编译一次，hyperfine -N 测得：带 --ignore-system-fonts 是 83.5 ± 5.4 ms，不带是 182.9 ± 2.6 ms。多出来的约 100 ms，我猜是扫描这台机器上 284 个系统字体族的代价（下面讲 typst fonts 时你会看到这个数字），我没有单独验证。两个数字都含进程启动。

有一件事我先点一下：这个文件没有指定字体，但标题和正文里的汉字显示出来了。我用 pdffonts 看了（带 --ignore-system-fonts 编译出来的）PDF，里面嵌了 LibertinusSerif（拉丁字母，Typst 内置的默认字体）、DejaVuSansMono（行内代码，也是内置的）和一个叫 NotoSansCJKjp-Thin 的字体（汉字）。Libertinus 里没有汉字，所以 Typst 往后找，找到了我环境变量里的 Noto Sans CJK。这个“碰巧能用”不可靠（连选中了哪个变体都不由我决定），第 5 篇我们会把每一层字体都显式钉死，那个奇怪的字体名也到时再解释。

1
mkdir -p /tmp/t01 && cp lab/ch01/hello.typ /tmp/t01/ && cd /tmp/t01
2
typst watch hello.typ >watch.log 2>&1 &
3
W=$!
4
sleep 3; echo "这是新增的一行。" >> hello.typ
5
sleep 2; echo "再改一次。" >> hello.typ
6
sleep 2; kill $W

1
[08:19:30] compiling ...
2
[08:19:30] compiled successfully in 50.47 ms
3
[08:19:33] compiling ...
4
[08:19:33] compiled successfully in 3.36 ms
5
[08:19:35] compiling ...
6
[08:19:35] compiled successfully in 2.66 ms

标记语法：一次过一遍#

下面是本篇的主角 lab/ch01/markup-tour.typ，我把 Typst 日常写作用到的标记几乎都塞进了它：

1
#set page(width: 14cm, height: auto, margin: 1cm)
2
#set heading(numbering: "1.1")
3

4
= 标记语法速览 <tour>
5

6
普通段落，*加粗*，_强调_，行内代码 `let x = 1`，自动链接 https://typst.app。
7
空行分段；行末加反斜杠 \
8
可以强制换行。不换行空格 10~km，连字符 -- 与 --- 分别是 en dash 与 em dash。
9
智能引号："double" 与 'single'。
10

11
== 列表与术语
12

13
- 无序列表
14
- 第二项
15
  - 嵌套一层
16

17
+ 有序列表
18
+ 编号自动递增
19

20
/ 术语: 这是术语列表的说明。
21
/ Typst: 一门基于标记的排版语言。
22

23
== 代码块与标签 <code>
24

25
```rust
26
fn main() {
27
    println!("hello");
28
}
29
```
30

31
转义：\#、\*、\_，Unicode：\u{4e2d}\u{6587}。
32
引用：见 @tour 与 @code。
33

34
// 这一行是注释，不会出现在输出里。
35
/* 块注释
36
也一样。 */

开头两行 #set 先不管（它们是第 4 篇的主题，这里只是让页面窄一点、标题带编号，方便截图和引用）。编译它，用 --pages 1 --format png --ppi 72 渲染成图：

1
$ typst compile --root . --ignore-system-fonts lab/ch01/markup-tour.typ out/ch01/markup-tour.pdf
2
$ typst compile --root . --ignore-system-fonts --pages 1 --format png --ppi 72 lab/ch01/markup-tour.typ out/figures/ch01-markup-page.png

结果：

我把每一条语法对应到它的效果，逐个说明。

1
中文*加粗*中文，English*not*Strong，中_强调_文。

1
中文加粗中文，English*not*Strong，中强调文。

1
网址 https://typst.app/docs，之后。
2
再 https://typst.app/docs. 之后。

1
= 引言 <intro>
2

3
见 @intro。

1
error: cannot reference heading without numbering
2
  ┌─ noref.typ:3:2
3
  │
4
3 │ 见 @intro。
5
  │    ^^^^^^
6
  │
7
  = hint: you can enable heading numbering with `#set heading(numbering: "1.")`

三种模式#

上面的 #set heading(...) 是我偷偷用到的第一处“代码”。Typst 有三种模式，在它们之间切换，是这门语言最核心的设计。我用一个暂存文件 modes.typ（不在仓库里）把三种模式混在一起：

1
#let w = 3
2
#let name = "Typst"
3

4
// 代码模式：# 后面接一个表达式，到表达式结束为止
5
宽度是 #w 厘米，#name.len() 个字母。
6
// 方法调用、字段访问会被吃进去，标点不会
7
先 #name，再 #name.
8
// 想让表达式带上后面的文字，用括号或者 #[]
9
#(w + 1)cm，#(name)er，#upper[hello]world
10

11
// 代码块内部是代码模式，方括号回到标记模式
12
#{
13
  let n = 2 + 3
14
  [n 等于 #n，]
15
  "字符串也会被拼进来。"
16
}
17

18
// 数学模式
19
行内 $x^2 + y^2 = z^2$，块级：
20
$ sum_(i=1)^n i = (n(n+1)) / 2 $
21
数学里嵌代码：$#w dot 2 = #(w * 2)$。

编译（typst compile modes.typ）后，pdftotext -layout 抽出的文字是：

1
宽度是 3 厘米，5 个字母。 先 Typst，再 Typst. 4cm，Typster，HELLOworld
2
n 等于 5，字符串也会被拼进来。
3
行内 𝑥2 + 𝑦2 = 𝑧 2 ，块级：
4
                             𝑛
5
                                   𝑛(𝑛 + 1)
6
                            ∑𝑖 =
7
                            𝑖=1
8
                                      2
9

10
数学里嵌代码：3 ⋅ 2 = 6。

（数学公式在文本抽取里会被拆散，这不影响 PDF 里的样子，第 8 篇我们会直接看渲染图。）

三种模式的规则，逐条对着这个输出看。

标记模式是默认模式。 文件开头就在标记模式：你写的字就是文字，*、_、=、- 这些有含义。这像一场普通话的对话，偶尔夹一句另一种语言，说完自动切回来：# 就是那个“我要换一种说法”的信号。

# 进入代码模式，只管一个表达式。 #w 取变量值，#name.len() 连方法调用一起吃进去（“Typst”有 5 个字母），#upper[hello] 是函数调用，方括号里是内容参数。表达式到哪里结束：标识符、字段访问和方法调用、函数调用的括号和方括号是表达式的一部分；其他字符，包括中文逗号和句号，结束它。所以 先 #name，再 #name. 里第二个 . 后面没有标识符，句号留在文字里，输出的是 Typst.。

想紧贴后面的字，用括号。 #(w + 1)cm 把 w + 1 算完得到 4，后面的 cm 原样输出，最终是 4cm。#(name)er 同理得到 Typster。没有括号写 #namer 就是在引用变量 namer，会报“unknown variable”。

#{ ... } 是代码块，[ ... ] 是内容块。 花括号里是代码模式，每一行是一条语句，let 声明变量；方括号里又回到标记模式，[n 等于 #n，] 是一段含代码的内容。块里最后那个字符串字面量也被拼进了输出：代码块把每条语句的结果“连接”（join）起来，这一点第 2 篇讲得很细。

$ ... $ 是数学模式。 美元符号紧贴内容是行内公式，美元符号与内容之间各留一个空格是块级公式（居中，单独一行）。上标 ^、下标 _、分式 /、求和 sum 都是数学模式自己的语法，和标记模式里的符号含义不同。在数学里再次嵌入代码也是 #：$#w dot 2 = #(w * 2)$ 得到 3 ⋅ 2 = 6。

这一节的规则，我压成一张表：

进入代码之后就不需要再写 # 了：#{ ... } 里面的 let、函数调用前面都没有 #，只有从方括号回到标记模式、再嵌入代码时才重新需要它（[n 等于 #n，]）。

编译失败长什么样#

我在 lab/ch01/unclosed.fail.typ 里故意写了一个忘记关闭的加粗：

1
= 标题
2

3
*忘记关闭的加粗

1
error: unclosed delimiter
2
  ┌─ lab/ch01/unclosed.fail.typ:3:0
3
  │
4
3 │ *忘记关闭的加粗
5
  │ ^

Typst 指出第 3 行第 0 列，高亮的是起始的那个 *，也就是没关的那个。make ch01 里它显示为 ok lab/ch01/unclosed.fail.typ (failed as expected)。

命令行：fonts 与 —root#

到这里已经够写一份笔记了。下面把命令行补全。typst --help 里的子命令只有这些：

1
Commands:
2
  compile      Compiles an input file into a supported output format [aliases: c]
3
  watch        Watches an input file and recompiles on changes [aliases: w]
4
  init         Initializes a new project from a template
5
  eval         Evaluates a piece of Typst code, optionally in the context of a document
6
  fonts        Lists all discovered fonts in system and custom font paths
7
  completions  Generates shell completion scripts
8
  info         Displays debugging information about Typst
9
  help         Print this message or the help of the given subcommand(s)

（我把换行折回了一行。init 在第 14、16 篇，eval 在第 16 篇。）

1
$ typst fonts | wc -l
2
284
3
$ typst fonts --ignore-system-fonts | wc -l
4
20

1
$ typst fonts --ignore-system-fonts
2
DejaVu Sans Mono
3
Libertinus Serif
4
Maple Mono NF
5
New Computer Modern
6
New Computer Modern Math
7
Noto Sans CJK HK
8
Noto Sans CJK JP
9
Noto Sans CJK KR
10
Noto Sans CJK SC
11
Noto Sans CJK TC
12
Noto Sans Mono CJK HK
13
Noto Sans Mono CJK JP
14
Noto Sans Mono CJK KR
15
Noto Sans Mono CJK SC
16
Noto Sans Mono CJK TC
17
Noto Serif CJK HK
18
Noto Serif CJK JP
19
Noto Serif CJK KR
20
Noto Serif CJK SC
21
Noto Serif CJK TC

1
$ env -u TYPST_FONT_PATHS typst fonts --ignore-system-fonts | wc -l
2
4
3
$ env -u TYPST_FONT_PATHS typst fonts --ignore-system-fonts --ignore-embedded-fonts | wc -l
4
0
5
$ SER=$(echo $TYPST_FONT_PATHS | tr ':' '\n' | grep serif)
6
$ env -u TYPST_FONT_PATHS typst fonts --ignore-system-fonts --font-path "$SER" | wc -l
7
9
8
$ env -u TYPST_FONT_PATHS typst fonts --ignore-system-fonts --ignore-embedded-fonts --font-path "$SER" | wc -l
9
5

1
proj/
2
├── common.typ
3
└── sub/
4
    └── page.typ

1
子目录里的页面。
2

3
#include "/common.typ"

1
$ typst compile sub/page.typ
2
error: file not found (searched at /tmp/t01/proj/sub/common.typ)
3
  ┌─ sub/page.typ:3:9
4
  │
5
3 │ #include "/common.typ"
6
  │          ^^^^^^^^^^^^^

1
$ typst compile --root . sub/page.typ
2
$ pdftotext sub/page.pdf -
3
子目录里的页面。
4
共用的页脚。

1
error: path `"../common.typ"` would escape the project root
2
  ┌─ sub/o.typ:1:9
3
  │
4
1 │ #include "../common.typ"
5
  │          ^^^^^^^^^^^^^^^
6
  │
7
  = hint: cannot access files outside of the project sandbox
8
  = hint: you can adjust the project root with the `--root` argument

跑一遍 make ch01#

四个选项加上 typst compile 的 --pages、--format、--ppi，就是 lab/ch01/extra.sh 做的事：它读 examples/*/main.typ，把每份成品的第一页渲染成 72 dpi 的 PNG，也就是本文开头的四张图。命令是 make ch01，它会先 make examples（编译全部成品）。第一次跑要联网：examples/ecosystem 会从 Typst Universe 下载 @preview 包（第 14 篇的内容），之后走缓存。然后它编译 lab/ch01/ 里的每个文件：

1
$ make ch01
2
typst compile examples/cv/main.typ
3
typst compile examples/ecosystem/main.typ
4
typst compile examples/homework/main.typ
5
typst compile examples/notes/main.typ
6
typst compile examples/slides/main.typ
7
./scripts/chapter.sh ch01
8
ok   lab/ch01/fig-markup.typ
9
ok   lab/ch01/hello.typ
10
ok   lab/ch01/markup-tour.typ
11
ok   lab/ch01/unclosed.fail.typ (failed as expected)

五份成品的页数（pdfinfo）：笔记 4 页，作业 1 页（homework-questions.pdf 同样 1 页），简历 1 页（中文和英文版各一页），幻灯片 17 页，ecosystem 1 页（第 14 篇的）。其中 fig-markup.typ 把一段标记源码和它的渲染结果并排放在一张图里：

它的源码有 12 行：

1
#set page(width: auto, height: auto, margin: 12pt)
2
#set text(font: ("Libertinus Serif", "Noto Serif CJK SC"), lang: "zh")
3

4
#let src = "= 标题\n*粗体* _斜体_ `code`\n- 项一\n+ 编号一\n/ 术语: 说明"
5

6
#grid(
7
  columns: 2,
8
  gutter: 1.5em,
9
  align: horizon,
10
  raw(src, lang: "typ", block: true),
11
  block(width: 6cm, eval(src, mode: "markup")),
12
)

（这里用到了 eval(src, mode: "markup")：把一个字符串当 Typst 标记来编译。第 11 篇我们会用它让 YAML 里的字符串带格式。左边源码里的 *粗体*、_斜体_ 被上了色，是 raw(..., lang: "typ") 的效果，我猜 typ 指的是 Typst 标记的高亮，没有去查。#grid、#set 都是后面几篇的内容，这里只需要看效果。）

接下来#

下一篇我们进入代码模式的内部：#let w = 3 里的 3 是什么类型，两个汉字的字符串为什么 len() 是 6 而 clusters().len() 是 2，if、for 的结果为什么能直接拼进文档。modes.typ 里那个“代码块把每条语句拼起来”的行为，到那时会有一张完整的规则表。

在那之前，你可以先把 watch 开着，自己试三件事：把 markup-tour.typ 里的 @tour 换成一个不存在的标签看错误信息；把 -- --- 换成 ---- 看它变成什么；把 #set page(width: 14cm ...) 删掉，看 Typst 的默认页面长什么样。错误信息的格式一旦认识，后面十五篇里的所有 *.fail.typ 你都读得懂。

下一篇：代码模式：值、类型与控制流。