疑难解答
大多数构建失败与 TeX 环境或缺失的包有关。本指南按症状列出常见问题与解决方案。
诊断命令
打开终端并运行：
同时在 TeX64 中检查：设置 > 环境 确认环境状态
TeX 环境问题
"latexmk not found"
原因：TeX 发行版未安装或未加入 PATH
解决：
- 从 https://www.tug.org/mactex/ 安装 MacTeX
- 或：sudo tlmgr install latexmk
- 确认：which latexmk
- 安装后重启 TeX64
"lualatex not found"
原因：TeX 发行版未安装
解决：安装 MacTeX（包含 lualatex）
"latexindent not found"
解决：
注：latexindent 为可选（用于代码格式化），构建无需依赖它
"synctex not found"
解决：MacTeX 默认包含，或：sudo tlmgr install synctex
没有 synctex 则 SyncTeX 导航无法工作
缺少 .sty 包
错误："File xxx.sty not found"
解决：
搜索：
PATH 问题
检查：echo $PATH
应包含 MacTeX 的 /Library/TeX/texbin 或 Homebrew 的 /opt/homebrew/bin
解决：在 ~/.zshrc 中添加：export PATH="/Library/TeX/texbin:$PATH"
重启终端和 TeX64
构建问题
构建失败并报错
查看构建输出面板的错误信息。点击错误跳转到源代码行。
常见原因：LaTeX 命令拼写错误、花括号不匹配、缺失包
提示：使用 AI（Axiom）诊断 - 粘贴错误或在聊天中询问
PDF 未更新
PDF 仅在构建成功时更新。请检查构建输出中的错误。
点击工具栏中的构建按钮重新构建。
构建缓慢
包含大量图片的大型项目耗时更长。
latexmk 采用增量编译 - 第二次构建更快。
首次构建可能因下载包而较慢
SyncTeX 问题
SyncTeX 不工作
确认 synctex 已安装：which synctex
点击工具栏构建按钮重新构建项目，以生成 .synctex.gz 文件
在 设置 > 环境 中确认绿色勾选
SyncTeX 跳转位置错误
某些 LaTeX 包会干扰源映射
多文件项目：确保 \input/\include 路径正确
macOS 问题
Gatekeeper
Control+点击（右键）→ 打开 或：系统设置 > 隐私与安全性 > 允许
屏幕录制权限（用于 OCR）
系统设置 > 隐私与安全性 > 屏幕录制 > 启用 TeX64
授予权限后可能需要重启 TeX64
"App is Damaged"
重新下载 DMG。确认架构正确（Apple Silicon 还是 Intel）
AI/Axiom 问题
AI 功能不可用
先确认已登录，然后检查账户：账户 > 账单
AI（聊天与补全）在所有方案中均可用，免费方案也包含每月少量试用额度。最常见的停用原因是当月 token 配额已用尽（或付款逾期）——请充值或等待下一个周期。
检查 token 配额：账户 > 用量
确认网络连接
AI 响应缓慢或超时
检查网络连接
服务器可能负载较高 - 稍后再试
速率限制：30 次/分钟
账户与登录
Google 登录失败
检查网络连接。尝试清除浏览器 cookie/缓存。重新登录。
订阅未生效
账单变更可能需要几分钟
支付失败时，请通过 Stripe 计费门户更新支付方式
宽限期：支付失败后 3 天功能才会被禁用
画廊问题
投稿上限：Free=10、Basic=100、Pro=500
每日投稿上限：每天 10 条
图片大小：最大 20MB。TeX 源码：最多 500,000 字符。标签：每条投稿最多 8 个。
获取帮助
使用 AI 聊天描述问题（可读取编译日志）
通过 /feedback 联系支持
请提供：macOS 版本、TeX64 版本、错误信息、复现步骤
可在设置 > 隐私中启用可选的错误诊断报告