VsCode LaTeX Workshop工作流打通教程

21世纪优秀青年

375人浏览 · 2026-04-03 11:45:15

21世纪优秀青年 · 2026-04-03 11:45:15 发布

本文前言

遇到的问题及解决

问题1：LaTeX Workshop 找不到编译器

问题2：编译后需要手动打开 PDF 预览

问题3：Overleaf Git 同步配置中Overleaf 拒绝密码登录（403）

本文前言

Overleaf是论文写作神器，之前为了解决普通用户编译时长限制，花了亿些米在万能鱼上升级了一下装备，写作环境也是立马好起来了(见下图)，经实测也是很香了，永久使用说是。然而，一切都朝着不可知的方向发展（内心真实想法：不用我动手动脑，或者给一个任务，坐等智能体去干，而overleaf只是个编译器而已，远远做不到）。

即最近精神状态Vlog：AI for Coding工具的兴起（厌恶了CC&ChatGPT的网页/cli版本，因为需要复制+粘贴 \狗头），特别是vscode中插件的加持，什么copilot/cc/codex/在最近的编程工作中用的飞起。使得重新思考了新的工作流（AI for Writing），overleaf中的项目能不能拉取到本地VsCode IDE(Overleaf Workshop通过Cookies接入Overleaf，测试发现只能编辑修改(能在Overleaf中同步修改内容)，但不能编译~)，使用智能工具完成初稿之后，通过Overleaf中的项目同步-Git完成从VsCode到Overleaf推送更新迭代，同时使用github做版本备份。

完整工作流原理图

本地 VS Code 编辑 .tex

│

▼

Ctrl+S 保存 → 自动编译 → PDF 标签页自动刷新预览

│

▼

git add → git commit

│

├──→ git push overleaf master → Overleaf 在线同步

│

└──→ git push github master → GitHub 私有仓库备份（可选）

Overleaf 在线编辑

│

▼

git pull overleaf master → 本地自动更新

遇到的问题及解决

问题1：LaTeX Workshop 找不到编译器

1) Tex Live 2026 下载与安装 (https://tug.org/texlive/windows.html)，安装并不是什么困难事情(双击install-tl-windows.exe，中间可以根据需求修改安装目录，可参考https://shuqian8421.github.io/posts/50991/index.html）

2) 手动添加环境变量：系统环境变量-> Path-> 新建，复制粘贴安装目录(参考下图)

3）帮助LaTeX Workshop 找到编译器，在 VS Code 全局 settings.json 中配置 xelatex/bibtex 的完整路径，步骤：Ctrl+Shift+P，搜索输入 Preferences: Open User Settings (JSON)，复制以下内容，粘贴至json文件中

{
    "claudeCode.preferredLocation": "panel",
    "chat.viewSessions.orientation": "stacked",
    "[markdown]": {
        "diffEditor.ignoreTrimWhitespace": false
    },
    "workbench.colorTheme": "Visual Studio Dark - C++",
    "claudeCode.environmentVariables": [


    ],
    "editor.accessibilitySupport": "on",
    "workbench.settings.applyToAllProfiles": [
        

    ],
    "latex-workshop.latex.autoBuild.run": "never",
    "latex-workshop.showContextMenu": true,
    "latex-workshop.intellisense.package.enabled": true,
    "latex-workshop.message.error.show": false,
    "latex-workshop.message.warning.show": false,
    "latex-workshop.latex.tools": [
        {
            "name": "xelatex",
            "command": "D:/Tex/texlive/2026/bin/windows/xelatex.exe",
            "args": [
                "-synctex=1",
                "-interaction=nonstopmode",
                "-file-line-error",
                "%DOCFILE%"
            ]
        },
        {
            "name": "pdflatex",
            "command": "pdflatex",
            "args": [
                "-synctex=1",
                "-interaction=nonstopmode",
                "-file-line-error",
                "%DOCFILE%"
            ]
        },
        {
            "name": "latexmk",
            "command": "latexmk",
            "args": [
                "-synctex=1",
                "-interaction=nonstopmode",
                "-file-line-error",
                "-pdf",
                "-outdir=%OUTDIR%",
                "%DOCFILE%"
            ]
        },
        {
            "name": "bibtex",
            "command": "bibtex",
            "args": [
                "%DOCFILE%"
            ]
        }
    ],
    "latex-workshop.latex.recipes": [
        {
            "name": "XeLaTeX",
            "tools": [
                "xelatex"
            ]
        },
        {
            "name": "PDFLaTeX",
            "tools": [
                "pdflatex"
            ]
        },
        {
            "name": "BibTeX",
            "tools": [
                "bibtex"
            ]
        },
        {
            "name": "LaTeXmk",
            "tools": [
                "latexmk"
            ]
        },
        {
            "name": "xelatex -> bibtex -> xelatex*2",
            "tools": [
                "xelatex",
                "bibtex",
                "xelatex",
                "xelatex"
            ]
        },
        {
            "name": "pdflatex -> bibtex -> pdflatex*2",
            "tools": [
                "pdflatex",
                "bibtex",
                "pdflatex",
                "pdflatex"
            ]
        }
    ],
    "latex-workshop.latex.clean.fileTypes": [
        "*.aux",
        "*.bbl",
        "*.blg",
        "*.idx",
        "*.ind",
        "*.lof",
        "*.lot",
        "*.out",
        "*.toc",
        "*.acn",
        "*.acr",
        "*.alg",
        "*.glg",
        "*.glo",
        "*.gls",
        "*.ist",
        "*.fls",
        "*.log",
        "*.fdb_latexmk"
    ],
    "latex-workshop.latex.autoClean.run": "onFailed",
    "latex-workshop.latex.recipe.default": "lastUsed",
    "latex-workshop.view.pdf.internal.synctex.keybinding": "double-click"
}

代码包括 VS Code 通用设置

| 配置项 | 当前值 | 功能 |

| `claudeCode.preferredLocation` | `"panel"` | Claude Code 显示在底部面板而非侧边栏 |

| `chat.viewSessions.orientation` | `"stacked"` | 聊天会话以堆叠方式排列 |

| `[markdown].diffEditor.ignoreTrimWhitespace` | `false` | Markdown 文件对比时不忽略首尾空格差异 |

| `workbench.colorTheme` | `"Visual Studio Dark - C++"` | 深色主题 |

| `editor.accessibilitySupport` | `"on"` | 开启无障碍辅助（可能导致某些性能下降，如不需要可关闭） |

LaTeX Workshop 设置

| 配置项 | 当前值 | 功能 |

| `autoBuild.run` | `"onSave"` | 保存 .tex 文件时自动编译 |

| `view.pdf.viewer` | `"tab"` | PDF 在 VS Code 标签页内预览，编译后自动刷新 |

| `showContextMenu` | `true` | 右键菜单显示 LaTeX 相关操作 |

| `intellisense.package.enabled` | `true` | 自动补全 LaTeX 宏包命令 |

| `message.error.show` | `false` | 不弹窗显示编译错误（在日志中仍可查看） |

| `message.warning.show` | `false` | 不弹窗显示编译警告 |

| `latex.recipe.default` | `"lastUsed"` | 默认使用上次选择的编译方案 |

| `view.pdf.internal.synctex.keybinding` | `"double-click"` | 双击 PDF 可跳转到对应 .tex 源码位置 |

| `latex.autoClean.run` | `"onFailed"` | 编译失败时自动清理临时文件 |

LaTeX 编译工具（tools）

| 工具名 | 命令 | 说明 |

| `xelatex` | `D:/Tex/.../xelatex.exe` | XeLaTeX 编译器（支持中文，完整路径） |

| `pdflatex` | `pdflatex` | PDFLaTeX（未配完整路径，**会报错**） |

| `latexmk` | `latexmk` | 自动化编译工具（未配完整路径，**会报错**） |

| `bibtex` | `D:/Tex/.../bibtex.exe` | BibTeX 参考文献处理（已配完整路径） |

LaTeX 编译方案（recipes）

| 方案名 | 步骤 | 说明 |

| `XeLaTeX` | xelatex × 1 | 快速编译，不处理参考文献 |

| `PDFLaTeX` | pdflatex × 1 | 会报错（pdflatex 不在 PATH） |

| `BibTeX` | bibtex × 1 | 单独处理参考文献 |

| `LaTeXmk` | latexmk × 1 | 会报错（latexmk 不在 PATH） |

| `xelatex -> bibtex -> xelatex*2` | xelatex → bibtex → xelatex × 2 | **完整编译**，含参考文献处理 |

| `pdflatex -> bibtex -> pdflatex*2` | pdflatex → bibtex → pdflatex × 2 | 会报错 |

清理文件类型（clean.fileTypes）

编译失败时自动清理的临时文件：`.aux`, `.bbl`, `.blg`, `.idx`, `.ind`, `.lof`, `.lot`, `.out`, `.toc`, `.acn`, `.acr`, `.alg`, `.glg`, `.glo`, `.gls`, `.ist`, `.fls`, `.log`, `.fdb_latexmk`

备注

- `pdflatex` 和 `latexmk` 未配置完整路径，选到这些方案会报错，可补上路径或删除不用的方案

- TeX Live 安装路径：`D:/Tex/texlive/2026/bin/windows/`

问题2：编译后需要手动打开 PDF 预览

每次 `Ctrl+Alt+B` 编译后，还需要再按 `Ctrl+Alt+V` 才能查看 PDF。解决方案：

在全局设置中添加：

{

    "latex-workshop.latex.autoBuild.run": "onSave",

    "latex-workshop.view.pdf.viewer": "tab",

    "latex-workshop.view.pdf.internal.synctex.keybinding": "double-click"

}

问题3：Overleaf Git 同步配置中Overleaf 拒绝密码登录（403）

Overleaf Git 同步配置

步骤1：初始化本地 Git 仓库

cd "c:/Users/89265/Desktop/manuscript"
git init

步骤2：添加 Overleaf 远程仓库

git remote add overleaf https://git.overleaf.com/<project-id>


#其中 `<project-id>` 从 Overleaf 项目 URL 中获取：https://www.overleaf.com/project/<project-id>` → 取最后一段。

提示错误：

remote: Overleaf now only supports Git authentication tokens to access git.

fatal: The requested URL returned error: 403

原因分析：Overleaf 已于近期停止支持用户名+密码的 Git 认证方式，必须使用 Git Authentication Token。解决方案：

1. 登录 Overleaf → 左上角头像 → **Account Settings**

2. 找到 **Git Integration** 部分

3. 点击 **Generate Token**

4. 复制生成的令牌（格式如 `olp_xxxxxx...`）

按照直觉用 Overleaf 登录邮箱作为 Git 用户名：

# 尝试1：用 foxmail 邮箱 — 失败

git clone https://xxx%40foxmail.com:olp_xxx@git.overleaf.com/<id>

# 结果：403

# 尝试2：用 Yale 邮箱 — 失败

git clone https://xxx%40aya.yale.edu:olp_xxx@git.overleaf.com/<id>

# 结果：403

令牌认证仍然 403，根本原因：Overleaf Git 认证的用户名是固定的 `git`，不是邮箱地址！这一点在 Overleaf 官方文档中没有明显说明，极易踩坑。解决方法：远程 URL 改为 https://git:<token>@git.overleaf.com/<project-id>

# 修复命令bash
git remote set-url overleaf "https://git:<your-token>@git.overleaf.com/<project-id>"

备注：<project-id>：即为overleaf中项目网址后的数字

问题4：Force push 被拒绝

本地仓库和 Overleaf 历史不同，git push --force 被禁止。

remote: error: forced push prohibited

remote: hint: You can't git push --force to a Overleaf project.

解决方法：先 git pull overleaf master --allow-unrelated-histories 合并，再正常 push

# 先合并 Overleaf 的历史（允许不相关历史合并）
git pull overleaf master --allow-unrelated-histories --no-edit

# 再正常推送
git push overleaf master

Overleaf-VsCode完整工作流

1 . 最终的远程配置

# Overleaf 远程
git remote add overleaf "https://git:<your-token>@git.overleaf.com/<project-id>"


# GitHub 远程（可选，用于备份）
git remote add github "https://github.com/<username>/<repo>.git"

2. 日常操作

#本地修改后同步到 Overleaf
git add Manuscript_IEEE\xx_Journal.tex  # 添加修改的文件
git commit -m "更新说明"                 # 提交
git push overleaf master                # 推送到 Overleaf


#从 Overleaf 拉取他人修改
git pull overleaf master                # 拉取 Overleaf 最新内容


# 同时推送到 GitHub（可选）
git push github master                  # 推送到 GitHub