latexmk报“command not found”需先在终端运行which/where latexmk验证命令是否存在，若无输出则说明TeX发行版未安装或PATH未正确配置：macOS需将/Library/TeX/texbin加入~/.zshrc并重启VSCode，Windows需勾选安装时的“Add TeX Live to PATH”或手动添加路径。

latexmk 报 “command not found” 怎么办

这不是插件没装好，而是 VSCode 根本找不到 latexmk 这个命令。LaTeX Workshop 只是调度器，不自带编译器。

• 先在 VSCode 内置终端（Ctrl+`）运行 which latexmk（macOS/Linux）或 where latexmk（Windows），必须有输出；没有就说明 TeX 发行版没装，或 PATH 没配对
• macOS 用 brew install --cask mactex 后，需手动把 /Library/TeX/texbin 加进 shell 的 $PATH（比如在 ~/.zshrc 里加 export PATH="/Library/TeX/texbin:$PATH"），然后彻底重启 VSCode
• Windows 安装 TeX Live 时务必勾选 “Add TeX Live to PATH”；若已安装完，就手动把类似 C:\texlive\2024\bin\win32 的路径加进系统环境变量
• Ubuntu/Debian 用户别只装 texlive-base，得运行 sudo apt install texlive-latex-recommended texlive-latex-extra latexmk

PDF 不自动刷新或预览窗口空白

LaTeX Workshop 默认不监听所有文件变动，尤其对 .bib、.sty 或子目录下的 .tex 文件静默忽略——它只认你指定的“主文档”。

VSCode

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

下载

• main.tex 文件第一行或前几行加上注释：% !TEX root = main.tex（哪怕就是本文件，也必须写）
• 检查设置里 latex-workshop.latex.autoBuild.run 是 onFileChange 而不是 never
• 关掉内置 PDF 查看器的 tab 模式：设 latex-workshop.view.pdf.viewer 为 external，并配好外部查看器（macOS 用 Skim，Windows 用 SumatraPDF）
• 首次编译建议手动按 Ctrl+Alt+B（Win/Linux）或 Cmd+Alt+B（macOS），别依赖保存即编译——有些模板（如 IEEEtran）需要多遍跑 bibtex 才能出参考文献

xelatex 编译不生成 PDF 却没报错

常见现象：保存 .tex 文件后，右下角状态栏显示 “Building…” 然后消失，PDF 标签页没刷新，也没弹出错误提示。根本原因通常是主文档未被识别或编译链未启用 -synctex=1。

• VS Code 左下角应显示 “Root file: xxx.tex”，否则插件不知道编译谁；若手动指定 latex-workshop.latex.rootFile，路径必须用正斜杠（./main.tex），不能写 .\main.tex
• 多文件项目（如 chapters/intro.tex）需在子文件顶部第一行加 % !TEX root = ../main.tex，且前面不能有空行或 BOM 字符
• 禁用 latex-workshop.message.error.show 后，编译失败会被吞掉——临时打开它，看终端输出里有没有 ! Undefined control sequence 或字体缺失警告
• 确保编译工具链参数含 -synctex=1 和 -interaction=nonstopmode，否则 SyncTeX 失效，PDF 预览和反向跳转都会断

中文乱码或标点挤压怎么办

中文论文必须用 XeLaTeX 引擎，但宏包混用或字体路径错位会直接导致段落缩进异常、章节标题乱码、标点粘连。

• 现在唯一推荐方案是只用 ctex，别混用 xeCJK：\usepackage{ctex} 一行就够了；手动加载 xeCJK 再加 ctex 会触发字体重复注册，报 fontspec error: "font-not-found"
• ctex 默认已适配各平台中文字体：Windows 用 "SimSun"，macOS 用 "PingFang SC"，Linux 用 "Noto Sans CJK SC"；若需微调，改选项即可，如 \usepackage[fontset=ubuntu]{ctex}
• 确保 .tex 文件编码为 UTF-8（无 BOM），VS Code 右下角确认，不是 ANSI 或 GBK；.bib 文件同理，否则 bibtex 会跪，必须换 biber
• 如果用了 subfiles 管理多文件，每个子文件仍需在导言区显式加载 ctex，或统一在主文件导言区加载后，子文件通过 \documentclass[main]{subfiles} 继承

实际配置中最容易被忽略的是：VSCode 重启不等于重载窗口，PATH 变更后必须完全退出再启动；% !TEX root 注释必须在文件最开头；biber 替代 bibtex 时，.bib 文件编码和 recipe 配置必须同步更新。