Typst 快速上手：从安装到编译第一份 PDF 的完整流程
【免费下载链接】typstA markup-based typesetting system that is powerful and easy to learn.项目地址: https://gitcode.com/GitHub_Trending/ty/typst
打开终端，敲一条命令，30 秒后就能拿到第一份 PDF。Typst 是一个基于标记语言的排版系统：你写一个 .typ 文件，它编译出 PDF、HTML 或 SVG，整个工具链只有一个二进制。本文带你装好 Typst、验证环境、编译出第一份文档，并给出日常会用到的三档设置。
30 秒看懂：单二进制、零依赖、直接出 PDF
Typst 是 LaTeX 的轻量替代：写几行标记，得到排版规范的成品文档。它适合写论文的学生、写技术文档的人，以及需要程序化生成报告的开发。核心卖点是安装包就是一个静态二进制，内置常用字体，装完不改任何配置就能直接编译。
| 项目 | 说明 |
|---|---|
| 支持平台 | Windows 10+、macOS 12+、主流 Linux（x86_64 / arm64） |
| 主要依赖 | 无（字体已内嵌）；从源码构建需 Rust 1.92+ |
| 许可证 | Apache-2.0 |
| 版本来源 | 官方发布版 0.15.1，可用typst update自行升级 |
装之前自检：最低要求三条，逐行过一遍
下面三行全部满足，就直接进安装环节，不用做任何准备。
| 检查项 | 最低要求 | 说明 |
|---|---|---|
| 系统版本 | Windows 10 / macOS 12 / 主流 Linux 发行版 | 预编译二进制覆盖 x86_64 与 arm64 两大架构 |
| 磁盘空间 | 约 30 MB | 二进制本身几十 MB，另需存放产物与字体 |
| 网络 | 能访问系统包管理器源 | 仅首次下载需要，装完离线可用 |
最短路径安装：winget、brew、cargo 各一条命令
用你系统对应的官方渠道装，然后跑typst --version，看到版本号即算成功。
Windows 一键安装（winget）
winget install --id Typst.Typst装完开一个新终端验证：
typst --version预期输出：typst 0.15.1。
备选安装方式对比
| 方式 | 适用场景 | 命令 |
|---|---|---|
| Homebrew | macOS | brew install typst |
| APT / DNF | Ubuntu、Fedora 等 | sudo apt install typst |
| Pacman | Arch | sudo pacman -S typst |
| 源码构建 | 包管理器里没有二进制时 | cargo install --locked typst-cli |
编译 hello.typ，拿到你的第一份 PDF
三步：写文件、编译、看产物。成功时终端无任何输出，同目录出现hello.pdf，约 15 KB、单页。
新建hello.typ，内容如下：
= Hello 这是一个 *Typst* 文档，公式是 $E = mc^2$。执行编译命令：
typst compile hello.typ预期结果：
- 终端：无报错，命令直接退出
- 文件：同目录生成
hello.pdf，打开可见标题「Hello」、正文和行内公式
想控制输出位置，加第二个参数即可：typst compile hello.typ out/result.pdf。
日常使用循环：watch 自动编译 + 编辑器实时预览
第 1 天只需要形成「编辑 → 保存 → 预览更新」的肌肉记忆，不用背任何新命令。
第 1 天：
- VS Code 装上 Typst 扩展，打开
hello.typ，保存即自动编译，右侧直接看 PDF 预览 - 或者终端跑
typst watch main.typ，会启动本地预览服务并自动打开浏览器，改动实时生效（HTTP 服务默认开启）
日常：
- 只改 .typ 文件然后保存，watch 或扩展负责重编，单页文档通常几十毫秒出结果
- 换项目或换电脑后先跑
typst update对齐版本；新版本有问题用typst update --revert回滚
设置分三档：必配 / 推荐 / 选配，按需取用
每一档都是独立片段，拷进文档头部改一个变量即可生效。
必配：一行搞定中文字体
二进制内置的是拉丁字体，中文需要指向系统里的 CJK 字体（思源黑体/宋体或 Noto Sans CJK）。在文档顶部加这一行：
#set text(font: "Noto Sans CJK SC")拿不准字体名时，跑typst fonts看系统实际识别到的名称。
推荐：统一页面风格
长文档建议在开头集中设置一次版式，之后全文一致：
#set page(paper: "a4", margin: 2.2cm, footer: align(center)[#counter(page).display()]) #set heading(numbering: "1.")选配：团队共享字体目录
字体不在每个人机器上时，用--font-path临时加一个搜索目录：
typst compile --font-path ~/team/fonts main.typ要长期生效，就把TYPST_FONT_PATHS环境变量写进你的 shell 配置文件，效果相同。
踩坑速查表：五个高频现象与一行解法
遇到下面的症状，对号入座执行修复列即可。
| 现象 | 可能原因 | 一条修复命令或操作 |
|---|---|---|
typst: command not found | 装完没重开终端，PATH 未刷新 | 新开终端，重跑typst --version |
| 中文显示为空白方块 | 缺中文字体，或字体名拼错 | 装思源字体，文档里#set text(font: "Noto Sans CJK SC") |
| 编译报错并指出行列号 | 语法错误，括号/引号不匹配 | 按报错的行号列号直接改，Typst 报错自带精确定位 |
| 图片加载不出来 | 相对路径写错，或格式不受支持 | 核对路径；仅支持 PNG、JPEG、GIF、WebP、SVG |
| 想用新功能但没效果 | 版本过旧 | typst update升级，出问题加--revert回滚 |
Typst 对照 LaTeX：元素映射表 + 迁移设置
从 LaTeX 迁过来，按下表做心智映射，第一天就不会迷路。
| 元素 | LaTeX | Typst |
|---|---|---|
| 章节标题 | \section{...} | = 标题 |
| 加粗 / 斜体 | \textbf{...}/\emph{...} | *粗体*/_斜体_ |
| 图片 | \includegraphics{...} | #image("a.png") |
| 表格 | tabular环境 | #table(...) |
| 行内公式 | $E=mc^2$ | $E=mc^2$（写法相同） |
想保留 LaTeX 的版式手感，在文档开头放这三行：
#set page(margin: 1.75in) #set par(leading: 0.55em, spacing: 0.55em, justify: true) #set text(font: "New Computer Modern")现在可以直接开写了。卡住时按下面的仓库内文档顺序查：
- 官方教程（从零到进阶）：docs/content/tutorial/index.typ
- 文档源（函数与语法参考）：docs/
- 架构与模块说明：docs/dev/architecture.md
- 项目信息与许可证：README.md、LICENSE
【免费下载链接】typstA markup-based typesetting system that is powerful and easy to learn.项目地址: https://gitcode.com/GitHub_Trending/ty/typst
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
