LaTeX 党福音:Bookokrat SyncTeX 双向搜索让源码与 PDF 同步跳转的秘密
LaTeX 党福音:Bookokrat SyncTeX 双向搜索让源码与 PDF 同步跳转的秘密
如果你是用 LaTeX 写论文的开发者或学生,Bookokrat 的 SyncTeX 双向搜索功能值得重点关注。这款终端 EPUB/PDF/DJVU 阅读器能把 pdflatex 生成的 .synctex.gz 映射文件读进来,实现 PDF 与 LaTeX 源码之间的同步跳转:在 PDF 里点击任意一行,立刻定位到对应的源码行号;反过来,在编辑器里按下 \lv,PDF 就会滚动到那一段内容所在的位置。整个 LaTeX 编译—阅读—调试工作流,不用再在两个窗口间来回切换。
什么是 SyncTeX 双向搜索?
SyncTeX 是 TeX 世界里的标准同步机制,核心是一份与 PDF 同名的侧车文件 .synctex.gz,记录了 PDF 里每个字符块来自哪个 .tex 文件的哪一行。Bookokrat 把这个机制做成了双向:
| 方向 | 操作 | 效果 |
|---|---|---|
| 逆搜索(PDF → 源码) | Ctrl+点击 / 右键 / 普通模式 gd |
打开编辑器并跳到对应源码行 |
| 正搜索(源码 → PDF) | --synctex-forward 命令 |
运行中的 Bookokrat 跳到对应页并滚动到目标位置 |
启用 SyncTeX:只需加一个编译参数
第一步,编译时开启 synctex:
pdflatex --synctex=1 document.tex
编译完成后,PDF 旁边会生成 document.synctex.gz。用 Bookokrat 打开 PDF 时,它会自动发现并激活 SyncTeX,标题栏出现 [SyncTeX] 标记即表示就绪,无需任何额外配置。
逆搜索操作:点击 PDF 直达 LaTeX 源码行
这是最常用的一步。在 PDF 页面上有三种触发方式:
- Ctrl+点击:在点击位置执行逆搜索
- 右键点击:同样定位到点击位置
gd:普通模式(normal mode)下的快捷键,对鼠标选中文本也生效(使用选区锚点位置)
触发后,Bookokrat 会解析出源码文件和行号,然后调用你配置的编辑器命令打开它。编辑器命令写在 ~/.bookokrat_settings.yaml 里:
synctex_editor: "nvim --server /tmp/nvim.sock --remote-send '<C-\\><C-n>:e {file}<CR>:{line}<CR>'"
占位符支持 {file}、{line}、{column} 三个。也可以在应用内按 Space+s 打开 Settings 弹窗,到 Integrations 标签页里修改。
正搜索操作:编辑器一键跳转 PDF 位置
反方向同样简单。在编辑器所在终端执行:
bookokrat --synctex-forward 42:0:main.tex document.pdf
参数格式是 行号:列号:文件。这条命令会通过 Unix socket 发送给正在运行的 Bookokrat 实例,PDF 视图随即跳到对应页并滚动到目标位置。
配合 VimTeX,只需在 init.vim 或 init.lua 里加两行:
let g:vimtex_view_method = 'general'
let g:vimtex_view_general_cmd = 'bookokrat --synctex-forward @line:@col:@tex @pdf'
之后在 Neovim 里按 \lv 就从源码跳到了 PDF,再配合前面的逆搜索,Ctrl+点击 就能跳回编辑器——完整闭环。任何能执行 shell 命令的编辑器都能接进来,不限于 Vim 系。
它是怎么做到的?三个关键机制
- 解析侧车文件:
SyncTexScanner会解析.synctex.gz,同时建立"文件+行号 → PDF 坐标"的正向索引和"PDF 页面上的元素 → 源码位置"的逆向日志,坐标统一换算到 PDF 点单位(72 dpi),核心实现在 src/pdf/synctex.rs。 - 容错的正向搜索:
forward_search找不到精确行号时,会按 ±1、±2、±3 行依次探测(见 src/pdf/synctex.rs),所以光标停在段落中间也能跳对位置;文件名支持完整路径或仅文件名的模糊匹配,\input{}引入的多个.tex文件也都能正确解析。 - Unix socket 进程间通信:打开 PDF 后,Bookokrat 会在临时目录监听一个
bookokrat-stx-<文档名>-<哈希>.sock的 socket(见 src/pdf/synctex.rs),--synctex-forward参数(定义于 src/cli.rs)就是把forward <行> <列> <文件>这行文本发过去。哈希基于 PDF 的规范化路径计算,不同目录下的同名文档不会串线。
质量保障:黄金数据回归测试
这套同步机制不是"能用就行",项目为它准备了一整套回归测试:三份真实编译的 LaTeX 样例(简单三页文档、多文件 \input、包含公式/TikZ/表格的 20 页综合文档)都存放在 tests/testdata/synctex/,并用 synctex 官方命令行工具导出的黄金 JSON 逐条比对正反两个方向的搜索结果。例如三页测试文档的源码见 tests/testdata/synctex/test_main.tex。此外还有 socket 回环测试和多份 VHS 终端录制脚本,其中 vhs_tests/tapes/pdf_synctex.tape 完整演示了正搜索跳页和右键逆搜索的真实交互。
常见问题
Q:没有 .synctex.gz 会发生什么?
SyncTeX 保持静默,PDF 照常阅读,点击也不会触发跳转。重新编译时加 --synctex=1 即可。
Q:配置了 synctex_editor 但点击没反应?
确认编辑器命令本身能手动跑通,并检查 {file}/{line} 占位符拼写。未配置编辑器时,逆搜索只会在右下角弹出提示而不打开编辑器,这属于预期行为。
Q:终端有要求吗? PDF 阅读需要支持图形协议的终端(Kitty、Ghostty 体验最佳,iTerm2、WezTerm 等也可用)。
更多按键和细节可参考应用内置帮助(按 ?),完整说明见 readme.txt 的 SYNCTEX 章节与 README.md。


