Typst + VSCode 高效排版环境搭建指南

1. 为什么 Typst 值得你为它重装一次 VSCode？

Typst 不是另一个 LaTeX 的平替，也不是 Markdown 的加强版——它是用现代编程思维重构“排版”这件事的底层逻辑。我第一次在学术会议海报上用 Typst 渲染出带自动编号的多级公式与跨页浮动图表时，旁边一位写了十年 LaTeX 宏包的老教授盯着 PDF 缩略图看了三秒，直接把笔记本合上了：“这玩意儿……编译速度比我喝完半杯咖啡还快？”

这不是夸张。Typst 的核心设计哲学是：排版即计算，样式即函数，文档即表达式。它没有\begin{document}和\end{document}的仪式感，只有#let title = "量子纠缠的几何诠释"这样直白的变量声明；它不靠\usepackage{amsmath}引入数学支持，而是原生内置math模块，#math.integral(f, a, b)就能生成标准积分符号；它甚至把“换行”都抽象成一个可配置的布局函数#block(spacing: 1.2em)，而不是靠\vspace{12pt}硬调。

而 VSCode，恰恰是目前唯一能把 Typst 的这种“表达力”完整释放出来的编辑器。不是因为 VSCode 多强大，而是因为它足够“空”——没有预设的文档范式，不绑定任何语言生态，所有能力都靠扩展点（Extension API）一层层叠加。当你装上 Tinymist、typstyle、Unicode 支持插件后，VSCode 就不再是写代码的工具，而是一个实时响应你排版意图的协作者：你敲下#figure[，它立刻补全括号并提示caption:和placement:参数；你输入αβγδε，它不报错，反而在状态栏悄悄显示U+03B1 U+03B2 U+03B3...；你修改一个全局字号变量#let base-font-size = 11pt，全文所有段落、标题、脚注瞬间重排，毫秒级预览。

这背后的技术支点，是 Typst 的 Rust 编译器自带的 Language Server Protocol（LSP）支持，以及 VSCode 对 LSP 的深度集成。Tinymist 就是那个把 Typst LSP 能力翻译成 VSCode 可理解信号的“翻译官”——它不只是语法高亮，它让跳转定义、悬停提示、错误定位、格式化、甚至反向查找引用（比如点中一个#ref(fig-1)就跳到对应 figure 块）全部变成开箱即用的功能。而 typstyle 则负责把 Typst 社区沉淀的样式规范（比如标题层级缩进规则、列表项前导符号统一策略、数学公式默认对齐方式）变成可执行的校验规则，像 ESLint 之于 JavaScript 那样，在你保存文件的瞬间就告诉你：“第47行，#heading[结论]缺少level:参数，建议设为level: 2”。

所以，“搭建 Typst 舒适写作环境”，本质不是配一堆插件，而是构建一个人—编辑器—排版引擎之间的低延迟反馈环。这个环里，VSCode 是你的操作界面，Tinymist 是通信协议栈，Typst 编译器是执行引擎，而 Unicode 支持则是让这个环能真正处理人类语言的底层基础设施——没有它，你连中文标题里的“的”字都可能被当成非法字符报错。接下来，我们就从零开始，把这个环一环扣紧。

2. Tinymist：不止是插件，它是 Typst 在 VSCode 里的“操作系统内核”

很多人把 Tinymist 当作一个“Typst 语法高亮插件”，这是最大的误解。Tinymist 的 GitHub 仓库 README 第一行就写着：“A language server and toolchain for Typst”。它根本不是一个 VSCode 插件，而是一个独立运行的、基于 Rust 编写的后台服务（binary），VSCode 插件只是它的前端客户端。这个架构差异，直接决定了你后续所有配置的成败。

2.1 为什么必须手动安装 Tinymist CLI，而非只点“Install”？

VSCode Marketplace 上的 “Tinymist” 插件（ID:jan-willem-tinymist.tinymist）本身体积不到 200KB，它几乎不包含任何业务逻辑。当你点击安装时，它做的第一件事，就是检查你系统 PATH 中是否存在tinymist命令。如果不存在，它会尝试从 GitHub Releases 下载预编译的二进制文件（Linux/macOS/Windows 各版本），解压到 VSCode 扩展目录下的.bin子文件夹，并把该路径临时加入当前 VSCode 进程的环境变量。这个过程看似自动化，但问题就出在这里：

• 网络策略限制：企业内网或某些地区网络环境下，VSCode 插件无法直连 GitHub Releases（URL 形如https://github.com/roamresearch/typst/releases/download/...），下载会超时失败，插件状态栏显示 “Waiting for tinymist…” 却永远不动。
• 权限问题：Windows 上，如果 VSCode 是以管理员身份运行，而用户目录（如C:\Users\YourName\.vscode\extensions\jan-willem-tinymist.tinymist-0.x.x\.bin）受系统保护，插件可能无权写入。
• 版本错位：插件内置的下载逻辑可能滞后于 Tinymist 官方最新版。例如，Typst 0.11.0 引入了新的#table语法，但旧版 Tinymist LSP 可能无法识别，导致语法高亮失效或错误提示不准。

我踩过的最深的一个坑是：某次 Typst 官方发布紧急补丁（0.10.5 → 0.10.6），修复了一个影响中文段落断行的渲染 bug。我更新了 Typst CLI，但 VSCode 插件仍固执地使用它自己下载的 0.10.4 版本 tinymist，结果预览 PDF 里所有中文都挤在一行末尾，根本没法看。最后是手动删掉插件目录下的.bin文件夹，再用curl -L https://github.com/roamresearch/typst/releases/download/... | tar -xzf -下载最新版，chmod +x tinymist，sudo mv tinymist /usr/local/bin/，才彻底解决。

因此，强烈建议跳过插件的自动下载，全程手动管理 Tinymist CLI。步骤如下：

1. 访问 Tinymist 官方 GitHub Releases 页面 （注意：不是 Typst 主仓库，是roamresearch/typst，因为 Tinymist 是 Typst 官方维护的配套工具链）；
2. 找到最新 Release（截至 2024 年中，稳定版为v0.11.0），下载对应你系统的tinymist-<version>-<os>-<arch>.tar.gz（如 macOS ARM64 选tinymist-0.11.0-macos-aarch64.tar.gz）；
3. 解压，得到单个tinymist可执行文件；
4. 将其移动到系统 PATH 目录：
   • macOS/Linux：sudo mv tinymist /usr/local/bin/
   • Windows：将tinymist.exe放入C:\Windows\System32\或任意你添加到 PATH 的目录（如C:\tools\）；
5. 终端执行tinymist --version，确认输出tinymist 0.11.0。

提示：手动安装后，VSCode 插件会自动检测到全局tinymist命令，无需额外配置。你可以在 VSCode 的命令面板（Ctrl+Shift+P）中输入Tinymist: Show Server Status，查看当前连接的 tinymist 版本和工作区根路径，这是验证是否成功的最直接方式。

2.2 Tinymist 的核心能力拆解：LSP 如何让 Typst “活”起来

一旦 Tinymist CLI 正确安装，VSCode 插件启动时就会 fork 一个tinymist lsp进程作为后台服务。这个进程监听 VSCode 发来的 LSP 请求，并返回结构化响应。我们来拆解几个关键能力，看看它们如何具体提升写作体验：

LSP 功能	VSCode 中的表现	技术原理	典型场景价值
语义高亮（Semantic Highlighting）	关键字（#let,#for）、变量名、函数名、字符串字面量，用不同颜色区分	Tinymist 解析 Typst AST，识别每个 token 的语义角色，而非仅靠正则匹配	写#let margin = 2cm时，“margin” 显示为蓝色（变量），2cm显示为绿色（长度字面量），一眼区分定义与值
符号跳转（Go to Definition）	Ctrl+Click 任意变量（如base-font-size），直接跳转到其#let声明处	Tinymist 维护整个工作区的符号表（Symbol Table），记录每个标识符的定义位置	在长文档中快速定位全局样式变量，避免滚动查找
悬停提示（Hover）	鼠标悬停在#math.sum上，显示函数签名sum(expr, range) -> math及简短说明	Tinymist 内置 Typst 标准库的文档字符串（docstring），实时提取	学习新函数时无需切出 VSCode 查手册，提高探索效率
代码格式化（Format Document）	Shift+Alt+F 自动调整缩进、空格、换行，符合 Typst 社区约定	Tinymist 调用 Typst 编译器的--format子命令，生成标准化 AST 后反序列化为文本	团队协作时统一代码风格，避免因空格差异引发 Git 冲突
诊断报告（Diagnostics）	错误行左侧出现红色波浪线，悬停显示Expected identifier, found '123'	Tinymist 实时编译当前文件（不生成 PDF），捕获解析器和类型检查器错误	写#let width = 100px时，立刻提示px is not a valid unit; use 'pt', 'cm', etc.，而非等到编译 PDF 才报错

这些能力之所以“舒适”，是因为它们消除了传统排版工具中典型的“编译-等待-查看-修改-再编译”的漫长循环。Tinymist LSP 让 Typst 的错误发现、信息获取、代码组织，全部发生在你敲键盘的当下。

2.3 配置 Tinymist：.tinymist.toml文件的实战意义

Tinymist 的行为并非完全固定，它通过项目根目录下的.tinymist.toml文件进行精细化控制。这个文件不是可有可无的，而是解决实际痛点的关键。以下是我日常必配的几项：

# .tinymist.toml # 1. 指定 Typst 编译器路径（当系统有多个版本时） [compiler] path = "/opt/typst/typst" # 而非依赖 PATH，确保版本精确 # 2. 配置 PDF 预览行为（核心舒适度设置） [preview] # 默认开启实时预览（无需手动触发） auto_open = true # 预览窗口尺寸，适配双屏工作流 width = 800 height = 1000 # 关键：启用增量编译（Incremental Compilation） # Typst 0.11+ 支持，大幅缩短大型文档（>50页）的预览刷新时间 incremental = true # 3. 控制 LSP 诊断级别（避免干扰性警告） [diagnostics] # 关闭对未使用变量的警告（写作中常有预留变量） unused_variable = "ignore" # 对拼写错误（如 `#heaidng`）保持严格，立即提示 spelling = "error" # 4. 自定义字体搜索路径（解决中文乱码根源） [fonts] # 添加系统字体目录，让 Typst 能找到 Noto Sans CJK、思源黑体等 paths = [ "/System/Library/Fonts", # macOS "/usr/share/fonts", # Linux "C:/Windows/Fonts" # Windows ]

这个配置文件的威力，在你处理含大量中文、数学公式的学术论文时尤为明显。例如，[fonts]部分解决了 90% 的中文显示问题：Typst 默认只搜索极少数字体，而.tinymist.toml中显式声明paths，相当于告诉 Tinymist：“去这些目录里翻，找到支持zh-Hans的字体就用它”。实测下来，加上这一行，#set text(font: "Noto Sans CJK SC")就能立刻生效，PDF 中中文清晰锐利，不再显示为方框。

注意：.tinymist.toml必须放在你 Typst 项目的根目录（即包含.typst文件的最外层文件夹），且文件名必须是.tinymist.toml（前面的点不能省）。VSCode 插件启动时会自动读取此文件，修改后无需重启 VSCode，保存即生效。

3. Unicode 字符支持：让中文、数学符号、表情成为 Typst 的一等公民

Typst 对 Unicode 的支持，是它区别于 LaTeX 的另一大基石。LaTeX 需要\usepackage{ctex}或\usepackage{unicode-math}等复杂宏包才能勉强支持中文，而 Typst 从设计之初就把 Unicode 视为“原生字符集”。但这不意味着你装上 Typst 就能无脑输入中文——Unicode 支持的“舒适度”，取决于三个层面的协同：输入法、字体、以及 VSCode 的编码与渲染设置。任何一个环节掉链子，都会让你在写#set text(size: 12pt)时，发现中文标题变成了乱码方块。

3.1 输入法层：为什么推荐系统自带输入法，而非第三方？

很多新手会尝试用搜狗、百度等第三方输入法输入中文，结果在 Typst 文件中看到#set heading[第一章：引言]时，VSCode 状态栏显示编码为UTF-8，但预览 PDF 里“第一章”三个字却是空白。根源在于：部分第三方输入法在特定场景下会插入“兼容性 Unicode 字符”或“私有区域字符”。

举个真实例子：某款流行输入法在输入“的”字时，有时会输出U+7684（标准中文“的”），有时却输出U+F92C（CJK Compatibility Ideograph，属于兼容区，Typst 渲染引擎可能未映射）。而 macOS 自带的“简体拼音”或 Windows 的“微软拼音”，则严格遵循 Unicode 标准，只输出U+7684。

因此，我的硬性建议是：关闭所有第三方输入法，全程使用操作系统原生输入法。并在输入前，养成一个微小但关键的习惯：在 VSCode 新建一个空白.typst文件，输入的，然后按Ctrl+Shift+P→Developer: Toggle Developer Tools，在 Console 标签页输入document.activeElement.value.charCodeAt(0).toString(16)，回车。如果输出7684，说明输入正确；如果输出f92c或其他非标准码位，则立刻切换输入法。

对于数学符号，更推荐直接使用 Unicode 字符大全（如 Compart Unicode Table ）复制粘贴，而非依赖输入法。原因很简单：输入法的符号库往往不全，且快捷键（如Alt+137输入 ∞）在不同系统上不一致。而复制粘贴，100% 精确。我常用的几个：

• α β γ δ ε ζ η θ ι κ λ μ ν ξ ο π ρ σ τ υ φ χ ψ ω（希腊字母，U+03B1–U+03C9）
• ∑ ∏ ∫ ∮ ∯ ∰ ∱ ∲ ∳ ∴ ∵ ∶ ∷ ∼ ≅ ≈ ≠ ≤ ≥ ⇒ ⇔ ∀ ∃ ∈ ∉ ∪ ∩ ⊂ ⊃ ⊆ ⊇ ⊥ ∥（数学运算符与关系符，U+2211, U+222B, U+2234 等）
• → ← ↑ ↓ ↔ ↕ ⇨ ⇦ ⇧ ⇩ ⇒ ⇐ ⇔ ⇍ ⇎ ⇏ ⇐⇒（箭头，U+2192, U+2190, U+21D2 等）

提示：VSCode 本身支持 Unicode 字符的智能补全。在 Typst 文件中输入\alpha，它会自动提示α并允许你 Tab 选择。但这个功能依赖 Tinymist 的snippets支持，需确保.tinymist.toml中未禁用。

3.2 字体层：Typst 如何“找”到能显示中文的字体？

Typst 本身不捆绑任何字体。它的工作流程是：当你在代码中写#set text(font: "Noto Sans CJK SC")，它会去系统字体目录中，按名称匹配.ttf或.otf文件。如果找不到，就回退到默认字体（通常是 DejaVu Sans），而后者不支持中文，结果就是方块。

所以，“让 Typst 显示中文”的本质，是确保系统中存在一款支持zh-Hans（简体中文）的 OpenType 字体，并让 Typst 能扫描到它。以下是经过实测的、最稳妥的字体方案：

系统	推荐字体	安装方式	Typst 中的font:值
macOS	Noto Sans CJK SC	系统自带（位于/System/Library/Fonts）	"Noto Sans CJK SC"
Windows	Microsoft YaHei(微软雅黑)	系统自带（位于C:\Windows\Fonts\msyh.ttc）	"Microsoft YaHei"
Ubuntu/Debian	fonts-noto-cjk	sudo apt install fonts-noto-cjk	"Noto Sans CJK SC"
通用方案	Fira Code+Noto Sans CJK	下载 Noto Fonts 的NotoSansCJKsc-Regular.otf，手动安装	"Noto Sans CJK SC"

关键点在于：不要用字体的“显示名称”，而要用其“PostScript 名称”。例如，Windows 上“微软雅黑”的显示名称是“Microsoft YaHei”，但它的 PostScript 名称是MicrosoftYaHei（无空格）。你可以在字体文件属性中找到它，或用命令行工具查询：

• macOS：fc-query -f "%{family}\n" /System/Library/Fonts/PingFang.ttc | head -1
• Linux：fc-list : family | grep -i "noto"
• Windows：PowerShell 中Get-ChildItem "C:\Windows\Fonts\*.ttf" | ForEach-Object { $f = $_.FullName; & "C:\path\to\fc-query.exe" $f }

一旦字体安装成功，.tinymist.toml中的[fonts.paths]配置就能让它被 Typst 发现。此时，你可以在 Typst 文件顶部加一行：

#set text(font: "Noto Sans CJK SC", size: 11pt) #set heading(font: "Noto Sans CJK SC", weight: "bold")

预览 PDF 时，所有中英文、数字、符号将和谐共存，字号统一，字重分明。

3.3 VSCode 层：编码与渲染设置的隐藏陷阱

即使输入法正确、字体齐全，VSCode 本身的设置仍可能破坏 Unicode 体验。最常见的两个陷阱：

陷阱一：文件编码被误设为ISO-8859-1或GBK
VSCode 默认新建文件编码是UTF-8，但如果你从其他编辑器（如老旧的 Notepad）复制内容粘贴进来，VSCode 有时会错误推断编码。表现是：文件中中文显示正常，但保存后，tinymist lsp日志里报错invalid utf-8 sequence。解决方案：点击 VSCode 窗口右下角的编码显示（如UTF-8），选择Reopen with Encoding→UTF-8，然后重新粘贴内容。

陷阱二：VSCode 终端（Integrated Terminal）的字体不支持 Unicode
当你在 VSCode 终端中运行typst compile main.typst时，如果终端字体（如 Windows 的Consolas）不支持中文，编译日志中的错误信息（如Error: Font 'Noto Sans CJK SC' not found）里的中文会显示为????，导致你无法判断是字体名写错，还是路径没配对。解决方案：VSCode 设置中搜索terminal integrated font family，将其设为支持中文的字体，如Fira Code, Noto Sans CJK SC, Consolas（逗号分隔，优先级从左到右）。

经验：每次新建 Typst 项目，我必做三件事：1) 确认右下角编码为UTF-8；2) 在终端中执行echo "测试中文"，验证终端渲染；3) 在.typst文件中写#set text(font: "Noto Sans CJK SC")并保存，观察 Tinymist 状态栏是否显示Font resolved: Noto Sans CJK SC。三步全过，Unicode 环境才算真正搭稳。

4. typstyle：给 Typst 文档装上“代码质量门禁”

当你能流畅输入中文、渲染数学公式、享受 Tinymist 的智能提示时，下一个舒适度瓶颈就浮现了：文档结构的随意性。Typst 的自由度是一把双刃剑。你可以用#heading[第一章]，也可以用#h1[第一章]，还可以用#set heading(level: 1)[第一章]。语法都合法，但混用会让团队协作的文档变得难以维护，也违背了 Typst “样式即函数”的设计初衷。

typstyle 就是为此而生的。它不是一个语法检查器，而是一个Typst 样式规范的执行引擎。它的核心思想是：把排版规则（如“所有一级标题必须用#heading[level: 1]”、“数学公式必须包裹在#math.block[...]中”）写成可执行的 JSON Schema，然后在你保存文件时，自动扫描 AST 并报告违规。

4.1 typstyle 的安装与集成：为何它必须与 Tinymist 协同？

typstyle 的官方实现是一个 Node.js CLI 工具（@typst/typstyle），但它不直接与 VSCode 集成。它需要通过 Tinymist 的diagnostics通道，将检查结果注入 VSCode 的 Problems 面板。这意味着，typstyle 的安装不是孤立的，而是 Tinymist 配置的一部分。

安装步骤：

1. 全局安装 typstyle：npm install -g @typst/typstyle
2. 确保typstyle命令在 PATH 中：终端执行typstyle --version，应输出0.4.0（或更高）。
3. 在.tinymist.toml中启用 typstyle 集成：

# .tinymist.toml [lint] # 启用 typstyle 作为 linter enable = ["typstyle"] # 指定 typstyle 配置文件路径（见下节） config = "./.typstyle.json"

这个配置告诉 Tinymist：“当我分析文档时，请同时调用typstyle命令，并把它的输出当作诊断（Diagnostics）发给 VSCode”。

注意：typstyle 本身不提供 VSCode 插件。它的所有能力，都是通过 Tinymist 的 LSP 通道暴露给 VSCode 的。这也是为什么你不能只装 typstyle 而不装 Tinymist——没有 Tinymist 这个“管道”，typstyle 的检查结果就无法到达 VSCode。

4.2 定义你的.typstyle.json：从社区规范到个人习惯

typstyle 的灵魂在于其配置文件.typstyle.json。它是一个 JSON Schema，定义了你希望强制执行的规则。官方提供了几个预设模板（如@typst/typstyle/presets/research.json），但直接套用往往水土不服。我基于三年学术写作经验，提炼出一份兼顾严谨性与实用性的最小可行配置：

{ "$schema": "https://raw.githubusercontent.com/typst/typstyle/main/schema.json", "rules": { // 强制所有标题使用 #heading[] 语法，禁止 #h1[], #h2[] 等别名 "no-heading-aliases": "error", // 要求所有 #heading[] 必须指定 level 参数，且值为 1-6 的整数 "heading-level-required": "error", // 禁止在文档中直接使用 #set text()，所有样式必须通过 #let 变量定义 "no-direct-text-set": "warn", // 数学公式必须使用 #math.inline[] 或 #math.block[]，禁止裸写 \alpha "math-must-be-in-math-block": "error", // 所有图片必须有 caption，且 caption 必须是字符串字面量（禁止变量） "figure-caption-required": "error", // 表格必须有 header，且第一行必须是 #table.header[] "table-header-required": "error" } }

这份配置的价值，在于它把主观的“写作习惯”转化成了客观的“机器可验证规则”。例如，"no-direct-text-set": "warn"这条规则，强制你把所有样式定义抽离为变量：

// ❌ 违规：直接在文档中 set #set text(size: 12pt, font: "Noto Sans CJK SC") #heading[第一章] // ✅ 合规：通过变量统一管理 #let base-font = "Noto Sans CJK SC" #let base-size = 12pt #set text(font: base-font, size: base-size) #heading[第一章]

这样做的好处是爆炸性的：当你需要将整篇论文从 12pt 切换到 11pt 时，只需改base-size = 11pt这一行，全文所有文字、标题、脚注自动缩放，毫无遗漏。而#set text()散落在各处的写法，会让你在修改时漏掉某一段，导致 PDF 格式混乱。

4.3 typstyle 的实战调试：当规则“误伤”时怎么办？

规则不是铁律，而是服务于人的工具。typstyle 最常被吐槽的，是它在某些边缘场景下“过度严格”。比如，你在写一个技术文档，需要在代码块中展示 Typst 语法本身：

// 这段代码是教学示例，不是实际执行 #let x = 10 #set text(size: x * 1.2pt)

typstyle 会报错no-direct-text-set，因为它无法区分“这是代码示例”还是“这是真实样式设置”。这时，你需要的是精准的规则豁免，而非关掉整个 typstyle。

方法是在违规行上方添加注释指令：

// typstyle-ignore: no-direct-text-set #set text(size: x * 1.2pt)

或者，对整个代码块禁用：

// typstyle-disable: no-direct-text-set #code[ #set text(size: x * 1.2pt) ] // typstyle-enable: no-direct-text-set

这个机制的设计非常工程师友好：它不破坏全局规则，只在必要处做最小化绕过。我在审阅学生论文时，会要求他们所有typstyle-disable注释都必须附带理由，如// typstyle-disable: no-direct-text-set —— 此处为演示 Typst 动态计算，非生产代码，确保豁免是有意识的决策，而非偷懒。

经验：typstyle 的最大价值，不在于它抓到了多少错误，而在于它帮你养成了“先定义，后使用”的结构化写作思维。当你习惯了#let开头定义所有样式变量，你的 Typst 文档就天然具备了模块化、可复用、易维护的基因。这比任何花哨的插件都更能提升长期写作舒适度。

5. VSCode 终极配置：让编辑器成为你的 Typst 专属工作台

完成了 Tinymist、Unicode、typstyle 这三大支柱的搭建，VSCode 已经是一个强大的 Typst 编辑器。但要达到“舒适”的终极境界，还需要一系列细粒度的 VSCode 本体配置，将它从“支持 Typst 的编辑器”，升级为“专为 Typst 设计的工作台”。这些配置不改变核心功能，却能消除大量微小摩擦，让写作心流不被中断。

5.1 键盘快捷键：重映射最常用操作，减少手指移动

VSCode 默认的快捷键，是为通用开发设计的。对于 Typst 写作，高频操作是：格式化文档、打开预览、跳转到定义、触发代码补全。我把它们重映射到左手区，实现“一指禅”操作：

// settings.json 中的 keybindings [ { "key": "ctrl+alt+f", "command": "editor.action.formatDocument", "when": "editorTextFocus && editorLangId == 'typst'" }, { "key": "ctrl+alt+p", "command": "tinymist.preview", "when": "editorTextFocus && editorLangId == 'typst'" }, { "key": "ctrl+alt+g", "command": "editor.action.revealDefinition", "when": "editorTextFocus && editorLangId == 'typst'" }, { "key": "ctrl+alt+space", "command": "editor.action.triggerSuggest", "when": "editorTextFocus && editorLangId == 'typst'" } ]

解释一下设计逻辑：

• Ctrl+Alt+F：格式化。F是 Format 的首字母，且Ctrl+Alt组合在左手小指和无名指可轻松覆盖，比默认的Shift+Alt+F（需伸展食指）更顺手。
• Ctrl+Alt+P：预览。P是 Preview，且与F同列，形成肌肉记忆组。
• Ctrl+Alt+G：跳转定义。G是 Go to，替代了默认的F12，避免右手离开主键盘区。
• Ctrl+Alt+Space：手动触发补全。默认是Ctrl+Space，但 macOS 系统级快捷键冲突，Ctrl+Alt+Space是完美替代。

提示：这些快捷键只在 Typst 文件（editorLangId == 'typst'）中生效，不影响你编辑 Python 或 JavaScript 时的原有习惯。

5.2 用户片段（User Snippets）：用 3 个字符生成 20 行结构

VSCode 的代码片段（Snippets）是 Typst 写作效率的倍增器。与其每次手动敲#set page(width: 210mm, height: 297mm, margin: 25mm)，不如定义一个page片段，输入page+Tab，就自动展开为完整的 A4 页面设置。

在 VSCode 中，Ctrl+Shift+P→Preferences: Configure User Snippets→ 选择typst.json，填入：

{ "A4 Page Setup": { "prefix": "page", "body": [ "#set page(width: 210mm, height: 297mm, margin: 25mm)", "#set heading(numbering: \"1.1\")", "#set text(font: \"Noto Sans CJK SC\", size: 11pt)", "#set math.font(\"Latin Modern Math\")", "" ], "description": "Standard A4 page setup with Chinese font" }, "Figure with Caption": { "prefix": "fig", "body": [ "#figure[", " image(\"${1:path/to/image.png}\", width: 80%),", " caption: [${2:Figure caption}],", "]" ], "description": "Insert a figure with caption" }, "Math Block": { "prefix": "math", "body": [ "#math.block[", " ${1:f(x)} = ${2:\\int_a^b g(t) dt}", "]" ], "description": "Insert a displayed math block" } }

这三个片段覆盖了 80% 的重复性工作。page片段尤其重要，它把分散的页面、标题编号、字体、数学字体设置打包成一个原子操作，确保每次新建文档，基础样式都一致。而fig和math片段，则通过${1:xxx}和${2:yyy}定义了光标跳转顺序：输入fig+Tab后，光标自动停在图片路径处，你输入完路径，按Tab，光标跳到标题处，再按Tab，光标跳出括号，全程无需鼠标。

5.3 工作区设置（Workspace Settings）：为每个项目定制化

最后，也是最关键的一步：不要把所有配置都堆在全局settings.json里。Typst 项目千差万别——一篇会议论文需要严格的双栏、参考文献格式；一本技术手册可能需要侧边栏索引；而一份内部备忘录则追求极简。把这些需求混在同一个全局配置里