Typst 快速安装与配置指南：5 步跑通 PDF 编译

Typst 快速安装与配置指南：5 步跑通 PDF 编译

【免费下载链接】typstA markup-based typesetting system that is powerful and easy to learn.项目地址: https://gitcode.com/GitHub_Trending/ty/typst

Typst 是一套把.typ源文件直接编译成 PDF 的标记语言排版系统。这篇文章带你完整走一遍 Typst 安装：用一条命令装好、用一个 5 行文档验证能编译、配好编辑器，再解决字体、中文、watch 三个高频问题，最后掌握模板复用和 Typst 配置里的典型细节。

按平台一条命令装好

装完打开终端，运行：

typst --version

会看到形如typst 0.15.1的版本号。如果终端提示找不到命令，说明 PATH 没配对，重开一次终端再试。如果你的发行版没有 typst 包，也可以从官方 release 页手动下载对应平台的二进制，或按仓库根目录提供的 Dockerfile 搭容器环境，这里不展开。

第一件事：编译一个 5 行文档验证

新建main.typ，写入：

= 你好，Typst 这是我的第一份 *Typst* 文档。 $ E = mc^2 $

回到终端，运行：

typst compile main.typ typst watch main.typ

✅ 如果同目录下生成了main.pdf、终端没有任何报错，说明 Typst 编译 PDF 的链路已完全打通；打开 PDF 能看到标题、一行加粗正文和一个行内公式。出错时终端会给出文件名、行号和列号，照着改即可。typst watch main.typ会持续监听文件变化，保存一次重编一次，终端显示 "completed" 即完成一轮；以后想升级，官方二进制直接运行typst update即可，包管理器装的版本则走对应包管理器。

编辑器搭配：VS Code 为主

日常写作推荐 VS Code：在扩展市场搜索并安装官方 "Typst" 扩展，它会自动调用系统 PATH 里的 typst 可执行文件。打开.typ文件后启动预览，保存时文档实时重编，等价于内置的 watch 模式。如果你的 typst 不在 PATH 里，把可执行文件的完整路径填进扩展设置项typst.compilerPath就行。

其他编辑器基本都是一行配置的事：

最常见的三个坑

提示找不到字体？

Typst 按"字体族名称"精确匹配，你在set text(font: ...)里写的名字必须和系统里注册的名称一字不差，包括大小写。先运行typst fonts列出当前所有可用字体，从输出里挑名字填进文档；字体放在自定义目录时，加--font-path参数临时告诉它去哪找。

中文显示成方块？

原因是系统里没有覆盖中文的字体。装一个开源中文字体（如思源黑体/思源宋体）放入系统字体目录：Linux 放~/.fonts，macOS 放~/Library/Fonts，然后重新编译；字体暂时不想装进系统的话，编译时指定目录：

typst fonts --font-path ./fonts typst compile --font-path ./fonts main.typ

想让自定义目录长期生效，Typst 字体配置可以走环境变量：

export TYPST_FONT_PATHS="$HOME/fonts"

写进 shell 的启动文件后，编译和 watch 都会自动带上这个目录。不确定当前生效了哪些字体路径时，运行typst info可以看到完整的字体路径列表。

watch 不自动刷新？

typst watch监听的是磁盘上的文件变化，编辑器里没保存（没按 Ctrl/Cmd+S）的修改它感知不到；另外确认你是在包含.typ文件的那个目录里启动的 watch。两个条件都满足后，保存一次终端会打印 "completed"，PDF 随之更新。

进阶两步：模板复用与包声明

模板复用靠#let定义函数、#import引入。把页眉逻辑抽到单独文件：

// report.typ #let report(title, content) = { set page(margin: 1.8cm) align(center)[#text(22pt, weight: "bold")[#title]] v(0.5em) content }

主文档两行接入：

#import "report.typ": report #show: report("周报")

如果这个模板要发给别人用，就在项目根目录放一个typst.toml声明包信息，这是 Typst 配置里标准包结构的入口：

[package] name = "report" version = "0.1.0" entrypoint = "./report.typ"

LaTeX 用户快速对照

从装好到编译，Typst 的工作流就是两条命令加一个会报行号的错误提示，比 LaTeX 工具链轻得多。想继续深入，可以看 官方教程、LaTeX 用户迁移指南 和 完整语法参考。

【免费下载链接】typstA markup-based typesetting system that is powerful and easy to learn.项目地址: https://gitcode.com/GitHub_Trending/ty/typst