VSCode如何使用Quarto科学文档编写_VSCode Quarto科学文档编写总结-VSCode-PHP中文网

quarto 在 vscode 中需先安装官方 cli（非 npm）并验证 quarto --version，再安装官方 quarto 扩展；若预览失败，需检查项目根目录、引用路径及端口冲突；pdf 导出问题源于 latex 环境，应配置 tectonic 引擎与中文字体。

vscode如何使用quarto科学文档编写_vscode quarto科学文档编写总结

Quarto 在 VSCode 里不能直接“开箱即用”，必须装对扩展、配好命令路径，否则 quarto preview 报错或预览窗口空白是常态。

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 路径（见下一条）。

Windows 用户常卡在这步：即使 quarto --version 在 PowerShell 里能运行，VSCode 内置终端仍可能找不到。原因在于 VSCode 默认不读取系统 PATH 的全部上下文，尤其当 Quarto 安装在非标准路径时。

VSCode

避免常见的 VSCode 错误——设置冲突、调试器配置和扩展冲突。

下载

解决方法是显式指定可执行文件位置：

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 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)

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$ 时