VSCode中LaTeX Workshop编译失败等问题，需依次配置LaTeX路径、启用XeLaTeX并设中文字体、设置biber参考文献流程、开启SyncTeX同步、调整日志编码；macOS下路径为/Library/TeX/texbin/xelatex，字体推荐Songti SC。
如果您在VSCode中使用LaTeX Workshop扩展编写学术论文，但遇到编译失败、预览不刷新、引用无法跳转或中文乱码等问题，则可能是由于工具链配置不当、编译流程未正确设置或字体支持缺失所致。以下是解决此类问题的具体操作步骤：
本文运行环境：MacBook Pro，macOS Sequoia。
一、验证并配置LaTeX发行版路径
LaTeX Workshop依赖系统中已安装的LaTeX发行版（如TeX Live或MacTeX）执行编译。若插件无法调用latexmk、xelatex等命令，需手动指定可执行文件路径。
1、打开VSCode设置（Cmd + ,），搜索“latex-workshop.latex.tools”。
2、点击“Edit in settings.json”，在数组中添加或修改xelatex条目：
3、确保"args"包含"-synctex=1"、"-interaction=nonstopmode"及"%DOC%"，且"path"指向本地xelatex绝对路径，例如"/usr/texbin/xelatex"或"/Library/TeX/texbin/xelatex"。
4、在"latex-workshop.latex.recipe.default"中确认默认recipe已设为"xelatex"或自定义含xelatex的序列。
二、启用XeLaTeX并正确声明中文字体
默认pdfLaTeX不支持直接调用系统字体，而XeLaTeX可原生处理UTF-8和TrueType字体，是中文论文编排的推荐引擎。需在导言区加载fontspec宏包并指定中文字体。
1、在.tex主文件导言区（\begin{document}之前）添加：\usepackage{fontspec}。
2、添加中文字体设置语句：\setmainfont{Songti SC}（macOS系统自带宋体）或\setmainfont{Noto Serif CJK SC}（需提前安装Noto字体）。
3、删除或注释掉\usepackage[UTF8]{ctex}以外的旧字体包（如CJK、xeCJK混用会导致冲突）。
三、修复参考文献无法生成与交叉引用失效
BibTeX或Biber后端需与编译流程严格同步。LaTeX Workshop默认recipe若未包含bibtex/biber步骤，将导致\cite命令显示问号且参考文献为空。
使用约定式提交（Conventional Commits）生成标准化的 Git 提交信息。适用于以下场景： (1) 暂存更改时需要提交信息； (2) 审查 diff 时希望获得结构化摘要； (3) 编写 PR 描述或变更日志（changelog）条目； (4) 用户明确要求“为本次更改编写提交信息”。 该功能会分析已暂存/未暂存的 diff，并生成按类型（type）划分范围的提交信息。
1、在settings.json中定位"latex-workshop.latex.recipes"，新增一个recipe对象，名称设为"pdflatex → biber → pdflatex ×2"。
2、该recipe的tools数组依次填入："pdflatex"、"biber"、"pdflatex"、"pdflatex"。
3、确保.bib文件路径被\addbibresource{references.bib}正确声明，且references.bib位于工作区根目录或与主.tex同级。
4、保存后按Cmd + Alt + B触发该recipe，观察底部状态栏是否显示“Biber completed successfully”。
四、启用正向与反向同步（SyncTeX）
SyncTeX支持PDF预览器与源代码双向跳转，提升编辑效率。需编译器参数、PDF查看器及插件三者协同启用。
1、检查xelatex或pdflatex的args中已包含"-synctex=1"选项。
2、在设置中将"latex-workshop.view.pdf.viewer"设为"tab"或"external"；若选external，需确认Skim（macOS）已安装并启用“Preferences → Sync → Check for file changes”。
3、在PDF预览标签页中右键选择“Jump to source”，或按Cmd + Click PDF任意位置，自动定位至对应.tex行。
五、解决编译日志中文乱码与警告堆积
终端输出编码不匹配或log文件含大量无关警告，会干扰错误定位。需统一编码环境并精简日志级别。
1、在settings.json中添加："latex-workshop.latex.logFileFilter": ["error", "warning"]，隐藏info级日志。
2、于终端中执行locale命令，确认LANG值为"zh_CN.UTF-8"或"en_US.UTF-8"；若非UTF-8，需在shell配置文件（如.zshrc）中添加export LANG=en_US.UTF-8并重载。
3、重启VSCode使环境变量生效，再次编译观察日志是否仅显示关键错误与警告。
