1. Ubuntu 下 LaTeX 写作链路到底解决什么问题如果你在 Ubuntu 上写论文、课程报告或者技术文档LaTeX 几乎是绕不开的工具。它和 Word 最大的区别在于你写的是内容加标记排版交给编译器。公式、参考文献、交叉引用、目录这些在 Word 里让人头疼的东西LaTeX 用几行命令就能稳定生成。但新手第一次装 LaTeX往往会卡在三件事上装什么、怎么配、编译报错看不懂。这篇面向 Ubuntu 新手把 TeXLive、TeXstudio、VSCode 三条链路一次讲清楚并且用 TaoToken 的统一 Key 把写作辅助工具的调用凭证管起来。所谓统一 Key就是你把模型调用、代码补全、文档润色这些需要 API 的场景都指向同一个入口不用每个工具单独申请、单独填、单独记。对经常换编辑器或者同时用多个辅助插件的人来说这一步能省掉大量重复配置。适合谁看刚装完 Ubuntu、准备写第一篇 LaTeX 文档的学生从 Overleaf 转到本地、想搞清楚本地编译链路的用户以及已经在用 VSCode 但 LaTeX 编译总是失败、想一次性跑通中文文档的人。整篇的节奏是先装环境再配编辑器最后验证编译每一步都给可复制的命令和配置片段。我试过在几台不同配置的 Ubuntu 机器上从零搭这套环境最深的体会是TeXLive 装全量包虽然大但能避免 90% 的“缺宏包”报错新手别一上来就追求精简。下面按顺序来。2. TaoToken 前置准备统一 Key 与 API 通道在正式配 LaTeX 之前先把 TaoToken 的凭证准备好。原因很简单后面 TeXstudio 和 VSCode 里如果要用到写作辅助、语法检查、文档润色这类能力都需要一个 API 入口。与其每个工具单独配不如统一走一个 Key。TaoToken 的官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基础地址是 https://taotoken.net/api 。注意 API 地址不带 UTM 参数配置的时候直接填这个。你需要拿到两样东西Base URL 和 API Key。Base URL 就是上面那个 https://taotoken.net/api API Key 在控制台的 API Keys 页面生成。生成之后先复制保存因为有些页面刷新后就不再完整显示。具体操作路径打开官网进入控制台找到 API Keys 菜单新建一个 Key。建议给这个 Key 起个能认出来的名字比如 ubuntu-latex方便以后区分用途。生成后你会得到一串以 sk- 开头的字符串这就是你的调用凭证。这里要强调一个概念Base URL 加 API Key 加 Model ID这三件套是任何兼容接口的工具都要填的。Base URL 决定请求发到哪里API Key 决定你有没有权限Model ID 决定用哪个模型。后面不管是在 TeXstudio 里配辅助工具还是在 VSCode 里配插件只要涉及模型调用都是填这三样。如果你只是纯本地编译 LaTeX不涉及任何在线辅助那这一步可以先跳过等需要的时候再回来配。但既然这篇的主题是统一管理写作辅助工具的凭证建议先把 Key 准备好后面直接填。控制台地址https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。拿到 Key 之后先别急着关页面把 Base URL 和 Key 记在一个临时文本里下一步配置要用。3. 可复制配置TeXLive 安装与编辑器 settings 片段这一节是整篇的核心操作区分三块装 TeXLive、配 TeXstudio、配 VSCode。每块都给完整命令或配置文件片段路径和原文一致你可以直接复制。3.1 安装 TeXLive 全量包Ubuntu 下最省心的方式是 apt 安装 texlive-full。它体积大大概几个 GB但宏包齐全中文支持也包含在内。sudo apt update sudo apt install -y texlive-full装完之后验证一下版本tex --version latex --version xelatex --version如果三条命令都能输出版本号说明基础环境 OK。中文文档建议用 xelatex 编译因为它对字体的处理更友好。如果你磁盘紧张也可以只装部分包比如 texlive-latex-extra 加 texlive-lang-chinese但新手容易遇到缺包报错所以这里还是推荐 full。3.2 安装并配置 TeXstudiosudo apt install -y texstudio装完后打开 TeXstudio进入 Options - Configure TeXstudio - Commands确认 XeLaTeX 的路径是 xelatex。默认一般没问题。然后配置中文编译。在文档开头用 ctex 宏包\documentclass[UTF8]{ctexart} \begin{document} 你好LaTeX。 \end{document}TeXstudio 里按 F5 或点编译按钮默认会用 pdflatex。中文建议改成 XeLaTeX在 Options - Configure TeXstudio - Build 里把 Default Compiler 设为 XeLaTeX。如果你要在 TeXstudio 里接入写作辅助工具可以在 Configure TeXstudio - Language Checking 或者外部工具里配置。涉及模型调用的地方填三件套{ base_url: https://taotoken.net/api, api_key: sk-你的Key, model_id: 你的模型ID }注意 base_url 就是 https://taotoken.net/api 不要多加斜杠或路径。api_key 填你刚才生成的。model_id 按你实际要用的填。3.3 配置 VSCode 编译链路先装 VSCode然后装三个插件LaTeX Workshop、LaTeX Utilities、LaTeX-formatter。在扩展市场搜名字安装即可。关键是 LaTeX Workshop 的配置。打开 VSCode 的 settings.json路径是 ~/.config/Code/User/settings.json加入以下片段{ latex-workshop.latex.tools: [ { name: xelatex, command: xelatex, args: [ -synctex1, -interactionnonstopmode, -file-line-error, %DOC% ] }, { name: bibtex, command: bibtex, args: [%DOCFILE%] } ], latex-workshop.latex.recipes: [ { name: xelatex, tools: [xelatex] }, { name: xelatex - bibtex - xelatex*2, tools: [xelatex, bibtex, xelatex, xelatex] } ], latex-workshop.latex.recipe.default: xelatex - bibtex - xelatex*2, latex-workshop.view.pdf.viewer: tab }这段配置定义了编译工具和编译配方。默认配方是 xelatex 加 bibtex 再跑两次 xelatex这样参考文献和交叉引用都能正确生成。如果你在 VSCode 里用辅助插件需要填 API同样用三件套base_url https://taotoken.net/api api_key sk-你的Key model_id 你的模型IDTOML 格式适合一些用配置文件管理凭证的插件。核心还是那三样格式随工具变值不变。配置保存后打开一个 .tex 文件按 CtrlAltB 触发编译或者点左侧的 LaTeX 图标选 Recipe。编译成功会在同目录生成 PDF。4. 验证请求与成功结果一次跑通中文文档配置完不代表能用得实际编译一次。这一节给完整的验证步骤和预期结果。新建一个文件 test.tex内容如下\documentclass[UTF8]{ctexart} \usepackage{amsmath} \usepackage{graphicx} \title{Ubuntu LaTeX 测试} \author{你的名字} \begin{document} \maketitle \section{第一节} 这是一个中文测试文档。 \subsection{公式测试} 行内公式 $E mc^2$多行公式 \begin{align} a^2 b^2 c^2 \\ \int_0^1 x^2 dx \frac{1}{3} \end{align} \subsection{列表测试} \begin{itemize} \item 第一项 \item 第二项 \end{itemize} \end{document}保存后在 VSCode 里按 CtrlAltB或者在终端里直接跑xelatex test.tex预期结果终端输出里能看到 Output written on test.pdf并且没有 Error 字样。同目录下生成 test.pdf打开能看到中文标题、公式和列表都正常显示。如果用的是 TeXstudio按 F5 编译底部日志区显示 Process exited normally右侧预览窗口能看到 PDF。验证 API 通道是否通可以用 curl 发一个最小请求curl https://taotoken.net/api/v1/models \ -H Authorization: Bearer sk-你的Key如果返回模型列表的 JSON说明 Key 和 Base URL 都对。如果返回 401说明 Key 有问题回控制台检查。这一步跑通意味着你的本地编译链路和 API 通道都正常。后面写正式文档直接在这个基础上改就行。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth新手在这一套流程里最容易撞的几个报错我按真实遇到的整理一下对照着查。401 Unauthorized。这个基本是 Key 的问题。检查三件事Key 有没有复制完整有没有多余空格Base URL 是不是 https://taotoken.net/api 。如果 Key 是在别的项目里用过、被撤销了也会 401回控制台重新生成一个。注意请求头格式是 Authorization: Bearer sk-xxxBearer 和 Key 之间有一个空格。local proxy failed。这个报错通常出现在工具尝试走本地代理但代理没起来的时候。检查你的环境变量里有没有 http_proxy 或 https_proxy 指向一个不存在的端口。用 env | grep -i proxy 看一下如果有unset 掉再试。另外确认 Base URL 填的是 https://taotoken.net/api 不要填成 localhost 或 127.0.0.1。reading choices 相关报错。这类错误一般出现在解析模型返回结果的时候提示读取 choices 字段失败。常见原因是返回的不是预期 JSON可能是 Key 无效返回了错误页或者 Model ID 填错了。先确认 Model ID 和你在控制台看到的一致再用 curl 单独测一次接口看返回结构对不对。OAuth 相关报错。如果你用的工具走 OAuth 流程而不是 API Key报错可能提示 token 过期或回调失败。这种情况建议改用 API Key 方式直接填三件套绕开 OAuth 的复杂度。Base URL 用 https://taotoken.net/api Key 用控制台生成的Model ID 按实际填。编译报错缺宏包。如果 xelatex 提示 File xxx.sty not found说明 TeXLive 没装全。回到第 3.1 节确认装了 texlive-full。已经装了还报错跑一下 sudo apt install --reinstall texlive-full。中文不显示或乱码。检查文档类是不是 ctexart编译命令是不是 xelatex。用 pdflatex 编译 ctex 文档容易出问题统一用 xelatex。VSCode 编译没反应。检查 settings.json 有没有语法错误JSON 不允许尾逗号。再看 LaTeX Workshop 的输出面板里面会有具体命令和报错。Recipe 名字要和 recipes 里定义的一致。排障的核心思路是分层先确认 TeXLive 本身能编译再确认编辑器调用了正确的命令最后确认 API 通道能通。哪一层出问题就查哪一层不要混在一起猜。6. 写作链路的长期用法与凭证管理环境跑通之后真正影响效率的是日常怎么用。这里说几个实际经验。第一中文文档统一用 xelatex别在 pdflatex 和 xelatex 之间反复切。VSCode 的默认 recipe 设成 xelatex 那条TeXstudio 的默认编译器也设成 XeLaTeX省得每次手动改。第二参考文献用 bibtex 的话编译顺序是 xelatex - bibtex - xelatex - xelatex。少跑一次 xelatex交叉引用就会显示问号。VSCode 的 recipe 里已经配好了这个顺序直接用。第三凭证管理上把 Base URL、API Key、Model ID 这三件套集中记在一个地方。TaoToken 的统一 Key 好处就在这里不管你换 TeXstudio 还是 VSCode还是以后加别的写作工具填的都是同一组值。Key 如果泄露或者想轮换回控制台重新生成然后更新所有工具里的配置就行。如果你长期做编码或者 Agent 类的工作可以考虑 Coding Plan把调用额度集中管理https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。只是验证模型通不通用模型对话页面就行https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。第四别一上来就啃 LaTeX 语法书。最有效的学习方式是找一篇你目标期刊或课程的 LaTeX 模板下载下来边改边编译遇到不懂的命令再查。模板里通常已经把宏包、格式、参考文献样式都配好了你只需要填内容。这比从零写文档类快得多。第五VSCode 里 LaTeX Workshop 的 PDF 预览支持 SyncTeX在 PDF 里 CtrlClick 能跳回源码对应位置反过来在源码里也能跳到 PDF。写长文档时这个功能很省时间记得在配置里保留 -synctex1 参数。最后环境搭好只是开始真正写起来会遇到各种具体问题比如表格宽度、图片位置、公式编号。这些都可以在用的过程中逐个解决不用提前全部学会。把编译链路和凭证通道先跑通剩下的就是内容的事了。