PDF 与 SyncTeX

概览

TeX64 提供集成的 PDF 预览以及 SyncTeX 双向导航功能。在编辑源代码时，PDF 预览会实时更新，使编辑器与 PDF 查看器始终保持完全同步。

通过 SyncTeX，您可以即时看到源代码中的光标位置对应于 PDF 中的何处，反之亦然——点击 PDF 即可直接跳转到对应源码。可从多种视图模式中选择，匹配您的工作流。

平台说明：TeX64 目前面向 macOS（Apple Silicon 与 Intel）发布。Windows 与 Linux 版本仍在计划中、尚未提供，因此下文的快捷键以 macOS 按键为准。文中出现的 Windows/Linux 对应按键，将在相应版本发布后生效。

PDF 预览模式

TeX64 会在构建成功时自动更新 PDF。选择最适合您项目规模与显示器配置的查看模式。

集成查看器（同一窗口）

构建成功时自动更新 PDF。编辑器与 PDF 集成显示在同一窗口中。该模式适合单显示器环境或紧凑布局。PDF 预览可置于编辑器下方或旁侧，便于频繁切换。

分屏视图（垂直/水平）

将编辑器与 PDF 并排显示（垂直分屏）或上下显示（水平分屏）。在 macOS 上使用 Cmd+\ 切换（Windows/Linux 版本发布后为 Ctrl+\）。

在宽屏显示器上，将编辑器置于左侧、PDF 预览置于右侧，可同时查看源与输出，工作更高效。当使用较大字号或缩放级别时，水平分屏模式更具可读性。

分离模式（独立窗口）

将 PDF 查看器分离为独立窗口，在另一空间打开。此模式在多显示器布局下尤为强大。可在主显示器显示 TeX64，同时在副显示器全屏显示 PDF，进行演示级审阅与更宽视角的查看。

构建失败时的行为

若构建失败，TeX64 会保留上次成功生成的 PDF。绝不会显示损坏或部分渲染的 PDF 文件。这样您可以在修复错误时以最后一次成功的版本作为参考。

PDF 查看器操作

TeX64 的 PDF 查看器支持标准导航操作。

缩放控制

  • 放大：使用 Cmd+=（Mac）或 Ctrl+=（Windows/Linux）放大。
  • 缩小：使用 Cmd+-（Mac）或 Ctrl+-（Windows/Linux）缩小。
  • 重置缩放：使用 Cmd+0（Mac）或 Ctrl+0（Windows/Linux）将缩放重置为默认。
  • 还可以使用鼠标滚轮、触控板或捏合手势进行缩放。

滚动导航

  • 滚动 PDF 浏览任意内容。可使用方向键、滚轮或触控板进行导航。
  • 按空格或 PageDown 前往下一页，按 Shift+空格 或 PageUp 返回上一页。

页面导航

  • Home/End：跳转至文档的首页或末页。
  • 点击 PDF 查看器顶部的页码指示器，可直接跳到指定页面。

自动刷新行为

TeX64 持续监视源代码的变更。当构建成功时，PDF 会自动更新。

构建成功时

当构建成功完成后，TeX64 会自动重新加载 PDF 以显示最新内容。默认情况下，滚动位置会回到文档顶部。

滚动位置保持

TeX64 会尽可能在 PDF 更新时保持您的滚动位置。对于小幅修改，您将继续查看相同的区段。对于改变文档结构的大幅修改，滚动位置可能会被重置。

构建失败时的保持

如果构建失败，将继续显示上次成功的 PDF。您可以查看错误信息，并在再次构建前进行修复。

正向 SyncTeX（源 → PDF）

正向 SyncTeX 可即时识别并显示编辑器中光标位置在 PDF 中的对应位置。实时查看源代码改动如何反映在输出中。

光标位置高亮

当您在编辑器中放置光标时，TeX64 会高亮或在 PDF 中显示对应区域的视觉指示器。您可以即时看到任意元素——从小段文字到大段、段落、章节与插图——在输出中的位置。

实时更新

高亮会实时更新。每次移动光标，PDF 视图都会即时跟随更新。查看器会自动滚动到高亮位置，让您始终看到当前的编辑位置。

视觉指示器

PDF 上会出现视觉标记——如矩形、背景色或图标——指示当前光标位置所对应的区域。这让您即使在复杂文档中也能清楚地知道源代码的哪一部分对应 PDF 中的哪个位置。

反向 SyncTeX（PDF → 源）

反向 SyncTeX 让您可以点击 PDF 直接跳到源代码中的对应行。在阅读 PDF 时，当发现需要修改的地方，可立即前往源代码进行编辑。

Cmd+点击 跳转

  • Mac：按住 Cmd 并点击 PDF 内的文字或元素。
  • Windows/Linux（计划中）：相应版本发布后，按住 Ctrl 并点击 PDF 内的文字或元素。

即时导航

点击后，TeX64 将编辑器置于前台，并自动将光标跳转到对应的源代码行。行号会被高亮，光标会定位到该行开头。对于跨多行的块（如段落或 figure 环境），将跳转到块的起始行。

多文件项目中的行为

反向 SyncTeX 在多文件项目中尤其强大。在通过 \input 或 \include 拆分的文件中，点击元素后，正确的外部文件会自动打开并跳转到对应行。无论项目结构如何，都能实现精准导航。

精确定位

跳转精度取决于 TeX64 从 SyncTeX 文件读取的信息粒度。通常可按段落级精度跳转到正确的行，但某些 LaTeX 宏包可能导致更粗的精度（如页级）。

多文件项目支持

SyncTeX 在通过 \input 与 \include 命令拆分的多文件 LaTeX 项目中完全可用。正确配置主文件与精准的路径至关重要。

理解 \input 与 \include

  • \input：在当前位置直接引入指定文件，不会分页。
  • \include：在新页面开始处引入指定文件。可用 \excludeonly 单独排除。

两种方式均被 SyncTeX 完整支持，可在文件间准确追踪对应关系，实现双向导航。

主文件的重要性

TeX64 会自动尝试检测项目的主文件（含 \begin{document} 的主文件）。在存在多个 LaTeX 文件时，您可能需要明确指定哪一个应被视为主文件。

若未正确设置主文件，SyncTeX 将无法工作。请通过菜单「设置主文件」进行设置，或在项目设置中指定。

跨文件跳转

正向与反向 SyncTeX 在多文件之间均可无缝工作。无论编辑器中哪个文件处于活动状态，光标位置都能准确反映到 PDF 的对应位置。同样地，从 PDF 跳转时，正确的相关文件会自动打开。

SyncTeX 所需条件

SyncTeX 要正常工作需要若干组件。

synctex 二进制

  • 必须安装 synctex 命令行工具。
  • 如已安装 MacTeX，则 synctex 会自动包含其中。
  • TeX Live 安装中也包含 synctex。
  • 验证安装：在终端运行「which synctex」。若显示路径，则表示已安装。

.synctex.gz 文件生成

  • latexmk 必须在编译时自动生成 .synctex.gz 文件。
  • TeX64 的构建过程默认启用 .synctex.gz 生成。
  • 构建成功后，请确认项目目录中存在 .synctex.gz 文件。

latexmk 配置

  • 在 .latexmkrc 或 latexmkrc 文件中配置 SyncTeX 生成选项。
  • 推荐：$pdf_mode = 1;（pdflatex）或 $pdf_mode = 4;（lualatex/xelatex）

TeX64 环境验证

在 TeX64 的「设置 > 环境」菜单中可验证可用的 TeX 环境。绿色对勾（✓）表示 synctex 已正确安装。

PDF 文字搜索

您可在 PDF 查看器内搜索文字。使用 Cmd+F（Mac）或 Ctrl+F（Windows/Linux）打开搜索框。

搜索功能

  • 输入搜索词后自动高亮 PDF 中的所有匹配项。
  • 在结果间导航：使用上下箭头按钮或 Enter 键移动到下一个/上一个匹配项。
  • 匹配计数：搜索框会显示找到的匹配项总数。

PDF 注释与编辑

TeX64 的 PDF 查看器为只读预览，不支持在 PDF 中直接添加注释、标记或手写编辑。

若需要为 PDF 添加注释，请使用其他 PDF 编辑应用（如 Preview.app、Adobe Acrobat、PDFExpert 等）。TeX64 的 PDF 查看器专注于面向审阅、参考与导航的快速预览。

连续预览工作流

TeX64 的 PDF 预览与自动构建系统紧密集成。启用自动构建后，每次保存源代码都会自动编译并更新 PDF。

实时预览工作流

  1. 在 TeX64 中打开 LaTeX 文件，在编辑器中编辑代码。
  2. 保存文件（Cmd+S / Ctrl+S）。
  3. TeX64 自动开始编译（若启用了自动构建）。
  4. 编译完成后，PDF 即时更新。
  5. 点击 PDF（Cmd+Click）跳转到源码，或移动源码光标以在 PDF 中高亮对应位置。

启用自动构建

可在 TeX64 设置菜单中启用自动构建。启用后，文件变更被检测到约 0.5 秒后即自动开始编译。

疑难解答

SyncTeX 与 PDF 预览的常见问题及其解决方法。

SyncTeX 不工作

  • 检查 1：synctex 安装：在终端运行「which synctex」以确认 synctex 已安装。若无输出，请重新安装您的 TeX 环境。
  • 检查 2：TeX64 环境检查：在 TeX64 的 设置 > 环境 中确认是否显示绿色对勾。
  • 检查 3：主文件设置：对于多文件项目，请确认主文件是否设置正确。

找不到 .synctex.gz

  • 重新构建项目（按 Cmd+B 或点击构建按钮）。
  • 构建成功后，请确认项目目录中存在 .synctex.gz 文件。
  • 如未生成该文件，请检查您的 latexmk 配置。

跳转不精确

  • 某些 LaTeX 宏包（tikz、pgfplot 等）可能干扰源映射。
  • 大量使用宏命令会使源到输出的映射复杂化，降低跳转精度。
  • 在此情况下，可同时使用正向与反向 SyncTeX 交互以确定大致位置。

多文件项目的问题

  • 未设置主文件：在 TeX64 菜单中使用「设置主文件」，并选择包含 \begin{document} 的主文件。
  • 路径指定错误：确认 \input 与 \include 中指定的路径准确。若使用相对路径，请确认其相对于主文件正确无误。
  • 若外部文件无法打开，请检查路径分隔符（Mac 上为正斜杠，Windows 上为反斜杠）。

PDF 不更新

  • 请查看构建输出面板是否存在错误。若构建失败，PDF 不会更新。
  • 确认是否启用了自动构建。尝试手动构建（Cmd+B）。
  • 若构建成功但 PDF 未更新，请尝试重启 TeX64。

通用修复方法

  • 重新构建项目：从菜单执行「清理构建」或「重建」。
  • 重启 TeX64：关闭后重新打开应用程序。
  • 检查 TeX 环境：在 设置 > 环境 中确认 TeX/LaTeX 的安装状态。

性能优化

对于大型 PDF 文档或资源密集的 LaTeX 文件，可优化 TeX64 的性能。

处理大型 PDF

  • TeX64 采用逐页渲染策略，以高效处理大型 PDF。
  • 仅渲染可见区域：屏幕外的页面不会加载到内存。
  • 延迟加载：渲染随页面滚动逐步进行。

渲染优化

  • GPU 加速：在受支持的系统上使用 GPU 加速渲染。
  • 缓存：先前已渲染的页面会被缓存，加快导航速度。
  • 自适应质量：根据缩放级别与内存使用情况自动调整渲染质量。

减少编译时间

  • 增量编译：latexmk 仅重新编译必要部分。
  • 草稿模式：在 \documentclass 选项中使用 draft 模式，可简化图像处理。
  • 移除未用宏包：删除未使用的 \usepackage 命令可缩短编译时间。

如有疑问或需要支持，请访问支持页面。