1. 先想清楚这套组合到底在解决什么问题1.1 为什么是 TeX Live 而不是别的发行版写论文、写书、写技术文档只要排版要求稍微严一点最后基本都会绕回 LaTeX。而装 LaTeX 这件事第一步就是选发行版。市面上常见的有 TeX Live、MiKTeX、MacTeX 这几种我这些年用下来结论很朴素跨平台、长期稳定、宏包最全的还是 TeX Live。原因不复杂。MiKTeX 的卖点是按需安装编译时缺什么宏包就现下什么看起来省空间但代价是首次编译某个复杂文档时会频繁卡在网络请求上断网或者镜像抽风就直接编不过。对于写作这种需要心流的事情中途停下来等下载是很破坏节奏的。TeX Live 走的是另一个路子——一次性把 scheme-full 全部装好之后几年你写什么文档基本都不用再操心宏包缺失。对长期写东西的人来说磁盘换省心这笔账是划算的。TeX Live 完整版装完大概 7 到 8 个 G放在今天动辄 512G 起步的硬盘上真不算什么。我更看重的是它的可复现性同一份.tex文件在 Windows、macOS、Linux 上编出来的结果几乎完全一致这对需要投稿、需要多人协作的场景太重要了。还有个容易被忽略的点tlmgr这个包管理器是 TeX Live 自带的更新、装卸宏包一条命令搞定而且 TeX Live 的版本是按年发布的你锁定某一年份后宏包生态就固定住了不会出现昨天还能编今天更新完就报错的惨案。1.2 VSCode 在这套流程里扮演什么角色很多人会问为什么不直接用 TeXstudio 或者 WinEdt这些专用编辑器开箱即用确实省事。但我的使用场景里LaTeX 只是工作流的一环旁边还有代码、脚本、Markdown 笔记、配置文件。为了写 LaTeX 单独开一个 IDE再在两边来回切窗口时间长了真的很烦。VSCode 的价值在于它是容器不是单一功能的编辑器。装上 LaTeX Workshop 插件之后语法高亮、补全、编译、预览、反向搜索、日志跳转全部在一个窗口里完成同时它还能顺手处理同一目录下的.bib、.py、.yaml。这一点在写带数据可视化的论文时特别爽——改完画图脚本直接在同一棵树里编译文档。需要说清楚的是VSCode 本身不会编译 LaTeX它只是调度员。真正干活的是 TeX Live 提供的xelatex、latexmk这些命令行工具。理解这一点非常关键因为后面所有编译失败预览打不开的问题绝大多数都不是 VSCode 的锅而是命令链或者环境变量的问题。想通这层排查思路就顺了先在终端里手动跑一遍命令能出 PDF再回 VSCode 里看配置。1.3 预览方式为什么值得单独拿出来讲标题里我特意把预览方式单列出来因为这是新手最容易忽视、老手也常常配错的一环。LaTeX 的写作循环是改一点、编一下、看一眼预览环节顺不顺直接决定你一天能推进多少内容。常见预览方式大致有这么几类VSCode 内置的 PDF 标签页预览、外部 PDF 阅读器配合反向搜索、浏览器里通过本地服务预览、以及侧栏多页缩略图。它们之间不是替代关系而是不同场景下的不同选择。比如写大体量书籍时我需要外部阅读器的平滑滚动和书签写短篇时内置预览的保存即刷新更顺手做幻灯片时又想看多页缩略。所以这篇文章我不会只给你一份配置而是把每种预览方式的适用边界、配置成本、踩坑点都摊开说清楚你可以按自己的文档类型挑一套也可以几套并存随时切换。2. 装 TeX Live 之前必须确认的三件事2.1 中文用户名与安装路径是头号杀手先把最要命的坑摆在前面Windows 用户名是中文会引发一连串莫名其妙的问题。表现五花八门——tlmgr报编码错误、编译时找不到用户配置文件、TEXMFHOME解析失败、日志里出现乱码路径。原因在于 TeX 生态系统里有大量脚本是 Perl 和批处理写的对非 ASCII 路径的处理并不总是可靠。我的建议很直接安装路径绝对不要包含中文和空格。默认装在C:\texlive\2024就挺好如果你想装到别的盘用D:\texlive\2024这种形式。哪怕你的系统用户名是中文只要安装目录干净绝大多数问题都能绕过去。如果你已经踩进去了也不是没办法。可以在系统环境变量里手动指定TEXMFHOME指向一个纯英文路径比如D:\texmf。这样做的好处是用户级的宏包、模板、字体都放在一个安全的位置不和系统用户目录扯上关系。这个技巧我在三台中文用户名的机器上都验证过稳定可用。注意安装期间关掉杀毒软件的实时防护。TeX Live 安装过程要释放几万个小文件实时扫描会让安装时间从二十分钟变成两个小时还有小概率在解压中途锁文件导致安装失败。2.2 Windows 下的安装流程与镜像选择Windows 上官方推荐下载install-tl-windows.exe这是一个引导程序运行后它会去拉取真正的安装脚本。默认源在海外速度可能很感人。所以第一步就改成国内镜像这一步能省下大量时间。我的操作顺序是这样的下载安装器后先别急着点下一步找到镜像选择的地方切到清华 TUNA、中科大 USTC 或者阿里云的 CTAN 镜像。切换之后后面的下载会明显快很多。安装模式上如果你硬盘不紧张直接选scheme-full。理由前面说了省心。如果你确实想省空间那就选scheme-basic加中文支持相关的集合之后用tlmgr按需装但这意味着你以后每次遇到缺包都要手动处理一遍# 装完之后随时可以补装宏包 tlmgr install ctex tlmgr install algorithm2e安装过程通常 20 到 60 分钟取决于磁盘速度和镜像。中途不要关窗口哪怕看起来卡住不动了也可以先看看任务管理器里磁盘是不是还在写。我见过有人以为卡死了直接关掉结果重装三遍。2.3 macOS 与 Linux 的差异化做法macOS 用户的等价选择是 MacTeX它其实就是 TeX Live 加上一堆 Mac 专属工具比如 TeXShop、BibDesk。现在 MacTeX 也用tlmgr管理和 TeX Live 保持一致。如果你不想装 4 个 G 的附赠软件可以直接下载BasicTeX再自己补包但同样会面临缺包手动补的问题。苹果芯片的机器上TeX Live 早就原生支持 ARM 了不用折腾兼容层。Linux 用户最省事发行版仓库里就有。但这里有个取舍仓库版本往往落后一两年。如果你只是写普通文档仓库版本完全够用如果要投稿到对版本有要求的期刊建议用官方安装脚本# 下载并运行官方安装器 wget https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/tlnet/install-tl-unx.tar.gz tar -xzf install-tl-unx.tar.gz cd install-tl-*/ sudo ./install-tl -repository https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/tlnet装完之后记得把bin目录加进PATH否则xelatex命令在终端里是找不到的。这一点和 Windows 不一样Windows 的安装器会自动处理环境变量。2.4 三条命令验证安装是否真的成功装完别急着开 VSCode先在终端里跑三条命令。这一步能帮你提前排除掉八成后续问题。tex --version # 看版本号确认主程序在 latexmk --version # 编译调度器后面排练用得上 kpsewhich ctexart.cls # 查中文文档类能否被找到第三条命令尤其关键。如果它返回一个具体路径说明中文支持已经就位如果什么都不输出说明ctex没装上需要tlmgr install ctex。很多人后面在 VSCode 里编译中文报错根子就在这里。再顺手把镜像源固化一下以后更新会快很多tlmgr option repository https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/tlnet tlmgr update --self --all--self是更新tlmgr自身--all是更新全部宏包。这两个可以分开跑先更新自己再更新所有避免版本不匹配。3. VSCode 端配置把调度逻辑写进 settings.json3.1 插件装哪些别装哪些核心插件只有一个LaTeX Workshop作者 James Yu。它承担了编译、预览、日志解析、反向搜索几乎所有功能。剩下的都是锦上添花。我实际会装的清单是这样的插件作用是否必需LaTeX Workshop编译、预览、Synctex必需Chinese (Simplified) Language Pack中文界面看习惯Code Spell Checker英文拼写检查推荐LaTeX Utilities字数统计、引用跳转可选GitLens版本追溯看习惯不推荐一上来装一堆 LaTeX 相关插件尤其是功能重叠的。多个插件同时接管.tex文件的编译任务会出现保存后编译两次甚至互相覆盖日志的情况排查起来非常痛苦。一个 LaTeX Workshop 就够了。界面汉化很简单CtrlShiftP打开命令面板输入Configure Display Language选中文重启即可。注意这只是界面语言不影响编译。3.2 settings.json 里真正需要改的字段LaTeX Workshop 的默认配置其实能跑但对中文项目和自有目录结构来说不够用。我把我这几年稳定的配置拆开讲每条都说明为什么。{ latex-workshop.latex.tools: [ { name: xelatex, command: xelatex, args: [ -synctex1, -interactionnonstopmode, -file-line-error, %DOC% ], env: {} }, { name: bibtex, command: bibtex, args: [%DOCFILE%], env: {} }, { name: latexmk, command: latexmk, args: [ -synctex1, -interactionnonstopmode, -file-line-error, -xelatex, %DOC% ], env: {} } ] }逐条说。-synctex1是生成反向搜索索引没有它你在 PDF 里双击就没法跳回源码。-interactionnonstopmode让编译过程遇到错误继续往下走而不是停下来等你敲回车——在 GUI 环境下停下来就意味着卡死。-file-line-error把报错格式改成文件名:行号: 错误VSCode 能直接识别并生成可点击的链接这是体验提升最大的一条。%DOC%是带扩展名的完整文件名%DOCFILE%是不带扩展名的主文件名。BibTeX 需要的是后者搞混了会报找不到 .aux 文件。然后是编译配方recipe{ latex-workshop.latex.recipes: [ { name: xelatex, tools: [xelatex] }, { name: xelatex x2, tools: [xelatex, xelatex] }, { name: latexmk (xelatex), tools: [latexmk] }, { name: xelatex - bibtex - xelatex x2, tools: [xelatex, bibtex, xelatex, xelatex] } ] }为什么要准备四个配方因为它们对应不同的文档状态。单次xelatex最快适合改正文时的高频编译两次xelatex是为了让目录、交叉引用、页码收敛带 bibtex 的那条专门处理参考文献因为 BibTeX 需要先读到.aux才能排序生成.bbl。日常写作用单次或两次投稿前跑一次完整链这是我实践下来最省时间的策略。3.3 中文文档该走 xelatex 还是 latexmk新手最常问的是编译中文到底用pdflatex还是xelatex答案是直接上 xelatex。pdflatex对 UTF-8 和系统字体的支持是硬伤传统做法要靠CJK宏包加一堆编码声明稍微特殊一点的字就变成方框或者报Missing character。xelatex原生走 Unicode配合ctex宏包可以直接调用系统里的中文字体写作体验完全不是一个级别。\documentclass[UTF8]{ctexart} \begin{document} 中文排版测试标点、引号测试都没问题。 \end{document}latexmk则是个总调度它自己判断需要编译几遍、什么时候跑 BibTeX。配上-xelatex参数后等于把上面那条长链交给它自动决策{ name: latexmk, command: latexmk, args: [ -synctex1, -interactionnonstopmode, -file-line-error, -xelatex, -outdir%OUTDIR%, %DOC% ] }我的建议是文档里引用了大量参考文献、有索引、有术语表的时候用 latexmk纯正文写作时用手动链因为它更快、日志更干净。latexmk 的日志里会混入它自己的调度信息出错时定位反而更慢。3.4 自动编译与自动清理的取舍LaTeX Workshop 支持保存即编译这个功能好用但也要小心。配置项是{ latex-workshop.latex.autoBuild.run: onSave, latex-workshop.latex.autoClean.run: onBuilt }onSave是最稳的选择。onFileChange会在你每敲几个字就触发一次编译大文档下会卡到你怀疑人生。never则适合那种编译一次要几十秒的重量级文档手动触发更可控。自动清理辅助文件这个功能我建议先别开。原因很实际.aux、.toc、.bbl这些中间文件是增量编译的基础清掉之后下次编译要全量重跑。更麻烦的是一旦清理规则写错把.synctex.gz删了反向搜索直接失灵。等你环境完全稳定了再考虑开。手动清理可以用命令面板里的LaTeX Workshop: Clean up auxiliary files比配置自动清理安全得多。4. 四种预览方式的适用边界与配置4.1 内置 PDF 预览短文档的首选LaTeX Workshop 内置了一个基于 PDF.js 的查看器编译完成后会在编辑区新开一个标签页显示 PDF。配置一行搞定{ latex-workshop.view.pdf.viewer: tab, latex-workshop.synctex.afterBuild.enabled: true, latex-workshop.view.pdf.internal.synctex.keybinding: double-click }它的优点是开箱即用、零外部依赖、和反向搜索天然打通。保存后 PDF 自动刷新位置还能大致保持改一段看一眼的节奏非常顺。反向搜索用Ctrl点击或者双击光标就跳回源码对应行了。但它也有明确的短板。第一大文档渲染吃力。三百页以上的教材、带大量矢量图的学位论文滚动会明显发涩翻页有延迟。第二书签、注释、多窗口对比这些功能基本没有。第三PDF.js 的字体渲染在某些中文字体上会有细微的字重偏差看久了眼睛累。所以我的实际用法是小于五十页的文档、日常修改、赶稿阶段全用内置预览一旦文档超过一百页立刻切换到外部阅读器。这个阈值是我自己反复试出来的你可以按机器性能上下调整。4.2 外部阅读器配反向搜索长篇写作的标配外部阅读器这条路Windows 上几乎只有 SumatraPDF 值得推荐macOS 上是 SkimLinux 上 Okular 或 zathura 都行。它们的共同点是轻量、启动快、支持热重载PDF 文件被覆盖后会立刻重新加载并尽量保持阅读位置。核心配置是三段告诉 VSCode 用外部查看器、告诉它查看器的启动命令、告诉它反向搜索时怎么把坐标传回编辑器。{ latex-workshop.view.pdf.viewer: external, latex-workshop.view.pdf.external.viewer.command: C:/Program Files/SumatraPDF/SumatraPDF.exe, latex-workshop.view.pdf.external.viewer.args: [ -reuse-instance, %PDF% ] }-reuse-instance很关键。不加这个参数每次编译都会弹出新的 SumatraPDF 窗口开十次编译就有十个窗口任务栏直接爆炸。加了之后它复用同一个窗口并自动重载。反向搜索的方向是反过来的——从 PDF 跳回源码。这需要 SumatraPDF 知道用什么命令去唤起 VSCode{ latex-workshop.view.pdf.external.synctex.command: C:/Program Files/SumatraPDF/SumatraPDF.exe, latex-workshop.view.pdf.external.synctex.args: [ -forward-search, %TEX%, %LINE%, -reuse-instance, %PDF% ] }同时在 SumatraPDF 里要设置好反向搜索命令行让它双击时调用 VSCode 并带上文件行号参数。这一步必须在 SumatraPDF 的图形设置里手动填没法通过 VSCode 配置完成。填完之后在 PDF 里双击任意位置VSCode 就会跳到源码对应行写作效率提升非常明显。macOS 上的 Skim 更省事它的偏好设置里直接有 SyncTeX 预设选项选 Visual Studio Code 就行路径会自动填好。Linux 下 Okular 需要在设置里开启编辑器并填上code -g %f:%l这类命令。4.3 浏览器预览多设备查看的临时方案还有一条路是在浏览器里预览。LaTeX Workshop 内置了一个本地 HTTP 服务把 PDF 通过http://127.0.0.1:3000这样的地址暴露出来{ latex-workshop.view.pdf.viewer: browser }这条路我用的场景很窄但确实有用需要把预览内容投到平板、或者在同一局域网的另一台机器上看的时候。比如把笔记本当编译机用平板在旁边看排版效果这种时候浏览器方案就很方便。需要注意的是端口占用。3000 是个很热门的端口被别的开发服务占掉之后预览会一直转圈。解决方法是改端口{ latex-workshop.view.pdf.internal.synctex.keybinding: double-click, latex-workshop.view.pdf.viewer: browser, latex-workshop.view.pdf.browser.port: 34567 }改成五位数的不常用端口冲突概率大幅下降。另外浏览器方案下反向搜索基本不可用它适合只看不改的场景。4.4 侧栏缩略图与多页对照写幻灯片beamer或者需要整体把握版式的时候我强烈建议用侧栏缩略图。LaTeX Workshop 在 PDF 标签页的左侧有个缩略图面板能一次看到多页布局。检查页面是否溢出、标题层级是否统一、表格有没有跑出边界用这个视图比逐页翻要快得多。如果你的预览方式是外部阅读器那 SumatraPDF 的显示书签面板也能起到类似作用而且它的书签直接由 PDF 的目录结构生成跳转很快。我给自己的模板都会加\usepackage{hyperref}并开启bookmarks这样目录结构自动映射成 PDF 书签长篇文档导航效率翻倍。再补一个组合打法同一份 PDF 用两个窗口打开。一个开在 VSCode 内置标签页负责写的时候瞄一眼一个用 SumatraPDF 全屏开着负责整体审阅。两个窗口都在监听同一个文件编译完同时刷新。这套配法听着有点浪费但在赶论文最后几天的时候真的能省不少事。5. 报错排查实录那些年我踩过的坑5.1 中文路径导致的一连串灵异问题前面提过中文用户名这里给一个具体的排查流程。当你遇到命令行能编译、VSCode 编译失败这种诡异现象时按这个顺序查第一在 VSCode 的集成终端里手动敲一遍编译命令看原始报错。LaTeX Workshop 的日志会把很多细节折叠起来直接看终端输出更清楚。第二检查kpsewhich -var-valueTEXMFHOME的输出路径里有没有中文。如果有就在系统环境变量里把它指向纯英文目录。第三确认工作目录的完整路径没有中文也没用空格。项目放在D:\work\paper这种路径下最稳妥。第四检查latex-workshop.latex.outDir的设置。如果你设成了%DIR%/build要确认这个build目录存在或者配置里允许自动创建。目录不存在时编译会静默失败日志里只留下一句语焉不详的报错。注意Windows 上路径分隔符用正斜杠/在 VSCode 配置里是安全的反斜杠\反而容易在 JSON 里被当成转义字符导致路径解析错误。5.2 编译链超时与辅助文件残留另一种高频问题是编译看起来在跑但永远不结束。原因通常是两道一是-interaction没设成nonstopmode某个宏包在等输入二是编译链太长VSCode 默认的超时时间不够。解决办法分两步。先确认nonstopmode已经加上如果还是卡就在配方里减少编译次数或者把超时时间调长{ latex-workshop.latex.build.forceRecipeUsage: false, latex-workshop.latex.autoBuild.run: onSave }forceRecipeUsage设成false允许 LaTeX Workshop 在判断配方不适用时回退到默认行为。这个选项在新版本里被调整过我一般保持默认不动只在明确需要时才改。辅助文件残留的典型症状是改了参考文献编出来还是旧的。这是因为.bbl文件没被重新生成。方向是手动删掉*.aux、*.bbl、*.blg、*.fdb_latexmk这几个文件再跑完整编译链。为了省事我把清理列表写进了配置{ latex-workshop.latex.clean.fileTypes: [ *.aux, *.bbl, *.blg, *.idx, *.ind, *.lof, *.lot, *.out, *.toc, *.acn, *.acr, *.alg, *.glg, *.glo, *.gls, *.fls, *.log, *.fdb_latexmk, *.snm, *.nav, *.vrb ] }注意这里故意不包含*.synctex.gz。很多默认配置会把它一起清掉清完反向搜索就废了还得重新走一遍完整编译才能恢复。5.3 反向搜索点了没反应反向搜索失效的排查我总结成四个检查点编译参数里有没有-synctex1。没有这个参数.synctex.gz根本不会生成。.synctex.gz文件是不是存在和 PDF 在不在同一个目录。如果你的outDir设了子目录Synctex 文件也会跟着过去外部阅读器找不到它。外部阅读器的反向搜索命令有没有配好。SumatraPDF 那边是必须手动填的VSCode 配置只负责正向跳转。PDF 和源码版本是否一致。如果你改了源码但没重新编译就点 PDF跳过去的位置是旧的。还有一个隐蔽的坑同一份文档在多个编辑器里打开过。比如你之前用别的编辑器打开过项目.synctex.gz里记录的是那个编辑器的路径信息VSCode 接手后跳转会跳到错误的文件。重新完整编译一遍即可。5.4 常见问题速查表现象可能原因处理方式保存后不编译autoBuild 设为 never改为 onSave编译成功但没 PDFoutDir 目录不存在手动建目录或去掉 outDir中文变方框宏包没装或字体缺失装 ctex检查 fontspec 字体名参考文献不更新bbl 未重新生成清理 aux/bbl 后完整编译反向搜索跳错文件synctex 缓存过期删 synctex.gz 后全量编译编译卡住不结束缺 nonstopmode检查编译参数内置预览打不开PDF.js 加载失败换外部阅读器或重启窗口浏览器预览转圈端口被占用换一个高位端口报错无法定位缺 file-line-error加上该参数这张表基本覆盖了我遇到过的九成问题。剩下的那一成通常得靠看latex-workshop.log里折叠的原始输出——日志文件是最终真相任何插件的界面提示都只是它的摘要。6. 效率技巧与目录组织习惯6.1 目录结构和管理多文件项目项目一大就得拆分文件否则一个几千行的.tex谁都不想打开。我习惯的目录长这样paper/ ├── main.tex ├── chapters/ │ ├── 01-intro.tex │ └── 02-method.tex ├── figures/ ├── refs/ │ └── library.bib └── build/主文件只保留导言区和\input语句\documentclass[UTF8]{ctexart} \usepackage{graphicx} \usepackage{hyperref} \begin{document} \input{chapters/01-intro} \input{chapters/02-method} \bibliography{refs/library} \bibliographystyle{plain} \end{document}这里有个硬性要求\input的路径是相对于主文件的不是相对于当前文件。初学时我在子文件里写相对路径折腾了半天才发现引用不到图。另外如果主文件放在子目录里比如src/main.tex编译工具的工作目录会以 VSCode 打开的根目录为准容易导致图片找不到。这时候要么用%DIR%显式指定输出目录要么就在配置里加cwd{ name: xelatex, command: xelatex, args: [ -synctex1, -interactionnonstopmode, -file-line-error, %DOC% ], env: {} }最省心的做法还是把主文件放在项目根目录latexmk和 Synctex 都能少掉一堆奥妙。6.2 用代码片段把常用结构固化下来写论文有大量重复结构图、表、公式、定理环境。每次都手敲一遍\begin{figure}...\end{figure}是纯浪费。VSCode 的用户片段功能在这里非常好用按CtrlShiftP找到Snippets: Configure User Snippets选latex.json然后写{ Figure with caption: { prefix: fig, body: [ \\begin{figure}[htbp], \\centering, \\includegraphics[width0.8\\linewidth]{$1}, \\caption{$2}, \\label{fig:$3}, \\end{figure} ], description: 插入带标题和标签的图 } }之后敲fig加 Tab 就能展开光标依次停在图片路径、标题、标签位置。同理可以给表格、公式、参考文献引用各配一个。这一招我把日常写作速度提升了大概三分之一尤其是写方法章节那种图表密集的部分。公式片段我还会带上\begin{equation}和\label{eq:}的组合因为公式编号和引用必须成对出现漏了标签后面引用就会报??。6.3 版本管理与编译产物的隔离LaTeX 项目一定要用 Git 管。但.aux、.log、.pdf这些产物不该进仓库一是体积大二是每次编译都变会污染 diff。.gitignore我是这么写的build/ *.aux *.log *.out *.toc *.synctex.gz *.fdb_latexmk *.fls *.bbl有个取舍要提醒.bbl要不要提交视场景而定。如果你用在线投稿系统对方只接受源码包那提交.bbl能让对方不跑 BibTeX 也能编出来这时候就得提交。本地仓库我一般忽略它。还有一点不要用 Git 管理 PDF。有人为了版本对比把编译出的 PDF 也提交了仓库半年就涨到几百兆。真需要留档单独建一个releases/目录在本地保存或者用标签指向源码快照就够了。6.4 WSL 和远程开发的一点补充现在不少人用 WSL 或者远程服务器跑编译。这套组合下有个先天限制PDF 预览这一步没法在 WSL 里完成因为 WSL 没有图形界面除非额外配 X Server。所以正确的做法是编译放在 WSL 或远程服务器预览回到 Windows 侧的外部阅读器。VSCode 的 Remote 系列插件能很好地支持这种分离。VSCode 连接远程环境后LaTeX Workshop 在远程执行编译命令但查看器进程是本地启动的。配置上需要把latex-workshop.view.pdf.external.viewer.command指向本地的 SumatraPDF 绝对路径而不是远程路径。这个不一致性初看很别扭但它恰好是远程编译、本地预览这套分工的体现。远程场景下还有阻尼网络延迟会让反向搜索的响应变慢跳到源码要等一两秒。如果你对写作节奏很敏感本地装一套 TeX Live 会更舒服。远程方案更适合算力受限或者需要统一环境的团队协作。7. 我实际用下来最稳的一套配置说了这么多分支最后把我自己天天用的那套贴出来。前提是Windows 系统、用户名可能含中文、文档以中文为主、篇幅在几十到两百页之间。编译链用手动的xelatex x2参考文献单独跑xelatex - bibtex - xelatex x2。预览默认走内置标签页文档超过一百页时手动切到 SumatraPDF。自动编译只在保存时触发自动清理不开。输出目录不设outDir所有产物留在项目根目录Synctex 路径最简单反向搜索最不容易出问题。这套配置听起来不高级但它的好处是几乎没有隐式行为。每个环节你能看到、能预测出问题时知道去哪找。我在配置上追过花哨试过自动清理、自定义输出目录、latexmk -pvc常驻监控最后都退回来了。-pvc那个尤其容易和 VSCode 的自动编译打架两个进程同时写同一组辅助文件偶发编译结果错乱排查成本极高。一个我坚持了好几年的小技巧给每个项目单独留一份settings.json放在.vscode/目录里跟着仓库走。这样换机器的时候不用重新配而且不同项目可以用不同配方——论文用完整链笔记用单次编译幻灯片用两次。项目级配置会覆盖用户级配置切换项目自动切换行为。还有一个提醒如果你哪天突然发现昨天还好好的今天全乱了先别急着改配置。按顺序检查tlmgr是不是自动更新了某个宏包、PATH里是不是多了另一份 LaTeX 的bin目录、项目里是不是手滑删了.synctex.gz。我这几次灵异事件查下来九成都是这三个原因之一。养成在终端里先跑一遍命令的习惯比盯着插件日志猜要快得多。