Typst 安装配置指南：5 分钟搞定跨平台排版环境

Typst 安装配置指南：5 分钟搞定跨平台排版环境

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

改了一行公式，干等两分钟才出 PDF。Typst 的单次编译在几百毫秒量级，前提是你的 Typst安装与 Typst配置做对。下面把环境一次装到位：从一条安装命令到 watch 自动编译、中文字体、LaTeX 迁移，5 分钟走完，不绕弯。

30 秒跑起来 ⚡：两条命令出第一份 PDF

最短验证路径就两步：装一次、编一次，环境好坏立刻见分晓。按你的系统取对应命令，装完新开终端敲typst --version，能打印出版本号就算成功：

winget install --id Typst.Typst # Windows brew install typst # macOS cargo install --locked typst-cli # Linux，需先装 Rust 工具链

再建个空文件夹，放一个内容为= Hello的main.typ，编译它：

typst compile main.typ

成功后同目录会生成main.pdf，全程约 1 秒。这步跑通，环境已八成健康，后面全是锦上添花。

用 1 分钟认清 Typst：它是什么，边界在哪

Typst 是一个基于标记语言的排版系统：文档里直接写= 标题、*加粗*，编译器是个几十字节的静态二进制，没有 TeX Live 那种 GB 级依赖树。它与 LaTeX 的本质区别在于——LaTeX 靠宏包扩展加多遍编译，Typst 靠标记求值加一遍编译。代价是排版定制的天花板略低，但论文、报告、讲义这类日常场景完全够用。

它干不了的事也有：依赖特定 LaTeX 宏包的精细控制（比如某些学位论文模板）、跨章深度引用的超长书籍。这类任务要么留在 LaTeX，要么把文档拆小写。

🐧 分平台落地：Windows、macOS、Linux、Docker 的备选路

最短路径上一节已给（每平台一条命令）。这里补两样东西：手动下载的备选路，和装完会碰到的环境细节。四个平台共用一个收尾动作——装完打开新终端敲typst --version确认，不再重复。

Windows：手动下载后加 PATH

winget 不可用时（较老的 Win10），去发行版页面下载typst-x86_64-pc-windows-msvc.zip，解压到固定目录（如C:\typst），再把该目录追加进 PATH 环境变量。重开终端才会生效，这是最常见的"装完找不到命令"原因。

macOS：把二进制挪进 /usr/local/bin

不用 brew 的话，下载对应架构的typst-x86_64-apple-darwin或typst-aarch64-apple-darwin包，把typst可执行文件拷进/usr/local/bin，天然在 PATH 里，不需要任何额外配置。

Linux：二进制落在 ~/.cargo/bin

cargo install把二进制放进~/.cargo/bin，出现typst: command not found时，把该目录加进 PATH 即可。Arch 系用户直接pacman -S typst更省事，仓库里有预编译包。

Docker：官方镜像加挂载卷

适合 CI 和容器环境。官方镜像就出自本仓库的 Dockerfile，Alpine 基底，体积只有几十 MB：

docker run --rm -v "$(pwd):/work" -w /work typst/typst compile main.typ

把本地目录挂进容器就免去了拷贝文件；镜像内还预置了非 root 用户typst，敏感场景加--user typst激活。

从 main.typ 到 watch：把自动编译链路跑通

编译一次验证过之后，就该切到 watch 模式，别再当人肉编译器：

typst watch main.typ

这就是 Typst watch 模式实现自动编译的原理：终端里挂一个监听器，编辑器里每次保存都触发增量重编译，main.pdf原地覆盖。想让结果自动弹出，追加--open，系统默认查看器会自动打开新页面。

编辑器联动放在下一节一起配，这里只负责把"保存即更新"这条链路先跑顺。

让它真正好用：按频率从高到低做 4 件事

字体：让 Typst 看见你自己的字体库

Typst 默认扫描系统字体目录，自建字体文件夹要靠--font-path指路。先列出目录内容，确认真实族名再写进文档：

typst fonts --font-path ./fonts

永久生效就用TYPST_FONT_PATHS环境变量，多个路径用:（Linux/macOS）或;（Windows）分隔，写进~/.bashrc或系统属性：

export TYPST_FONT_PATHS="$HOME/fonts"

中文是最高频场景：思源黑体 / Noto CJK 放进字体目录后，文档顶部加一行即可：

#set text(font: "Noto Serif CJK SC")

编辑器插件：高亮、报错、预览一次到位

VS Code 装 Typst 扩展（扩展市场搜 "Typst"），打开.typ文件即得语法高亮、行内报错和预览窗口；Neovim 用户把 tinymist-lsp 指向已安装的typst二进制，体验相同。插件与终端 watch 同时开只留一个，否则两个进程抢同一份main.pdf，报错信息会互相打架。

typst.toml：3 行声明项目入口

项目目录放一个typst.toml，整个文件夹就变成一个可被引用的包：

[package] name = "my-docs" version = "0.1.0" entrypoint = "main.typ"

仓库自带文档站用的就是这种格式，见 docs/typst.toml。声明了entrypoint之后，其他项目写import "my-docs"就能直接引用。

模板：一条命令拉下标准项目

别手抄模板文件，用 init 直接从包注册表拉完整项目骨架：

typst init @preview/charged-ieee myproject

在目标目录执行，会生成带完整结构的项目文件夹，结尾还会提示下一步编译命令。个人想复用的模板，则单独写一个.typ文件，用#let函数加#content占位符，需要的地方import进来。

踩坑速查：三类高频问题，各一条命令

字体缺失：报 "no font named ..." 警告

• 症状：编译能过但全文是回退字体，或终端提示找不到某族名。
• 原因：字体文件不在任何搜索位置（系统目录或--font-path）。
• 修复：typst fonts --font-path ./fonts核对族名是否在列表里，再让文档里的名字与它逐字一致。

中文字体不生效，全是方块

• 症状：PDF 里中文全部变成 □。
• 原因：系统字体库没有 CJK 字体，或族名拼写与typst fonts输出不一致。
• 修复：先装 Noto CJK 或思源字体，再在文档头部#set text(font: "Noto Serif CJK SC")，两样齐了方块就消失。

大文档编译慢，超过 10 秒

• 症状：单次编译 10 秒以上，反复调整时体感更差。
• 原因：每次都是完整走一遍，且文档里循环、大表偏多。
• 修复：typst watch main.typ交给监听器反复构建；特别重的文档用--jobs <n>调整并行 worker 数，默认等于 CPU 核数。

LaTeX 老用户：8 行对照表完成翻译

想让观感更贴近 LaTeX 习惯，顶部加 3 行即可，其余时间都留给正文：

#set page(margin: 1.75in) #set par(leading: 0.55em, spacing: 0.55em, first-line-indent: 1.8em, justify: true) #set text(font: "New Computer Modern")

收尾：一句话感受加 4 个官方入口

总体感受是"装上即用，越用越顺"：单一二进制无依赖树，watch 自动编译，中文字体配好之后中文支持相当省心。版本旧了敲一句typst update即可自升级，不需要重新走安装流程。常用资料都在官方文档站和本仓库里：

• 官方文档入口：docs/
• 入门教程：docs/content/tutorial/
• 字体与文本参考：docs/content/reference/library/text.typ
• CLI 源码（参数细节都在这）：crates/typst-cli/

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