本地一键解锁 WeMod 的完整功能
2026/9/29 5:34:14
1. WSL Ubuntu 下写 LaTeX 到底卡在哪
如果你在 Windows 上装了 WSL，又在 Ubuntu 里用 VsCode 写 LaTeX，大概率会遇到三类问题：编译命令找不到、中文直接报错、格式化一按就崩。这三个坑我全踩过，而且它们不是孤立的——PATH 没配好会导致latexmk找不到，中文没走 xelatex 会提示缺字库，latexindent 缺 Perl 模块会让格式化直接退出码 2。
这篇教程面向的是已经装好 VsCode、能正常连上 WSL Ubuntu 的读者。我会把整条链路拆成可复制的步骤：先装 TeX Live，再配 PATH，然后装 LaTeX Workshop 插件，接着给出完整的settings.json骨架，最后处理中文和格式化。同时我会把 TaoToken 的统一 Key 接进来，让 AI 辅助写 LaTeX 的时候不用在多个工具之间来回换 Key。
先说清楚 TaoToken 在这里的角色：它是一个统一的 API 通道，你申请一个 Key，就能在 VsCode 的 AI 插件、命令行工具、Coding Agent 里共用同一个入口。对于 LaTeX 这种需要频繁查语法、改公式、调格式的场景，把 AI 接进编辑器能省不少来回搜索的时间。官网入口在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 地址是 https://taotoken.net/api 。
下面按顺序来，每一步都给命令和配置，你跟着敲就行。
2. 前置准备：TeX Live 安装与 PATH 配置
2.1 安装 TeX Live
在 WSL Ubuntu 终端里执行。先下载安装脚本：
wget https://mirror.ctan.org/systems/texlive/tlnet/install-tl-unx.tar.gz如果 wget 慢，换 curl：
curl -L -o install-tl-unx.tar.gz https://mirror.ctan.org/systems/texlive/tlnet/install-tl-unx.tar.gz解压并进入目录：
zcat < install-tl-unx.tar.gz | tar xf - cd install-tl-*开始安装。全量安装大约 8GB，磁盘紧张的话可以在交互界面里去掉不用的语言包：
perl ./install-tl --no-interaction安装完成后，TeX Live 的二进制在/usr/local/texlive/2024/bin/x86_64-linux。注意年份，如果你装的是 2025 版本，把后面所有路径里的 2024 换成 2025。
2.2 配置 PATH（WSL 专用注意点）
WSL 下不要往.bashrc里塞 PATH，用.profile更稳。编辑：
nano ~/.profile在文件末尾追加：
# TeX Live PATH export MANPATH=${MANPATH}:/usr/local/texlive/2024/texmf-dist/doc/man export INFOPATH=${INFOPATH}:/usr/local/texlive/2024/texmf-dist/doc/info export PATH=${PATH}:/usr/local/texlive/2024/bin/x86_64-linux保存后生效：
source ~/.profile如果当前终端没刷新，直接在 PowerShell 里重启 WSL：
wsl --shutdown重新进入后验证：
which xelatex xelatex --version能打印出版本号就说明 PATH 通了。这一步没过，后面插件配置全是白搭。
3. TaoToken 统一 Key 接入 AI 辅助工具
3.1 申请 Key 与确认通道
打开 https://taotoken.net/api-keys ，登录后创建一个 API Key。这个 Key 就是你在各个工具里填的凭证。TaoToken 的 API 基地址是：
https://taotoken.net/api注意：API 地址不带 UTM 参数，直接写https://taotoken.net/api即可。官网首页带 UTM 的是推广链接，配置里不要混用。
3.2 在 VsCode AI 插件里填配置
以常见的 OpenAI 兼容插件为例，在设置里找 API Base / Endpoint 字段，填：
{ "aiAssistant.apiBase": "https://taotoken.net/api", "aiAssistant.apiKey": "你的_TaoToken_Key", "aiAssistant.model": "claude-sonnet-4-20250514" }不同插件字段名不一样，核心就三样：Base URL 指向https://taotoken.net/api，Key 填你申请的，模型名按需选。如果你用的是 Claude Code 这类命令行 Agent，配置方式参考 https://taotoken.net/doc 里的接入说明。
3.3 为什么用统一 Key
我试过在三个工具里分别配三套 Key，改一次要翻三个配置文件。统一到一个 Key 之后，换模型、查用量、排错都只在一个地方看。对于 LaTeX 写作这种需要 AI 帮忙改公式、生成表格、解释报错的场景，编辑器里直接调用比切浏览器快得多。
注意：Key 不要提交到 Git 仓库。放在用户级 settings.json 或者环境变量里，别写进项目目录的
.vscode/settings.json。
4. 可复制配置：settings.json 与中文格式化
4.1 安装 LaTeX Workshop
在 VsCode 里按Ctrl+P，输入：
ext install latex-workshop或者在扩展市场搜 "LaTeX Workshop" 安装。装完后先别急着编译，配置还没写。
4.2 完整 settings.json 骨架
打开 VsCode 设置 JSON（Ctrl+Shift+P搜 "Open Settings (JSON)"），把下面这段合并进去。这是 WSL 远程窗口下的配置：
{ "latex-workshop.latex.tools": [ { "name": "xelatex", "command": "xelatex", "args": [ "--shell-escape", "-synctex=1", "-interaction=nonstopmode", "-file-line-error", "%DOC%" ] }, { "name": "latexmk", "command": "latexmk", "args": [ "--shell-escape", "-synctex=1", "-interaction=nonstopmode", "-file-line-error", "-pdf", "-outdir=%OUTDIR%", "%DOC%" ] }, { "name": "bibtex", "command": "bibtex", "args": ["%DOCFILE%"] } ], "latex-workshop.latex.recipes": [ { "name": "xelatex (中文支持)", "tools": ["xelatex"] }, { "name": "latexmk", "tools": ["latexmk"] }, { "name": "pdflatex -> bibtex -> pdflatex*2", "tools": ["xelatex", "bibtex", "xelatex", "xelatex"] } ], "latex-workshop.latex.autoBuild.cleanAndRetry.enabled": true, "latex-workshop.latexindent.path": "/usr/local/texlive/2024/bin/x86_64-linux/latexindent", "latex-workshop.view.pdf.viewer": "tab", "latex-workshop.showContextMenu": true, "editor.tabSize": 4, "ltex.enabled": true, "ltex.language": "en-US" }关键点说明：latex-workshop.latexindent.path必须指向 TeX Live 自带的 latexindent，不要用系统包管理器装的旧版本，否则格式化行为不一致。recipes里第一个就是 xelatex，中文文档直接选它。
4.3 中文支持：ctex 宏包
测试文档：
\documentclass{article} \usepackage{ctex} \begin{document} 你好，LaTeX。中文测试通过。 \end{document}用 xelatex 编译。如果报Font "SimSun" not found，说明中文字体没装。在 Ubuntu 里装一套：
sudo apt install fonts-noto-cjk然后重新编译。ctex 会自动匹配可用字体，不用手动指定。
4.4 格式化：latexindent 缺模块修复
第一次按格式化（Ctrl+Shift+I）大概率报错：
Can't locate YAML/Tiny.pm in @INC这是 Perl 模块缺失。用 cpan 装：
cpan YAML::Tiny cpan File::HomeDir可能还需要装Log::Log4perl和Unicode::GCString：
cpan Log::Log4perl cpan Unicode::GCString装完再格式化，应该就正常了。如果 cpan 首次运行要初始化，一路回车用默认配置即可。
5. 验证请求与成功结果
5.1 编译验证
新建test.tex，写入上面的中文测试内容。点左侧 TeX 图标，选 "xelatex (中文支持)"，或者按Ctrl+Alt+B。底部终端会输出编译日志，最后出现：
Output written on test.pdf (1 page).右侧标签页自动打开 PDF 预览，中文正常显示，没有方块字。
5.2 格式化验证
在文档里故意把缩进打乱：
\documentclass{article} \usepackage{ctex} \begin{document} 你好。 \end{document}按Ctrl+Shift+I，缩进应该被整理成统一层级。如果没反应，看输出面板的 LaTeX Workshop 日志，确认 latexindent 路径和 Perl 模块都没问题。
5.3 AI 通道验证
在编辑器里调用 AI 插件，让它解释一段 LaTeX 报错。请求能正常返回，说明 TaoToken 的 Key 和 Base URL 配对了。如果返回 401，检查 Key 有没有多余空格；返回 404，检查 Base URL 是不是写成了带路径的形式，正确写法就是https://taotoken.net/api。
模型对话入口在 https://taotoken.net/models ，想先在线试一下模型响应再配到编辑器里，可以从这里进。长期用 Coding Agent 写文档的话，Coding Plan 在 https://taotoken.net/coding-plan 。
6. 本篇常见错排查
6.1 xelatex: command not found
PATH 没生效。检查~/.profile里的路径年份对不对，然后source ~/.profile。WSL 下如果改了.bashrc是没用的，因为非交互式 shell 不读它。
6.2 中文编译报错缺字体
装fonts-noto-cjk后重新编译。如果还是不行，在导言区显式指定：
\usepackage[fontset=fandol]{ctex}fandol 是 TeX Live 自带的字体集，不依赖系统字体。
6.3 latexindent 退出码 2
就是 Perl 模块缺失。按 4.4 节把YAML::Tiny、File::HomeDir、Log::Log4perl、Unicode::GCString都装上。装完用perl -MYAML::Tiny -e 'print "ok"'验证模块能加载。
6.4 编译产物散落一地
在 settings.json 里加：
"latex-workshop.latex.outDir": "%DIR%/build"这样 PDF 和中间文件都进 build 目录，源文件目录保持干净。注意 outDir 改了之后，PDF 预览路径也会跟着变，LaTeX Workshop 会自动处理。
6.5 AI 插件连不上
先确认 Base URL 是https://taotoken.net/api，不要带尾部斜杠，也不要带/v1之类的后缀。然后用 curl 直接测：
curl https://taotoken.net/api/models \ -H "Authorization: Bearer 你的Key"能返回模型列表就说明通道没问题，问题在插件配置。接入文档在 https://taotoken.net/doc ，里面有各工具的详细字段对照。
6.6 WSL 重启后配置丢失
.profile是持久化的，不会丢。但如果你的 WSL 发行版被重置或者换了用户，需要重新配。建议把 PATH 配置和 settings.json 都备份一份，换机器时直接复制。
最后说个实际经验：LaTeX 的报错信息经常指向行号不准，尤其是多文件项目。遇到File ended while scanning这类错误，先看它报的行号前后 10 行，大概率是某个\end{}漏了或者括号没闭合。把 AI 接进编辑器之后，直接选中报错段落让它分析，比手动翻日志快很多。TaoToken 的 Key 配一次，编辑器、命令行、Agent 都能用，省去反复切换的麻烦。