Quarto 在 VSCode 中需先安装官方 CLI（非 npm）并验证 quarto --version，再安装官方 Quarto 扩展；若预览失败，需检查项目根目录、引用路径及端口冲突；PDF 导出问题源于 LaTeX 环境，应配置 tectonic 引擎与中文字体。
Quarto 在 VSCode 里不能直接“开箱即用”，必须装对扩展、配好命令路径，否则 quarto preview 报错或预览窗口空白是常态。
安装 Quarto CLI 和 VSCode 扩展的顺序与验证方式
VSCode 本身不内置 Quarto 支持，依赖外部 CLI 工具和官方扩展协同工作。先在系统级安装 quarto（不是 npm install -g quarto，那是错的），从 quarto.org/download 下载对应系统的 installer 运行安装。安装完后终端执行：
quarto --version
必须返回类似 1.5.56 的版本号，否则 VSCode 扩展找不到命令。再安装 VSCode 扩展：搜索 “Quarto” 并安装官方发布的 Quarto 扩展（作者是 quarto-dev）。注意别装成旧版 “Quarto Preview” 或第三方仿品。
装完重启 VSCode，打开一个 .qmd 文件，状态栏右下角应显示 Quarto: OK；若显示 Quarto: Not Found，说明 VSCode 没找到 CLI —— 此时需手动配置 quarto.executable 路径（见下一条）。
VSCode 中配置 quarto.executable 的实际路径写法
Windows 用户常卡在这步：即使 quarto --version 在 PowerShell 里能运行，VSCode 内置终端仍可能找不到。原因在于 VSCode 默认不读取系统 PATH 的全部上下文，尤其当 Quarto 安装在非标准路径时。
解决方法是显式指定可执行文件位置：
- Windows：
"quarto.executable": "C:\Program Files\Quarto\bin\quarto.exe" - macOS：
"quarto.executable": "/opt/quarto/bin/quarto"（Apple Silicon 可能是/opt/homebrew/opt/quarto/bin/quarto） - Linux：
"quarto.executable": "/usr/lib/quarto/bin/quarto"（取决于包管理器安装路径）
该配置写入 VSCode settings.json（Ctrl+, → 打开设置 → 右上角 {} 图标），不要加引号外的空格，路径斜杠方向要匹配系统习惯（Windows 用双反斜杠或正斜杠均可）。
quarto preview 启动失败的三个高频原因
点击右上角 ▶️ 预览按钮或运行命令 Quarto: Preview Document 却无响应、弹出空白浏览器页、或终端报 command not found，大概率是以下其一：
- 当前工作区根目录不是 Quarto 项目目录（即没有
_quarto.yml或_site.yml），VSCode 不会自动向上查找，必须打开包含配置文件的文件夹作为工作区 - 文档里用了
include:引用其他.qmd，但被引用文件路径错误或含中文/空格，导致渲染中断（错误日志藏在 VSCode 输出面板 → 选择 “Quarto” 通道） - 启用了 Live Server 插件并占用了
localhost:3000，而quarto preview默认也用这个端口 —— 改法：在_quarto.yml加server: {port: 4000}，或在命令面板运行Quarto: Preview Document (Custom Port)
导出 PDF 时字体缺失或公式错位怎么办
Quarto 导出 PDF 本质调用 Pandoc + LaTeX，VSCode 本身不参与编译过程，但容易误以为“插件该负责”。实际问题几乎全出在本地 LaTeX 环境：
- 没装完整 TeX 发行版（如 TinyTeX 缺少
fontspec或unicode-math宏包）：推荐用tectonic（Quarto 官方推荐）或完整安装texlive-full（Ubuntu）/MacTeX（macOS） - 中文支持失效：在
_quarto.yml中明确指定引擎和字体，例如：format: pdf: engine: tectonic fontsize: 11pt mainfont: "Noto Serif CJK SC"（确保系统已安装该字体） - 数学公式渲染异常（如 sum 显示为方块）：检查是否混用了
$...$和$$...$$，Quarto 推荐统一用$$...$$块级公式；行内公式务必用单美元符且前后留空格，如当 $x > 0$ 时
PDF 导出失败时，别只看 VSCode 弹窗提示，一定要打开输出面板 → Quarto → 查看完整 LaTeX 日志，关键错误通常在最后几行。
