企业官网建设流程全解析

Typst 安装配置上手：从一条命令到出 PDF 的四站路

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

第一次接触 Typst 安装配置的朋友，常见路线是：Windows 上走 winget，macOS 走 Homebrew，Linux 用发行版自带的包管理器装好，然后跑一条编译命令，再处理一次中文字体。整条路走下来，顺利的话十分钟，卡住的话卡点也集中在这四站里。

第 1 站：环境怎么装

三台机器的命令，一张表：

第一条命令用来装 Windows 版的 Typst 并确认装上了：

winget install --id Typst.Typst typst --version

第二条命令是"包管理器里没有 Typst"时的兜底——用 Rust 工具链直接从源码编译 CLI：

cargo install --locked typst-cli

装完只看一件事：typst --version能打出版本号。这个仓库当前迭代到 0.15.1 线，你看到的版本低一两个小版本都很正常。

下一步：把一份测试文档放进来，走第 2 站的第一次编译。

第 2 站：第一次编译报错怎么办

先用最省事的姿势建项目骨架（自动建好main.typ和typst.toml），再编译它：

typst init demo cd demo typst compile main.typ out.pdf

出错了怎么排查，按现象对号入座：

• No such file or directory：路径基准是"当前工作目录"，不是文档所在目录。要么cd进项目目录再跑，要么在 crates/typst-cli/src/args.rs 里查到的--root参数指定根目录。
• Unknown font：你#set text(font: ...)里写的字体名系统里没有，跳到第 3 站处理。
• Undefined function：Typst 没有\前缀语法，函数调用一律#开头，比如#image(...)。

改对了怎么验证？编译时把out.pdf换成-，输出格式自动选控制台可读形式，或者直接在终端看 Typst 的报错行号——它给的位置信息相当精确，行、列都标了。

下一步：文档里出现中文？直接进第 3 站。

第 3 站：中文字体缺失怎么修

现象固定：正文中文变成一排方框，或者报错font not found。原因就一个——Typst 默认只搜系统字体目录，你文档里指定的中文字体（如 Source Han Serif CN）不在搜索范围内。

修复动作分两步。第一步，把字体文件放进系统目录（Linux 是~/.fonts，macOS 是~/Library/Fonts），或者用--font-path临时指过去。第二步，确认 Typst 真的看到字体了：

typst fonts

这条命令列出当前所有能被识别的字体，你在输出里搜一下 "Source Han"，搜到了再回到文档里#set text(font: "Source Han Serif CN")。

不想改系统目录的话，--font-path背后读的是环境变量TYPST_FONT_PATHS（多个路径用系统分隔符隔开，Unix 上是:，Windows 上是;），写进 shell 配置里就是"永久配置"。这个对应关系可以直接在 crates/typst-cli/src/args.rs 里找到佐证。

下一步：中文渲染正常后，把 Typst 接进日常编辑流。

第 4 站：编辑器与持续编译

装个 Typst 语言服务器（社区项目 tinymist），编辑器里的补全、跳转、实时预览就有了，具体装法见 docs/src/reflect.rs 同目录下的官方文档站说明，这里不展开。

CLI 侧真正值得记住的是一条增量编译命令——改完保存，PDF 自动重出，不用手动敲 compile：

typst watch main.typ

它监视源文件和它#import的所有依赖，大文档改一页只重排受影响的部分，体感上比"全量重编"快一个量级。配合typst update做自升级（带--backup-path可以留升级前备份），日常闭环就齐了。

下一步：对照下面这张表，把你 LaTeX 习惯里的写法平移过来。

LaTeX 写法平移对照

数学公式两边几乎一样，$E=mc^2$直接照抄。习惯项：Typst 的\是转义符，函数一律#前缀，这是从 LaTeX 迁移时唯一需要"戒掉"的本能。

下一步：文档写长了，拆模块用#import，而不是硬塞进一个文件。

卡点去哪问

• Typst 官方 Discord 社区：编译报错、字体疑难先抛这里
• GitHub 仓库 Issues 区：复现步骤 +typst --version输出，两条齐全响应最快
• 官方文档参考页：docs/content/reference/index.typ 对应的线上站点

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