企业官网建设流程全解析

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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 了解整体能力，API 入口是 https://taotoken.net/api。

先去控制台创建 Key：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，然后在 API Keys 页面生成：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。生成的 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 完整骨架

按Cmd+Shift+P，输入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": [ "-synctex=1", "-interaction=nonstopmode", "-file-line-error", "-pdf", "%DOC%" ] }, { "name": "bibtex", "command": "bibtex", "args": ["%DOCFILE%"] }, { "name": "latexmk-xelatex", "command": "latexmk", "args": [ "-synctex=1", "-interaction=nonstopmode", "-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，按Cmd+Alt+B触发编译，或者保存文件触发自动构建。VS Code 右侧会弹出 PDF 预览标签页。如果一切正常，你会看到标题、作者、中文正文和公式都正确渲染。

命令行验证也可以，直接跑：

cd 你的文档目录 latexmk -xelatex -synctex=1 -interaction=nonstopmode main.tex ls -lh main.pdf

输出main.pdf且大小不为 0，说明编译链路通了。

4.2 双向跳转验证

在 PDF 预览里双击某段文字，编辑器光标会跳到对应源码位置；在源码里按Cmd+Alt+J，PDF 会跳到对应位置。这就是 SyncTeX 的作用，写长文档时定位非常快。

4.3 接入 AI 辅助验证

如果你用支持自定义 API 的 AI 写作插件，把 base URL 填https://taotoken.net/api，Key 引用环境变量TAOTOKEN_API_KEY。想先验证模型通道是否通，可以直接在模型对话页测试：https://taotoken.net/model-chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite 。发一条「帮我润色这段 LaTeX 摘要」就能确认 Key 和通道都正常。

5. 本篇常见错排查

5.1 xelatex: command not found

MacTeX 装完但终端找不到命令，多半是 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 预览标签页是旧的，按Cmd+Alt+B重新编译一次，或者关掉预览重新打开。

5.4 中间文件堆积

aux、log、fls 这些文件会越积越多。配置里的latex-workshop.latex.clean.fileTypes已经列全了，按Cmd+Shift+P输入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 Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，它把编码场景的调用方式整理好了。接入细节和参数说明在文档里：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。Claude Code 相关的配置参考：https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claude-code-anthropic&utm_campaign=rewrite 。

一个实用技巧：把TAOTOKEN_API_KEY写进~/.zshrc后，VS Code 里所有终端和插件都能读到，不用每个工具单独填。如果某个插件只认配置文件，就用${env:TAOTOKEN_API_KEY}这种引用方式，避免明文。MacTeX 装一次能用很久，VS Code 配置存成 gist 或 dotfiles，换机器直接同步，省得重配。