Mac VSCode LaTeX 插入 SVG 完整终极教程（彻底解决 svg-raw.pdf 缺失报错）
一、适用环境

• 系统：Mac（Intel / Apple Silicon 通用）
• 编辑器：VS Code + LaTeX Workshop
• 编译引擎：XeLaTeX / Latexmk（论文主流配置）
• 需求：LaTeX 原生插入 SVG 矢量图、不失真、不手动转 PDF
  二、你之前所有报错的根源（核心总结）

1. 报错 File xxx_svg-raw.pdf is missing
   不是你文件少了，是 SVG 转换流程失败：

• svg 宏包不能自己处理 SVG，必须调用外部软件 Inkscape
• Mac 默认禁止 LaTeX 调用外部程序，需要开启 --shell-escape 权限
• 权限没开 → Inkscape 没执行 → 临时 PDF 没生成 → 报缺失错误

2. 一改配置就无法编译
   你的旧配置完全依赖 VSCode 默认编译规则：

• 没有自定义 tools（编译指令）
• 没有自定义 recipes（编译流程）
• 我之前只给了你 tools 没给 recipes，导致 VSCode 不知道怎么编译，直接崩

3. 大量 reference 未定义
   SVG 图片编译报错 → 编译直接中断终止 → 后续引用、参考文献全部不解析，属于连锁报错，不是你代码错了。

三、完整环境部署步骤（Mac 专属）
步骤1：Homebrew 安装 Inkscape
打开终端执行：
brew install --cask inkscape
步骤2：建立全局软链接（关键！解决 LaTeX 找不到 Inkscape）
sudo ln -s /Applications/Inkscape.app/Contents/MacOS/inkscape /usr/local/bin/inkscape
输入电脑开机密码，执行完成。
步骤3：验证是否安装成功
inkscape --version
输出版本号即为成功。

四、VS Code 最终正确配置（直接全覆盖）
打开 VSCode 设置（快捷键 command+,）→ 右上角打开 settings.json，全选替换为以下内容：
{
“[cpp]”: {
“editor.wordBasedSuggestions”: “off”,
“editor.semanticHighlighting.enabled”: true,
“editor.stickyScroll.defaultModel”: “foldingProviderModel”,
“editor.suggest.insertMode”: “replace”
},
“lldb.launch.terminal”: “integrated”,
“ipynb.experimental.serialization”: false,
“debug.terminal.clearBeforeReusing”: true,
“debug.internalConsoleOptions”: “neverOpen”,
“files.autoSave”: “afterDelay”,
“workbench.colorTheme”: “Light Modern”,
“workbench.editorAssociations”: {
“*.txt”: “default”
},
“latex-workshop.latex.autoBuild.run”: “never”,
“latex-workshop.latex.autoClean.run”: “onBuilt”,
“latex-workshop.latex.clean.subfolder.enabled”: true,
“latex-workshop.latex.recipe.default”: “lastUsed”,
“latex-workshop.intellisense.package.enabled”: true,
“latex-workshop.message.error.show”: false,
“latex-workshop.message.warning.show”: false,

// 自定义编译工具：开启 shell-escape 支持 SVG 转换
"latex-workshop.latex.tools": [
    {
        "name": "xelatex",
        "command": "xelatex",
        "args": [
            "--shell-escape",
            "-synctex=1",
            "-interaction=nonstopmode",
            "-file-line-error",
            "%DOC%"
        ]
    },
    {
        "name": "latexmk",
        "command": "latexmk",
        "args": [
            "-xelatex",
            "--shell-escape",
            "-synctex=1",
            "-interaction=nonstopmode",
            "-file-line-error",
            "%DOC%"
        ]
    },
    {
        "name": "biber",
        "command": "biber",
        "args": [
            "%DOCFILE%"
        ]
    }
],
// 编译配方：指定默认编译方式，解决无法编译问题
"latex-workshop.latex.recipes": [
    {
        "name": "LaTeXmk (XeLaTeX)",
        "tools": [
            "latexmk"
        ]
    }
]

}
本配置修改说明（精准对比你的原配置）

• 完全保留了你所有个人配置（主题、自动保存、C++ 设置、自动清理、不弹窗报错等）
• 新增 带 --shell-escape 的编译工具：授权 LaTeX 调用 Inkscape 转 SVG
• 新增 标准 recipes 编译流程：解决改配置后无法编译的致命问题
• 新增 biber 工具：适配你的参考文献编译，杜绝引用报错连锁问题

五、LaTeX 代码写法（直接可用）
导言区引入宏包
\usepackage{svg}
正文插入 SVG 图片
\begin{figure}[htbp]
\centering
\includesvg[width=0.82\textwidth]{images/obj_pg_osd_mapping.svg}
\caption{去中心化对象存储系统中的两级映射关系}
\label{fig:obj-pg-osd}
\end{figure}

六、最终使用流程

1. 保存 settings.json，重启 VS Code（必须）
2. VSCode 编译选择：LaTeXmk (XeLaTeX)
3. 正常编译，SVG 自动转 PDF 嵌入，矢量高清、无报错

七、常见问题终极解答

1. 为什么之前会报 svg-raw.pdf 缺失？
   未开启 shell-escape → 禁止调用 Inkscape → SVG 转 PDF 失败 → 临时文件缺失。
2. 为什么一改配置就编译失败？
   只定义了 tools 没有定义 recipes，VSCode 无编译执行方案。
3. 为什么突然几百个引用未定义？
   图片报错导致编译中断，后续所有解析、引用、参考文献全部失效，属于连锁报错，修复图片问题后自动恢复。

八、方案优势

• ✅ 无需手动转 PDF，SVG 原图直接插入
• ✅ 矢量图无限放大不模糊
• ✅ 适配 Mac + XeLaTeX + Latexmk 论文环境
• ✅ 彻底解决所有连锁报错