构建与编译
构建系统概览
TeX64 使用 latexmk 引擎来编译您的 LaTeX 文档。latexmk 会自动管理构建包含参考文献、索引和交叉引用的复杂文档所需的中间步骤。
所有构建均在本地完成，无需互联网连接。TeX64 可完全离线工作，保护您的安全与隐私。编译过程快速且透明。
如何构建
开始构建非常简单。您有以下几种选择：
- 工具栏按钮 — 点击工具栏中的构建按钮（播放图标）。Cmd+B 保留用于在编辑器中插入 \textbf{}。
- 清理构建 — 打开 Settings > Build Profile，然后点击 Clean。若还要删除生成的输出文件，请使用 Clean -C。
构建成功完成后，PDF 预览会自动更新。
构建过程
构建期间，latexmk 会自动管理：
- 多次编译 — LaTeX 通常需要运行 2~3 次以解析交叉引用
- BibTeX/Biber — 自动处理参考文献条目
- 索引生成 — 运行 makeindex 或 xindy 生成索引条目
- 交叉引用 — 确保 \ref、\cite、\pageref 等命令正确解析
- 变更检测 — 若文件未变更则跳过重新构建，节省时间
构建过程中，构建输出会实时显示在日志面板。您可以查看实时进度，准确了解 latexmk 的执行情况。
主文件选择
对于包含多个 .tex 文件的项目，TeX64 会识别哪个文件是您的主（根）文档。它通过扫描只出现在主文件中的 \documentclass 命令来完成识别。
在大多数情况下，自动检测都能正常工作。但若您的项目结构复杂、含有多个 \documentclass 声明，您可在项目设置中手动指定主文件。
TeX64 始终从主文件开始编译。所有其他文件都应通过主文件中的 \input 或 \include 命令引入。
构建配置
TeX64 允许您配置多个构建配置，每个配置都有自己的 LaTeX 引擎和自定义设置。这在需要用不同引擎测试文档时非常有用。
构建配置可在项目设置中创建和管理。每个配置都包含名称、引擎选择以及可选的自定义参数。
构建配置适用于以下场景：
- 用不同引擎测试同一文档（例如 pdflatex 与 xelatex）
- 为正式版本和草稿模式保留独立的构建设置
- 为演示文稿或特殊格式使用自定义引擎选项
支持的引擎
TeX64 支持以下主要 LaTeX 引擎：
pdflatex
pdflatex 是最成熟、使用最广泛的引擎。几乎兼容所有 LaTeX 宏包与模板，是标准文档的理想之选。直接生成 PDF 输出，速度很快。
最适合：学术论文、技术报告、书籍以及大多数标准文档。如果您不确定该用哪种引擎，pdflatex 是安全的选择。
xelatex
xelatex 原生支持 Unicode 与系统字体，是处理中文、日文、阿拉伯文等非拉丁文字的理想选择。您可使用系统中已安装的任意字体。
最适合：多语言文档、非拉丁文字以及需要系统字体的项目。如果您正在处理日文、中文或其他复杂书写系统，xelatex 是正确选择。
lualatex
lualatex 是一款现代引擎，将 Lua 脚本能力与先进字体处理相结合。原生支持 OpenType 字体，允许进行精细的排版控制。
最适合：需要高级脚本、复杂排版或现代字体技术的项目。兼具 xelatex 的优点与 Lua 的可扩展性。
自定义 latexmk 参数
高级用户可添加自定义 latexmk 参数以微调构建行为。这些参数在项目设置中配置。
常用参数包括：
-shell-escape— 启用 \write18 以从 LaTeX 内部运行外部程序（Minted 等宏包需要）-interaction=nonstopmode— 即使出错也继续编译（适用于一次性检查多个问题）-output-directory=— 为 PDF 和中间文件指定自定义输出目录-pdf— 强制启用 PDF 输出模式
编译日志
编译日志显示 LaTeX 编译器与 latexmk 的完整输出。TeX64 会解析此输出，并以颜色编码突出显示错误与警告。
- 错误 — 以红色高亮显示。这些会导致编译失败。
- 警告 — 以黄色或橙色高亮显示。它们不会阻止编译，但可能影响输出质量。
- 消息 — 以灰色显示。这些是有关构建过程的提示信息。
点击日志中的任何错误或警告，可直接跳转到源代码中的对应行。文件名与行号会被高亮，便于快速调试。
错误解析
TeX64 会自动解析 LaTeX 错误以识别正确的文件与行号。
常见错误模式包括：
- Undefined control sequence — 命令未定义或包含拼写错误
- Missing \endcsname inserted — 通常由花括号或圆括号不匹配引起
- File not found — \input 或 \include 所引用的文件不存在
- Package not found — \usepackage 指定的宏包未安装
- Runaway argument — 通常由命令参数中未关闭的花括号引起
LaTeX 经常产生连锁错误，因此找到首个错误至关重要。修复日志中的第一个错误，往往能消除后续大量错误。
AI 辅助调试
TeX64 的 AI 助手可分析您的编译日志并建议错误的修复方法。对于晦涩的 LaTeX 错误信息尤其有用。
在构建失败后使用 AI 调试：
- 点击编译日志面板中的「Ask AI」按钮
- TeX64 将完整的错误上下文发送给 AI
- AI 提示可能的原因与修复方法
AI 的建议是一个有用的起点，但并非总是正确。如果您没有深厚的 TeX 经验，它会特别有帮助。
环境诊断
TeX64 启动时会检查您的系统是否已安装构建所需的全部工具。它会验证：
- latexmk — LaTeX 构建自动化引擎（必需）
- TeX distribution — TeX Live、MacTeX、MiKTeX 或其他 TeX 发行版（必需）
- latexindent — 代码格式化工具（可选但推荐）
- synctex — 源代码与 PDF 同步（可选但推荐）
如果缺少任何必需的工具，TeX64 会发出警告并提供安装指导。
清理构建
清理构建会删除所有中间文件，然后从头重新构建整个文档。
清理构建会移除：
.aux— 辅助文件（交叉引用等）.log— 构建日志.toc— 目录文件.lof, .lot— 图表清单.bbl, .blg— 参考文献文件.fdb_latexmk— latexmk 文件依赖数据库
在以下情况下使用清理构建：
- 构建似乎卡在奇怪的状态，普通构建无法修复
- 进行重大结构变更之后（例如增删章节）
- 怀疑交叉引用或编号出现缓存问题时
- 更改了项目设置或引擎选项后
增量编译
默认情况下，TeX64 使用增量编译。latexmk 会追踪哪些文件已被修改，仅重新运行必要的编译步骤。
这能显著加快小幅修改后的构建。latexmk 在内部追踪依赖关系，只有在确有必要时才执行完整重建。
如果增量编译似乎遗漏了某些更改，请使用清理构建强制完整重建。
构建故障排查
如果构建失败，请检查以下常见问题：
「找不到主文件」
- 确认主文件正确。多文件项目必须从包含 \documentclass 的文件进行编译。
- 确认主文件仍然存在，未被删除或移动。
晦涩的错误信息
- 查看编译日志获取实际错误信息。滚动到第一条错误，而非最后一条——修复首个问题通常能解决连锁错误。
- 使用 TeX64 的 AI 调试来分析复杂的错误信息。
宏包缺失错误
- 确认所有必需的宏包均已用 \usepackage 加载。
- TeX64 会告诉您缺少哪个宏包。按照错误信息中的指引进行安装。
- 在 macOS 上安装 MacTeX 后，大多数宏包都会自动可用。
内存或资源问题
- 含有大量大图或复杂图形的文档可能内存不足。
- 尝试压缩图片或减小其尺寸以降低资源消耗。
- 另一种方法是将大型文档拆分为较小的部分分别编译。
构建缓慢
- 确认增量编译正常工作。大幅修改后可能需要清理构建。
- 复杂的图形与高级排版会显著增加构建时间。
性能优化建议
以下是缩短构建时间的策略：
- 草稿模式 — 在 \documentclass 中添加 draft 选项，跳过图像处理仅编译版式
- 选择性编译 — 使用 \includeonly 仅编译特定章节
- 图像优化 — 将大型位图图像转换为 PDF 或减小其尺寸
- 字体选择 — Computer Modern 字体（默认）比复杂的系统字体编译更快
- TikZ/PGFPlots 优化 — 将复杂图表预编译为 PDF，并作为图像引入
结合运用这些技巧，可显著缩短大型项目的构建时间。