VS Code中XeLaTeX编译LaTeX项目：交叉引用失效问题排查

你的settings.json配置存在参数错误，导致Biber未正确执行，进而引发交叉引用异常。

核心问题 #

Biber工具的参数使用了%DOCFILE%变量，该变量会输出带扩展名的主文件名（比如main.tex），但Biber需要的是不带扩展名的主文件名（比如main）才能找到对应的.bcf辅助文件。终端中你执行的是biber main（正确），但VS Code中实际执行的是biber main.tex（错误），这直接导致Biber未处理文献数据，后续XeLaTeX也无法生成正确的引用。

修正后的配置 #

将settings.json中的工具配置修改如下：

{
    "latex-workshop.latex.tools": [
        {
            "name": "xelatex",
            "command": "/usr/bin/xelatex",
            "args": [
                "-interaction=nonstopmode",
                "%DOCFILE_BASE%"
            ],
            "workingDirectory": "%DOC_PATH%"
        },
        {
            "name": "biber",
            "command": "/usr/bin/biber",
            "args": [
                "%DOCFILE_BASE%"
            ],
            "workingDirectory": "%DOC_PATH%"
        }
    ],
    "latex-workshop.latex.recipes": [
        {
            "name": "xelatex -> biber -> xelatex",
            "tools": [
                "xelatex",
                "biber",
                "xelatex"
            ]
        }
    ],
    "latex-workshop.latex.build.recipe.default": "xelatex -> biber -> xelatex",
    "latex-workshop.latex.env": {
        "PATH": "/usr/bin:$PATH"
    }
}

关键修改点 #

1. 替换变量：将%DOCFILE%改为%DOCFILE_BASE%，该变量会输出不带扩展名的主文件名，和你终端中使用的命令完全一致。
2. 指定工作目录：添加"workingDirectory": "%DOC_PATH%"，确保编译命令在主文件所在的项目目录中执行，等效于终端cd path/to/my/project的操作。

验证方法 #

修改配置后，重新执行编译：

1. 清理之前生成的辅助文件（.aux、.bcf、.out等）
2. 运行xelatex -> biber -> xelatex编译流程
3. 检查终端输出，确认不再出现Please (re)run Biber的警告，交叉引用处的??会被正确替换。

内容的提问来源于stack exchange，提问作者Zainab Iftikhar