MacOS 安装 LaTeX 全流程：用 TaoToken 统一 Key 打通 MacTeX 与 VS Code 配置

1. 为什么在 MacOS 上装 LaTeX 总卡在第一步如果你在 MacOS 上写论文、做简历或者整理技术文档LaTeX 几乎是绕不开的工具。它不像 Word 那样所见即所得而是用标记语言描述排版编译后输出 PDF公式、交叉引用、参考文献的稳定性远超普通编辑器。但很多人第一次装 LaTeX 就卡住了MacTeX 安装包 4GB 起步下载慢、装完不知道装到哪了VS Code 里装了 LaTeX Workshop 却不知道怎么配 recipes中文文档一编译就报字体缺失再加上现在写文档还想顺手接个 AI 辅助工具密钥散落在各个插件里管理起来更乱。这篇就按「MacOS 安装 LaTeX 全流程」来走一遍先用 MacTeX 把本地编译环境搭好再在 VS Code 里配置 LaTeX Workshop给出可以直接复制的 settings.json 骨架最后用 TaoToken 的统一 Key 把 AI 辅助写作工具的密钥通道收拢到一处。目标很明确——一次跑通中文文档编译并且让后续接 AI 工具时不用到处翻密钥。适合谁看刚换 Mac 的学生、需要写论文的科研党、想用 VS Code 写技术文档的开发者。全程命令和配置都给全跟着敲就行。2. 前置准备MacTeX 安装与 TaoToken Key 通道2.1 MacTeX 安装命令与验证MacTeX 是 TeX Live 在 MacOS 上的完整发行版包含 xelatex、pdflatex、latexmk、bibtex 等全套工具。官方下载地址是 tug.org/mactex安装包约 4GB。如果你用 Homebrew也可以走 cask# 方式一Homebrew 安装推荐便于后续升级 brew install --cask mactex # 方式二下载 dmg 后双击安装一路下一步即可 # 安装完成后新开一个终端窗口让 PATH 生效安装完成后验证是否可用which xelatex xelatex --version latexmk --version正常会输出类似XeTeX 3.141592653-2.6-0.999995的版本信息。如果提示 command not found说明 PATH 没生效执行下面这行再试eval $(/usr/libexec/path_helper)MacTeX 默认会把二进制放到/Library/TeX/texbin这个目录通常由 path_helper 自动加载。装完 MacTeX 后本地编译能力就已经具备了VS Code 只是调用这些命令行工具。2.2 TaoToken 统一 Key 的作用写文档时经常想接 AI 做润色、翻译、公式解释但每个插件都要单独填 Key换工具就得重新配。TaoToken 提供统一的 API 通道一个 Key 可以给多个 AI 辅助工具复用。你可以在官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 了解整体能力API 入口是 https://taotoken.net/api。先去控制台创建 Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 然后在 API Keys 页面生成https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。生成的 Key 先存到环境变量里后面配置工具直接引用避免明文写进配置文件。# 写入 shell 配置MacOS 默认 zsh echo export TAOTOKEN_API_KEY你的Key ~/.zshrc source ~/.zshrc echo $TAOTOKEN_API_KEY这样任何支持读取环境变量的工具都能拿到同一个 Key换工具不用改代码。3. VS Code 配置 LaTeX Workshop 可复制骨架3.1 安装插件打开 VS Code在扩展面板搜索LaTeX Workshop安装。它负责编译、预览 PDF、正向反向跳转。中文文档建议再装LTeX做语法检查可选。3.2 settings.json 完整骨架按CmdShiftP输入Open User Settings (JSON)把下面内容合并进去。这份配置的核心是用 xelatex 编译中文、latexmk 做自动构建、清理中间文件、开启 SyncTeX 双向跳转。{ latex-workshop.latex.autoBuild.run: onSave, latex-workshop.latex.autoBuild.cleanAndRetry.enabled: true, latex-workshop.latex.autoClean.run: onFailed, latex-workshop.view.pdf.viewer: tab, latex-workshop.synctex.afterBuild.enabled: true, latex-workshop.view.pdf.internal.synctex.keybinding: double-click, latex-workshop.intellisense.package.enabled: true, latex-workshop.showContextMenu: true, editor.wordWrap: on, 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, *.gz ], latex-workshop.latex.recipes: [ { name: xelatex, tools: [xelatex] }, { name: xelatex - bibtex - xelatex x2, tools: [xelatex, bibtex, xelatex, xelatex] }, { name: latexmk (xelatex), tools: [latexmk-xelatex] } ], latex-workshop.latex.tools: [ { name: xelatex, command: xelatex, args: [ -synctex1, -interactionnonstopmode, -file-line-error, -pdf, %DOC% ] }, { name: bibtex, command: bibtex, args: [%DOCFILE%] }, { name: latexmk-xelatex, command: latexmk, args: [ -synctex1, -interactionnonstopmode, -file-line-error, -xelatex, -outdir%OUTDIR%, %DOCFILE% ] } ] }保存后重启 VS Code。这份配置里latexmk-xelatex是最省心的 recipe它会自动判断需要编译几次、要不要跑 bibtex中文文档用 xelatex 引擎避免字体问题。3.3 中文文档最小示例新建main.tex用 ctex 宏包处理中文\documentclass[UTF8]{ctexart} \title{MacOS LaTeX 测试} \author{你的名字} \begin{document} \maketitle \section{第一节} 这是一个中文测试文档公式示例$E mc^2$。 \end{document}ctexart 会自动调用系统中文字体MacOS 上一般不需要额外配置字体路径。4. 验证请求编译与成功结果4.1 编译动作打开main.tex按CmdAltB触发编译或者保存文件触发自动构建。VS Code 右侧会弹出 PDF 预览标签页。如果一切正常你会看到标题、作者、中文正文和公式都正确渲染。命令行验证也可以直接跑cd 你的文档目录 latexmk -xelatex -synctex1 -interactionnonstopmode main.tex ls -lh main.pdf输出main.pdf且大小不为 0说明编译链路通了。4.2 双向跳转验证在 PDF 预览里双击某段文字编辑器光标会跳到对应源码位置在源码里按CmdAltJPDF 会跳到对应位置。这就是 SyncTeX 的作用写长文档时定位非常快。4.3 接入 AI 辅助验证如果你用支持自定义 API 的 AI 写作插件把 base URL 填https://taotoken.net/apiKey 引用环境变量TAOTOKEN_API_KEY。想先验证模型通道是否通可以直接在模型对话页测试https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。发一条「帮我润色这段 LaTeX 摘要」就能确认 Key 和通道都正常。5. 本篇常见错排查5.1 xelatex: command not foundMacTeX 装完但终端找不到命令多半是 PATH 没刷新。执行eval $(/usr/libexec/path_helper)或者直接检查/Library/TeX/texbin是否存在。VS Code 如果是在装 MacTeX 之前打开的重启一次让它继承新的环境变量。5.2 中文编译报字体缺失报错类似Font SimSun not found。原因是你用了 pdflatex 引擎或者手动指定了 Windows 字体。解决办法recipe 换成 xelatex文档用 ctexart/ctexrep不要手动写\setCJKmainfont{SimSun}。MacOS 上 ctex 会自动选 PingFang 或 Songti。5.3 编译成功但 PDF 不更新LaTeX Workshop 默认可能没开自动构建。检查latex-workshop.latex.autoBuild.run是否为onSave。另外如果 PDF 预览标签页是旧的按CmdAltB重新编译一次或者关掉预览重新打开。5.4 中间文件堆积aux、log、fls 这些文件会越积越多。配置里的latex-workshop.latex.clean.fileTypes已经列全了按CmdShiftP输入LaTeX Workshop: Clean up auxiliary files即可清理。5.5 Key 泄露风险不要把 TaoToken Key 直接写进 settings.json 或提交到 Git。用环境变量引用或者放在不纳入版本管理的本地配置文件里。团队协作时尤其注意。6. 后续怎么用统一 Key 与长期编码本地 LaTeX 环境跑通后AI 辅助写作的接入就简单了。所有支持自定义 API 的工具都指向同一个 base URL 和同一个环境变量 Key换工具只改工具本身不用重新申请密钥。如果你长期用 VS Code 写代码和文档想把 AI 编码能力也接进来可以看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它把编码场景的调用方式整理好了。接入细节和参数说明在文档里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。Claude Code 相关的配置参考https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude-code-anthropicutm_campaignrewrite 。一个实用技巧把TAOTOKEN_API_KEY写进~/.zshrc后VS Code 里所有终端和插件都能读到不用每个工具单独填。如果某个插件只认配置文件就用${env:TAOTOKEN_API_KEY}这种引用方式避免明文。MacTeX 装一次能用很久VS Code 配置存成 gist 或 dotfiles换机器直接同步省得重配。