1. WSL2 里 LaTeX 编译链的真实痛点与场景拆解如果你在 Windows 上写论文、做技术文档大概率经历过这种割裂TeX Live 装在 Windows 下路径里带空格和中文latexmk 时不时抽风换到 WSL2 里装 TeX Live编译是顺了但 VS Code 的 LaTeX Workshop 又找不到 xelatex中文文档一编译就是一堆 missing character。更麻烦的是很多同学还需要在编辑器里调用云端模型做润色、翻译、公式检查结果 WSL2 里的请求走不通插件一直显示离线。这篇就把这条链路一次打通WSL2 Ubuntu TeX Live 完整版 VS Code LaTeX Workshop 中文 xelatex 编译并且把需要走网络的请求统一收敛到 TaoToken 的 API 通道。目标很明确你跟着做完能在一个.tex文件上按一次编译直接出中文 PDF同时编辑器里的模型类请求也能正常发出。先说清楚适合谁一是正在写毕业论文、课程报告的学生二是需要长期维护技术文档的工程师三是习惯 VS Code 但又想要 Linux 下编译体验的人。核心检索词就是 WSL2 安装 TeX Live、VS Code LaTeX Workshop 配置、xelatex 中文编译报错排查这几个词后面会反复出现。我自己的环境是 Windows 11 WSL2 Ubuntu 22.04TeX Live 用的是texlive-full编辑器是 VS Code 加 LaTeX Workshop。下面所有命令和配置都是在这个组合下实测可用的。需要提醒的是texlive-full体积在 5GB 以上安装时间取决于网络建议预留 30 分钟以上别在赶 deadline 的晚上临时装。整个链路的逻辑是这样的WSL2 提供 Linux 运行环境TeX Live 提供编译工具链VS Code 通过 WSL 扩展在 Linux 侧运行 LaTeX Workshop编译产物 PDF 通过 VS Code 内置查看器预览。而需要联网的模型请求则通过配置 Base URL 指向 TaoToken 的统一入口避免在 WSL2 里单独折腾网络设置。这里有个常见误区要先纠正很多人以为 VS Code 装在 Windows 侧就够了其实 LaTeX Workshop 必须在 WSL 侧也安装一份否则它调用的是 Windows 的 shell找不到 WSL 里的 xelatex。这个点后面在扩展安装部分会重点讲。2. TaoToken 前置准备API Key 与统一通道说明在动手配编译链之前先把需要联网的那部分准备好这样后面配置 settings.json 时可以直接填进去不用来回切换。TaoToken 在这里扮演的角色是一个统一的 API 入口你不需要在 WSL2 里单独维护多套 endpoint把 Base URL 指向它Key 填进去模型请求就走同一条通道。先拿 Key。打开控制台地址https://taotoken.net/console登录后进入 API Keys 页面新建一个 Key。建议命名带上用途比如wsl2-latex-vscode方便以后区分。Key 只在创建时完整显示一次复制后先存到安全的地方别直接贴在会提交到 Git 的文件里。拿到 Key 之后你需要记住两个地址。一个是 API 根地址https://taotoken.net/api这个是不带任何追踪参数的干净地址配置里填它。另一个是官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content用来查文档和看模型列表。接入文档在https://taotoken.net/doc里面有各语言 SDK 的示例遇到字段不确定的时候去翻一下比猜快。模型 ID 这块要注意不同模型的名字不一样别凭记忆写。你可以在模型对话页面https://taotoken.net/chat里先选一个模型发一条消息确认它能正常返回然后在请求详情里看到实际使用的模型 ID。常见的比如 Claude 系列、GPT 系列具体以你账号里可用的为准。把 Base URL、Key、Model ID 这三件套记下来后面配置里会用到。如果你后面打算长期做编码类任务比如让模型帮忙改 LaTeX 宏包冲突、生成表格代码可以了解一下 Coding Plan入口在https://taotoken.net/coding-plan。它更适合高频调用场景普通写论文偶尔润色的话按量用 API 就够了。这里要强调一点TaoToken 是合规的 API 服务入口你配置的时候就是正常填 Base URL 和 Key不需要任何额外的网络工具。WSL2 里能不能连通取决于你的 WSL2 网络模式这个在第五节会专门讲镜像网络模式的配置那是解决 WSL2 访问宿主机服务的正路。把 Key 存好之后建议在 WSL2 里用环境变量管理而不是硬编码进配置文件。可以在~/.bashrc里加一行export TAOTOKEN_API_KEY你的Key然后source ~/.bashrc。这样配置文件里引用${env:TAOTOKEN_API_KEY}就行避免 Key 泄露。不过 LaTeX Workshop 本身不读这个变量它主要用于你后续可能装的其它模型类插件。3. 可复制配置TeX Live 安装与 VS Code settings.json这一节是全文的核心所有命令和配置都可以直接复制。先装环境再配编辑器顺序别乱。第一步装 WSL2 和 Ubuntu。以管理员身份打开 Windows PowerShell运行wsl --install这条命令会自动启用所需功能并下载 Ubuntu。完成后重启电脑重启后 Ubuntu 终端会自动启动让你设置 Linux 用户名和密码务必记住。如果已经装过 WSL2用wsl -l -v确认版本是 2不是的话用wsl --set-version Ubuntu 2切换。第二步在 Ubuntu 终端里更新并安装 TeX Live 完整版sudo apt update sudo apt upgrade -y sudo apt install texlive-full -ytexlive-full很大但一次装全后面写论文不会缺宏包。装完验证xelatex --version能看到 TeX Live 和版本号就说明成功了。如果提示 command not found检查一下 PATH或者重新开一个终端。第三步配中文字体。xelatex 编译中文必须能找到字体。装开源字体sudo apt install fonts-noto-cjk fonts-wqy-zenhei -y再补充共享 Windows 字体这样宋体、黑体、楷体都能用。先装 fontconfigsudo apt install fontconfig -y创建配置文件sudo nano /etc/fonts/local.conf粘贴以下内容?xml version1.0? !DOCTYPE fontconfig SYSTEM fonts.dtd fontconfig dir/mnt/c/Windows/Fonts/dir /fontconfig按 CtrlS 保存CtrlX 退出。刷新缓存sudo fc-cache -fv第四步装 VS Code 和扩展。Windows 侧从官网下载安装 VS Code然后装两个扩展WSLMicrosoft 发布和 LaTeX WorkshopJames Yu 发布。装完 WSL 扩展后点左下角绿色图标选择 Connect to WSL。连接成功后再进扩展市场确认 LaTeX Workshop 也装到了 WSL 里通常会提示 Install in WSL: Ubuntu点它。第五步配置 settings.json。在 VS Code 里确保已连接到 WSL按 CtrlShiftP搜索 Preferences: Open User Settings (JSON)粘贴以下配置{ latex-workshop.latex.recipe.default: latexmk (xelatex), latex-workshop.latex.tools: [ { name: latexmk_xelatex, command: latexmk, args: [ -synctex1, -interactionnonstopmode, -file-line-error, -xelatex, %DOC% ] } ], latex-workshop.latex.recipes: [ { name: latexmk (xelatex), tools: [latexmk_xelatex] } ], latex-workshop.latex.autoClean.run: onBuilt, 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.view.pdf.viewer: tab, latex-workshop.message.error.show: true, latex-workshop.message.warning.show: true }这段配置的关键是-xelatex参数它告诉 latexmk 用 xelatex 引擎中文才能正常编译。autoClean.run设为 onBuilt每次编译后自动清理临时文件目录不会越堆越乱。如果你后续要接入模型类请求比如在 VS Code 里用某个支持自定义 endpoint 的插件配置里填 Base URL 为https://taotoken.net/apiKey 用你前面拿到的Model ID 填你在模型对话里确认过的那个。这三件套缺一不可Base URL 决定请求发到哪Key 决定身份Model ID 决定用哪个模型。4. 验证请求中文示例文档编译与结果确认配置写完必须用一份真实的中文文档验证不然你不知道是配置对了还是碰巧没报错。新建一个目录比如~/latex-test在里面创建main.tex\documentclass[12pt]{article} \usepackage{ctex} \usepackage{amsmath} \usepackage{geometry} \geometry{a4paper, margin2.5cm} \title{WSL2 下 LaTeX 中文编译验证} \author{测试} \date{\today} \begin{document} \maketitle \section{中文段落测试} 这是一段中文用来验证 xelatex 能否正确找到字体并排版。 如果这段文字正常显示说明字体配置没问题。 \section{数学公式测试} 行内公式 $E mc^2$行间公式 \begin{equation} \int_{0}^{\infty} e^{-x^2} dx \frac{\sqrt{\pi}}{2} \end{equation} \section{结论} 编译通过链路正常。 \end{document}在 VS Code 里打开这个目录确保左下角显示的是 WSL 连接状态。打开main.tex按 CtrlAltB 触发编译或者点左侧 LaTeX 图标选 Build。第一次编译会稍慢因为要生成字体缓存。编译成功后VS Code 标签页里会显示 PDF 预览。检查三件事中文是否正常显示、公式是否渲染、有没有红色报错。如果中文变成方框或者空白说明字体没找到回到第三节检查fc-cache是否执行成功以及local.conf路径是否正确。再验证一下命令行编译排除 VS Code 的干扰cd ~/latex-test latexmk -xelatex -synctex1 -interactionnonstopmode main.tex如果命令行能出 PDF说明 TeX Live 和字体都没问题问题就在 VS Code 配置。如果命令行也报错看报错信息里提到的宏包或字体名针对性解决。关于模型请求的验证如果你在编辑器里配了走 TaoToken 的插件可以发一条简单请求比如让它把一段中文翻译成英文看是否正常返回。返回正常说明 Base URL、Key、Model ID 三件套填对了。如果报 401检查 Key 是否复制完整如果报连接失败看第五节。编译完成后目录里应该只剩main.tex、main.pdf和main.synctex.gz其它.aux、.log都被自动清理了。这就是autoClean.run: onBuilt的效果。5. 本篇常见报错排查401、local proxy failed 与字体缺失这一节按真实报错来遇到问题直接对号入座。报错一401 Unauthorized。这个通常出现在模型请求里不是 LaTeX 编译。原因就三个Key 没填、Key 填错、Key 前后有空格。检查你配置里的 Key 字段确认是从控制台完整复制的。如果用的是环境变量引用确认变量名拼写一致并且在启动 VS Code 的终端里已经source过。还有一种情况是 Key 被禁用或额度用完去控制台看一下状态。报错二local proxy failed 或连接超时。这个在 WSL2 里很常见本质是 WSL2 默认网络模式下访问不到宿主机的服务。解决办法是用镜像网络模式。在 Windows 用户主目录地址栏输入C:\Users\你的用户名创建.wslconfig文件内容[experimental] networkingModemirrored dnsTunnelingtrue firewalltrue autoProxytrue然后在 PowerShell 里执行wsl --shutdown完全关闭所有 Ubuntu 终端和连到 WSL 的 VS Code再重新打开。镜像网络模式下WSL2 和 Windows 共享网络栈访问外部服务就正常了。注意如果你之前在~/.bashrc里手动加过export HTTP_PROXY...之类的行先注释掉避免冲突。报错三reading choices 相关错误。这个一般出现在模型返回解析阶段说明请求发出去了但返回格式不符合插件预期。检查 Model ID 是否填对有些插件对模型名大小写敏感。另外确认 Base URL 结尾没有多余的斜杠正确写法是https://taotoken.net/api不要写成https://taotoken.net/api/。报错四OAuth 相关提示。如果你用的插件走 OAuth 流程而你想改成 API Key 方式需要在插件设置里切换认证模式。以 Codex 类工具为例它的auth.json里如果残留了旧的 OAuth 凭据会优先走 OAuth。你需要把auth.json里的认证方式改成 API Key并填入 Base URL、Key、Model ID 三件套。文件路径通常在~/.config下对应工具目录里改之前先备份。报错五xelatex 找不到中文字体输出 missing character。这是编译侧最常见的。先确认fc-list :langzh能列出中文字体。如果列不出来说明字体没装好或缓存没刷新重跑sudo fc-cache -fv。如果列出来了但编译还报错检查.tex里用的字体名是否和系统里的一致比如\setCJKmainfont{Noto Serif CJK SC}这个名字要和fc-list输出对得上。报错六latexmk 报 file-line-error 但定位不到行。这通常是宏包冲突或语法错误。先看.log文件里第一个 Error 出现的位置从那里往下读。常见的是ctex宏包和某些模板自带的字体设置冲突解决办法是统一用ctex管理字体别在导言区重复设置。报错七VS Code 里编译按钮没反应。先确认左下角是 WSL 连接状态不是 Windows。再确认 LaTeX Workshop 装在了 WSL 侧。如果都正常打开输出面板选 LaTeX Workshop看它实际执行的命令是什么对比第三节的配置看-xelatex参数有没有生效。6. 长期使用建议与统一通道接入环境搭好之后日常使用还有几个点值得注意能帮你少踩坑。第一项目目录放在 WSL 文件系统里别放在/mnt/c/下。Windows 挂载目录的 IO 性能差latexmk 频繁读写临时文件时会明显变慢。建议放在~/projects/这类 Linux 原生路径下VS Code 通过 WSL 连接打开体验最顺。第二.gitignore里把 LaTeX 临时文件排除掉。虽然autoClean会清理但偶尔中断编译会残留。加一行*.aux、*.log、*.fls之类的规则提交时干净。第三模型请求的 Base URL 统一用https://taotoken.net/api别在多个插件里填不同地址。统一通道的好处是换模型只改 Model ID不用动地址。Key 用环境变量管理配置文件里引用变量降低泄露风险。第四如果你需要频繁调用模型做文档润色、公式检查可以看看 Coding Plan入口在https://taotoken.net/coding-plan。它适合长期高频场景比单次按量更省心。普通写论文的话按量用就够了不用提前买。第五遇到接入问题先查文档https://taotoken.net/doc里有各语言的示例和字段说明。模型对话页面https://taotoken.net/chat可以用来快速验证某个模型是否可用确认 Model ID 再填进配置。API Keys 管理在https://taotoken.net/api-keysKey 丢了或要轮换都在这里操作。最后说一个实际经验WSL2 的镜像网络模式开启后不只是模型请求能通apt更新、git clone这些也会更稳。但改完.wslconfig一定要wsl --shutdown彻底重启只关终端窗口是不够的。这个坑我踩过改了配置没重启排查了半天以为是 Key 的问题。按这套流程走完你的 WSL2 TeX Live VS Code 链路就完整了中文文档能编译PDF 能预览需要联网的模型请求走 TaoToken 统一通道。后面换模板、加宏包基本不用再动环境配置。
1. WSL2 里 LaTeX 编译链的真实痛点与场景拆解如果你在 Windows 上写论文、做技术文档大概率经历过这种割裂TeX Live 装在 Windows 下路径里带空格和中文latexmk 时不时抽风换到 WSL2 里装 TeX Live编译是顺了但 VS Code 的 LaTeX Workshop 又找不到 xelatex中文文档一编译就是一堆 missing character。更麻烦的是很多同学还需要在编辑器里调用云端模型做润色、翻译、公式检查结果 WSL2 里的请求走不通插件一直显示离线。这篇就把这条链路一次打通WSL2 Ubuntu TeX Live 完整版 VS Code LaTeX Workshop 中文 xelatex 编译并且把需要走网络的请求统一收敛到 TaoToken 的 API 通道。目标很明确你跟着做完能在一个.tex文件上按一次编译直接出中文 PDF同时编辑器里的模型类请求也能正常发出。先说清楚适合谁一是正在写毕业论文、课程报告的学生二是需要长期维护技术文档的工程师三是习惯 VS Code 但又想要 Linux 下编译体验的人。核心检索词就是 WSL2 安装 TeX Live、VS Code LaTeX Workshop 配置、xelatex 中文编译报错排查这几个词后面会反复出现。我自己的环境是 Windows 11 WSL2 Ubuntu 22.04TeX Live 用的是texlive-full编辑器是 VS Code 加 LaTeX Workshop。下面所有命令和配置都是在这个组合下实测可用的。需要提醒的是texlive-full体积在 5GB 以上安装时间取决于网络建议预留 30 分钟以上别在赶 deadline 的晚上临时装。整个链路的逻辑是这样的WSL2 提供 Linux 运行环境TeX Live 提供编译工具链VS Code 通过 WSL 扩展在 Linux 侧运行 LaTeX Workshop编译产物 PDF 通过 VS Code 内置查看器预览。而需要联网的模型请求则通过配置 Base URL 指向 TaoToken 的统一入口避免在 WSL2 里单独折腾网络设置。这里有个常见误区要先纠正很多人以为 VS Code 装在 Windows 侧就够了其实 LaTeX Workshop 必须在 WSL 侧也安装一份否则它调用的是 Windows 的 shell找不到 WSL 里的 xelatex。这个点后面在扩展安装部分会重点讲。2. TaoToken 前置准备API Key 与统一通道说明在动手配编译链之前先把需要联网的那部分准备好这样后面配置 settings.json 时可以直接填进去不用来回切换。TaoToken 在这里扮演的角色是一个统一的 API 入口你不需要在 WSL2 里单独维护多套 endpoint把 Base URL 指向它Key 填进去模型请求就走同一条通道。先拿 Key。打开控制台地址https://taotoken.net/console登录后进入 API Keys 页面新建一个 Key。建议命名带上用途比如wsl2-latex-vscode方便以后区分。Key 只在创建时完整显示一次复制后先存到安全的地方别直接贴在会提交到 Git 的文件里。拿到 Key 之后你需要记住两个地址。一个是 API 根地址https://taotoken.net/api这个是不带任何追踪参数的干净地址配置里填它。另一个是官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content用来查文档和看模型列表。接入文档在https://taotoken.net/doc里面有各语言 SDK 的示例遇到字段不确定的时候去翻一下比猜快。模型 ID 这块要注意不同模型的名字不一样别凭记忆写。你可以在模型对话页面https://taotoken.net/chat里先选一个模型发一条消息确认它能正常返回然后在请求详情里看到实际使用的模型 ID。常见的比如 Claude 系列、GPT 系列具体以你账号里可用的为准。把 Base URL、Key、Model ID 这三件套记下来后面配置里会用到。如果你后面打算长期做编码类任务比如让模型帮忙改 LaTeX 宏包冲突、生成表格代码可以了解一下 Coding Plan入口在https://taotoken.net/coding-plan。它更适合高频调用场景普通写论文偶尔润色的话按量用 API 就够了。这里要强调一点TaoToken 是合规的 API 服务入口你配置的时候就是正常填 Base URL 和 Key不需要任何额外的网络工具。WSL2 里能不能连通取决于你的 WSL2 网络模式这个在第五节会专门讲镜像网络模式的配置那是解决 WSL2 访问宿主机服务的正路。把 Key 存好之后建议在 WSL2 里用环境变量管理而不是硬编码进配置文件。可以在~/.bashrc里加一行export TAOTOKEN_API_KEY你的Key然后source ~/.bashrc。这样配置文件里引用${env:TAOTOKEN_API_KEY}就行避免 Key 泄露。不过 LaTeX Workshop 本身不读这个变量它主要用于你后续可能装的其它模型类插件。3. 可复制配置TeX Live 安装与 VS Code settings.json这一节是全文的核心所有命令和配置都可以直接复制。先装环境再配编辑器顺序别乱。第一步装 WSL2 和 Ubuntu。以管理员身份打开 Windows PowerShell运行wsl --install这条命令会自动启用所需功能并下载 Ubuntu。完成后重启电脑重启后 Ubuntu 终端会自动启动让你设置 Linux 用户名和密码务必记住。如果已经装过 WSL2用wsl -l -v确认版本是 2不是的话用wsl --set-version Ubuntu 2切换。第二步在 Ubuntu 终端里更新并安装 TeX Live 完整版sudo apt update sudo apt upgrade -y sudo apt install texlive-full -ytexlive-full很大但一次装全后面写论文不会缺宏包。装完验证xelatex --version能看到 TeX Live 和版本号就说明成功了。如果提示 command not found检查一下 PATH或者重新开一个终端。第三步配中文字体。xelatex 编译中文必须能找到字体。装开源字体sudo apt install fonts-noto-cjk fonts-wqy-zenhei -y再补充共享 Windows 字体这样宋体、黑体、楷体都能用。先装 fontconfigsudo apt install fontconfig -y创建配置文件sudo nano /etc/fonts/local.conf粘贴以下内容?xml version1.0? !DOCTYPE fontconfig SYSTEM fonts.dtd fontconfig dir/mnt/c/Windows/Fonts/dir /fontconfig按 CtrlS 保存CtrlX 退出。刷新缓存sudo fc-cache -fv第四步装 VS Code 和扩展。Windows 侧从官网下载安装 VS Code然后装两个扩展WSLMicrosoft 发布和 LaTeX WorkshopJames Yu 发布。装完 WSL 扩展后点左下角绿色图标选择 Connect to WSL。连接成功后再进扩展市场确认 LaTeX Workshop 也装到了 WSL 里通常会提示 Install in WSL: Ubuntu点它。第五步配置 settings.json。在 VS Code 里确保已连接到 WSL按 CtrlShiftP搜索 Preferences: Open User Settings (JSON)粘贴以下配置{ latex-workshop.latex.recipe.default: latexmk (xelatex), latex-workshop.latex.tools: [ { name: latexmk_xelatex, command: latexmk, args: [ -synctex1, -interactionnonstopmode, -file-line-error, -xelatex, %DOC% ] } ], latex-workshop.latex.recipes: [ { name: latexmk (xelatex), tools: [latexmk_xelatex] } ], latex-workshop.latex.autoClean.run: onBuilt, 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.view.pdf.viewer: tab, latex-workshop.message.error.show: true, latex-workshop.message.warning.show: true }这段配置的关键是-xelatex参数它告诉 latexmk 用 xelatex 引擎中文才能正常编译。autoClean.run设为 onBuilt每次编译后自动清理临时文件目录不会越堆越乱。如果你后续要接入模型类请求比如在 VS Code 里用某个支持自定义 endpoint 的插件配置里填 Base URL 为https://taotoken.net/apiKey 用你前面拿到的Model ID 填你在模型对话里确认过的那个。这三件套缺一不可Base URL 决定请求发到哪Key 决定身份Model ID 决定用哪个模型。4. 验证请求中文示例文档编译与结果确认配置写完必须用一份真实的中文文档验证不然你不知道是配置对了还是碰巧没报错。新建一个目录比如~/latex-test在里面创建main.tex\documentclass[12pt]{article} \usepackage{ctex} \usepackage{amsmath} \usepackage{geometry} \geometry{a4paper, margin2.5cm} \title{WSL2 下 LaTeX 中文编译验证} \author{测试} \date{\today} \begin{document} \maketitle \section{中文段落测试} 这是一段中文用来验证 xelatex 能否正确找到字体并排版。 如果这段文字正常显示说明字体配置没问题。 \section{数学公式测试} 行内公式 $E mc^2$行间公式 \begin{equation} \int_{0}^{\infty} e^{-x^2} dx \frac{\sqrt{\pi}}{2} \end{equation} \section{结论} 编译通过链路正常。 \end{document}在 VS Code 里打开这个目录确保左下角显示的是 WSL 连接状态。打开main.tex按 CtrlAltB 触发编译或者点左侧 LaTeX 图标选 Build。第一次编译会稍慢因为要生成字体缓存。编译成功后VS Code 标签页里会显示 PDF 预览。检查三件事中文是否正常显示、公式是否渲染、有没有红色报错。如果中文变成方框或者空白说明字体没找到回到第三节检查fc-cache是否执行成功以及local.conf路径是否正确。再验证一下命令行编译排除 VS Code 的干扰cd ~/latex-test latexmk -xelatex -synctex1 -interactionnonstopmode main.tex如果命令行能出 PDF说明 TeX Live 和字体都没问题问题就在 VS Code 配置。如果命令行也报错看报错信息里提到的宏包或字体名针对性解决。关于模型请求的验证如果你在编辑器里配了走 TaoToken 的插件可以发一条简单请求比如让它把一段中文翻译成英文看是否正常返回。返回正常说明 Base URL、Key、Model ID 三件套填对了。如果报 401检查 Key 是否复制完整如果报连接失败看第五节。编译完成后目录里应该只剩main.tex、main.pdf和main.synctex.gz其它.aux、.log都被自动清理了。这就是autoClean.run: onBuilt的效果。5. 本篇常见报错排查401、local proxy failed 与字体缺失这一节按真实报错来遇到问题直接对号入座。报错一401 Unauthorized。这个通常出现在模型请求里不是 LaTeX 编译。原因就三个Key 没填、Key 填错、Key 前后有空格。检查你配置里的 Key 字段确认是从控制台完整复制的。如果用的是环境变量引用确认变量名拼写一致并且在启动 VS Code 的终端里已经source过。还有一种情况是 Key 被禁用或额度用完去控制台看一下状态。报错二local proxy failed 或连接超时。这个在 WSL2 里很常见本质是 WSL2 默认网络模式下访问不到宿主机的服务。解决办法是用镜像网络模式。在 Windows 用户主目录地址栏输入C:\Users\你的用户名创建.wslconfig文件内容[experimental] networkingModemirrored dnsTunnelingtrue firewalltrue autoProxytrue然后在 PowerShell 里执行wsl --shutdown完全关闭所有 Ubuntu 终端和连到 WSL 的 VS Code再重新打开。镜像网络模式下WSL2 和 Windows 共享网络栈访问外部服务就正常了。注意如果你之前在~/.bashrc里手动加过export HTTP_PROXY...之类的行先注释掉避免冲突。报错三reading choices 相关错误。这个一般出现在模型返回解析阶段说明请求发出去了但返回格式不符合插件预期。检查 Model ID 是否填对有些插件对模型名大小写敏感。另外确认 Base URL 结尾没有多余的斜杠正确写法是https://taotoken.net/api不要写成https://taotoken.net/api/。报错四OAuth 相关提示。如果你用的插件走 OAuth 流程而你想改成 API Key 方式需要在插件设置里切换认证模式。以 Codex 类工具为例它的auth.json里如果残留了旧的 OAuth 凭据会优先走 OAuth。你需要把auth.json里的认证方式改成 API Key并填入 Base URL、Key、Model ID 三件套。文件路径通常在~/.config下对应工具目录里改之前先备份。报错五xelatex 找不到中文字体输出 missing character。这是编译侧最常见的。先确认fc-list :langzh能列出中文字体。如果列不出来说明字体没装好或缓存没刷新重跑sudo fc-cache -fv。如果列出来了但编译还报错检查.tex里用的字体名是否和系统里的一致比如\setCJKmainfont{Noto Serif CJK SC}这个名字要和fc-list输出对得上。报错六latexmk 报 file-line-error 但定位不到行。这通常是宏包冲突或语法错误。先看.log文件里第一个 Error 出现的位置从那里往下读。常见的是ctex宏包和某些模板自带的字体设置冲突解决办法是统一用ctex管理字体别在导言区重复设置。报错七VS Code 里编译按钮没反应。先确认左下角是 WSL 连接状态不是 Windows。再确认 LaTeX Workshop 装在了 WSL 侧。如果都正常打开输出面板选 LaTeX Workshop看它实际执行的命令是什么对比第三节的配置看-xelatex参数有没有生效。6. 长期使用建议与统一通道接入环境搭好之后日常使用还有几个点值得注意能帮你少踩坑。第一项目目录放在 WSL 文件系统里别放在/mnt/c/下。Windows 挂载目录的 IO 性能差latexmk 频繁读写临时文件时会明显变慢。建议放在~/projects/这类 Linux 原生路径下VS Code 通过 WSL 连接打开体验最顺。第二.gitignore里把 LaTeX 临时文件排除掉。虽然autoClean会清理但偶尔中断编译会残留。加一行*.aux、*.log、*.fls之类的规则提交时干净。第三模型请求的 Base URL 统一用https://taotoken.net/api别在多个插件里填不同地址。统一通道的好处是换模型只改 Model ID不用动地址。Key 用环境变量管理配置文件里引用变量降低泄露风险。第四如果你需要频繁调用模型做文档润色、公式检查可以看看 Coding Plan入口在https://taotoken.net/coding-plan。它适合长期高频场景比单次按量更省心。普通写论文的话按量用就够了不用提前买。第五遇到接入问题先查文档https://taotoken.net/doc里有各语言的示例和字段说明。模型对话页面https://taotoken.net/chat可以用来快速验证某个模型是否可用确认 Model ID 再填进配置。API Keys 管理在https://taotoken.net/api-keysKey 丢了或要轮换都在这里操作。最后说一个实际经验WSL2 的镜像网络模式开启后不只是模型请求能通apt更新、git clone这些也会更稳。但改完.wslconfig一定要wsl --shutdown彻底重启只关终端窗口是不够的。这个坑我踩过改了配置没重启排查了半天以为是 Key 的问题。按这套流程走完你的 WSL2 TeX Live VS Code 链路就完整了中文文档能编译PDF 能预览需要联网的模型请求走 TaoToken 统一通道。后面换模板、加宏包基本不用再动环境配置。
 与 TaoToken 统一 Key 通道的调度实践)
