Skip to content

References and Zotero

Jump to bottom
zhangxh edited this page Aug 17, 2026 · 4 revisions

文献与 Zotero

TeXLeaf 在 \cite{...} 及用户配置的其他 citation 命令中提供 VS Code 原生 Suggest。候选按来源排序：

  1. 当前 bibliography 中已经存在的有效条目；
  2. Zotero/Better BibTeX 中尚未加入该 bibliography 的条目。

接受已有条目只插入 citation key；接受 Zotero 条目时，TeXLeaf 先导出 BibTeX/BibLaTeX，再把 bibliography 追加和 TeX citation 修改作为同一批文本编辑提交。

前置条件

使用 bibliography 已有条目的补全需要：

  • 工作区已信任；
  • texleaf.enabled 和 texleaf.zoteroCitations 开启；
  • 当前文件已保存为 .tex；
  • language ID 位于 texleaf.languageIds；
  • 光标位于 texleaf.citationCommands 中某个命令的必需大括号参数内。

读取 Zotero 候选还需要：

  • Zotero 桌面端正在运行；
  • Zotero 允许本机其他应用通信；
  • texleaf.zoteroPort 与 Zotero/Better BibTeX 端口一致；
  • 推荐安装与当前 Zotero 版本兼容的 Better BibTeX。

TeXLeaf 面向 VS Code 桌面版。浏览器版 VS Code、纯 Web 扩展环境或无法运行 Node 扩展宿主的环境不能直接使用本机 Zotero 集成。

原生 Suggest 的显示结构

左侧紧凑列表

TeXLeaf 自己创建的候选左侧只显示：

  • 主标签：文献标题；
  • 来源说明：bibliography 文件名，或 Zotero。

左侧不会显示 citation key，也不会再把“作者 · 期刊 · 年份”作为 detail 塞入紧凑列表。这样标题能获得更多横向空间。

右侧详情

选中一个 TeXLeaf 条目后，右侧详情按字段显示：

  • 完整标题；
  • 作者；
  • 期刊 / 出版物；
  • 年份；
  • Citation key；
  • 来源；
  • 已收录 / 未导入状态和接受后的操作说明。

右侧顶部不会再重复一行“作者 · 期刊 · 年份”汇总；这些信息只在下方各自字段中出现。Citation key 仍然保留在详情中，便于接受前核对实际将插入的 key。

搜索与多篇引用

TeXLeaf 会自行对以下字段进行规范化子串匹配：

  • 标题；
  • 作者；
  • 年份；
  • citation key。

搜索会折叠大小写、常见重音和标点差异。例如输入作者姓氏、标题中的几个词、2025 或 key 的一部分，都可以保留相应条目。

在一个 citation 中添加多篇：

\cite{ExistingKey, NewQuery, AnotherKey}

补全只替换光标所在的逗号分段，保留左右 sibling keys；已经出现在同一 \cite{...} 其他分段中的 key 不会再次建议。接受一篇后输入逗号，可以继续搜索并接受下一篇。

如果输入查询、退格删回空分段，再继续输入，TeXLeaf 会用文档版本和当前分段身份重新触发 Suggest，不要求把光标先移出大括号。

bibliography 文件解析

默认文件是：

reference.bib

可通过 texleaf.bibliographyFile 使用工作区内相对 .bib 路径，例如：

{
  "texleaf.bibliographyFile": "bib/sources.bib"
}

安全规则：

  • 不接受绝对路径、URI 或含 .. 的越界路径；
  • 简单文件名会优先使用从当前 TeX 文件向工作区根方向找到的最近同名文件；
  • 文件不存在时在当前工作区根按设置路径创建；
  • 多根工作区按当前 TeX 文档所属根解析，不会跨根选错；
  • 已打开且有未保存修改的 .bib 使用当前 VS Code 文档模型，不会绕过编辑器从磁盘覆盖它。

TeXLeaf 解析常见的花括号、引号、连接值、注释和嵌套字段。未闭合外层条目、重复 key、不安全 key 或明确冲突会阻止自动追加。

已有条目与 Zotero 条目去重

候选和提交阶段按以下身份比较：

  1. 精确 citation key；
  2. 规范化 DOI；
  3. 规范化 ISBN；
  4. 字段足够时，规范化标题 + 第一作者 + 年份。

如果 Zotero 中的同一文献已经以另一个 key 存在于 .bib，只保留 bibliography 中现有项；提交期间才被另一个窗口导入的等价条目，也会复用最新 bibliography key，而不是追加重复记录。

若相同 key 已被明显不同的文献占用，TeXLeaf 会报错并停止，不覆盖原条目。

导入格式与原子编辑

texleaf.bibliographyFormat 可选：

  • bibtex：默认；
  • biblatex。

切换格式只影响之后从 Zotero 导入的新条目，不会重新格式化已有 .bib 内容。

接受 Zotero 候选时：

  1. 重新确认当前 citation、文档版本和逗号分段没有变化；
  2. 从同一个 Zotero library 导出单条记录；
  3. 验证导出只含一个条目，且 key 安全、与候选一致；
  4. 重新读取当前 bibliography 模型并做重复/冲突检查；
  5. 保留原文件的 LF/CRLF 换行风格和条目间空行；
  6. 用同一个 WorkspaceEdit 修改 .tex 和 .bib；
  7. 干净 bibliography 可自动保存；原本 dirty 的 bibliography 保留为 dirty，不替用户保存其他修改。

导出或校验失败时，citation 会恢复/保留用户原来输入的查询，不提交半份导入。一次 Undo 可以一起撤销同一批文本改动。

Better BibTeX 与官方 Local API

TeXLeaf 首先访问：

http://127.0.0.1:<port>/better-bibtex/json-rpc

使用 Better BibTeX 的 library、search 和单条 export 能力，直接采用其权威 citekey，不在 VS Code 端按作者/年份重新生成。

若 Better BibTeX 路由或所需方法不可用，TeXLeaf 会回退 Zotero 官方 Local API：

http://127.0.0.1:<port>/api/

回退路径从 Zotero 的 BibTeX/BibLaTeX 导出文本中取得实际 citation key。缺少可安全导出 key 的记录会单独跳过，不应让整个文库不可用。

默认端口是 23119；Juris-M 常用 24119。端口必须是 1–65535 的整数，主机地址不可配置。

Library 选择

texleaf.zoteroLibrary 默认是 My Library，也可以写：

  • Zotero UI 中显示的库名称；
  • 群组库名称；
  • 内部数字 library ID。

名称不区分大小写匹配时仍要求唯一。两个库同名时，请改用数字 ID。搜索和单条导出使用同一个 library ID，避免从群组库搜索后又错误地到 My Library 导出。

Windows、macOS 与 Linux

三种桌面系统使用相同的 127.0.0.1 HTTP 边界和设置键：

  • Windows：确认 Zotero 桌面进程正在同一个登录会话运行；安全软件不应阻止本机回环连接。无需开放公网防火墙端口。
  • macOS：首次运行或升级 Zotero/BBT 后，确认 Zotero 已完全启动；系统网络权限不应被解释为允许外网访问，TeXLeaf 仍只请求回环地址。
  • Linux：本机 VS Code 与本机 Zotero 最直接；Flatpak/Snap 等沙箱版 Zotero 或 VS Code 可能隔离回环/文件访问，需要检查对应沙箱权限。

TeXLeaf 不发现 LAN 中另一台电脑的 Zotero，不接受 192.168.x.x、域名或任意 URL，也不把 Zotero 凭据发送到网络。

WSL、Remote SSH、Dev Container 与 Codespaces

127.0.0.1 始终指 TeXLeaf 扩展宿主所在的机器/网络命名空间，不是抽象意义上的“用户电脑”。

TeXLeaf 的 extensionKind 优先 ui，因此在 VS Code Desktop 的 WSL、Remote SSH 或 Dev Container 窗口中，如果 TeXLeaf 安装并运行在本地 UI extension host，它有机会访问桌面 Zotero，同时通过 VS Code Workspace FS 编辑远程项目文件。但最终宿主位置仍由 VS Code 的安装状态和扩展宿主决策决定。

排查方法：

  • 确认 TeXLeaf 安装在 Local 一侧，而不只是 SSH/WSL/Container 一侧；
  • 查看 Output → TeXLeaf 的连接错误；
  • 若扩展实际运行在远程 host，127.0.0.1:23119 指远程机器或容器，本机 Zotero 不可达；
  • 不要把 zoteroPort 当作端口转发地址，它只能改变端口数字，不能改变固定主机；
  • GitHub Codespaces/浏览器版 VS Code 中不能假设能访问桌面 Zotero，本功能应视为不可用，先在本地导出 bibliography 或使用桌面 Remote 窗口并确认宿主位置。

不要为了绕过这一边界把 Zotero API 暴露到公网。TeXLeaf 有意不支持可配置远程主机。

与 LaTeX Workshop 及其他补全共存

VS Code 会把当前上下文中所有 Completion Provider 的返回结果合并到一个 Suggest 中。TeXLeaf 只能决定自己返回什么，不能选择性删除、改写或隐藏 LaTeX Workshop 等第三方扩展的候选。

TeXLeaf 0.8.11 为 [latex] 和 [tex] 提供：

"editor.wordBasedSuggestions": "off"

这会默认隐藏 VS Code 自己从文档单词收集的 Text/word 候选，用户显式设置仍可覆盖。但 LaTeX Workshop 有独立 citation provider；其默认配置可能继续用 citation key 作为标签，这些不是 word-based suggestions，TeXLeaf 无法删除。

如果只是不希望 LaTeX Workshop 的行显示 key，可以在用户或工作区设置中让它显示标题：

{
  "latex-workshop.intellisense.citation.label": "title"
}

此设置由 LaTeX Workshop 定义，版本升级后以它的文档为准；结果可能是 TeXLeaf 标题条目和 LaTeX Workshop 标题条目同时出现。

不建议把 editor.suggest.showReferences 设为 false：LaTeX Workshop citation 和 TeXLeaf citation 都属于 CompletionItemKind.Reference，这样会同时隐藏 TeXLeaf 文献，并可能连 \ref{...} 补全一起关闭。LaTeX Workshop 的 citation.type=browser 会改弹它自己的 Quick Pick，也不等于禁用 citation provider。

若必须只保留 TeXLeaf，当前可靠办法是通过 VS Code 的扩展启用范围停用提供冲突候选的第三方扩展；代价是同时失去该扩展的编译/预览/语言服务功能。通常建议保留共存，只调整第三方 label。

缓存与刷新

Zotero 文献列表默认在内存缓存 30 秒。以下操作会刷新或失效：

  • 运行 TeXLeaf: 刷新 Zotero 参考文献缓存；
  • Zotero 相关设置改变；
  • 缓存过期后再次进入 citation。

自动加载失败有短暂冷却，避免每次按键都轰炸本机端口；手动刷新会立即重试并显示可读错误。Zotero 不可用时，bibliography 中已有条目仍应可搜索和插入。

工作区信任与安全

未信任工作区中：

  • 不访问 Zotero/Better BibTeX 端口；
  • 不自动弹出 Zotero citation picker；
  • 不创建或修改 bibliography；
  • 手动命令显示明确受限提示。

TeXLeaf 只发往回环地址，bibliography 只允许工作区内相对 .bib 路径，写入前重新验证文档和 key。即使项目设置试图写入任意主机 URL或 .. 路径，也不会采用。

常见问题速查

症状 首要检查
\cite{} 没有 TeXLeaf 条目 文件是否已保存为 .tex、工作区是否信任、两个总开关、citation command 列表
只有 .bib 现有条目，没有 Zotero Zotero 是否运行、本机通信、端口、library、输出日志
仍出现纯 key 行 判断是 VS Code word 候选还是 LaTeX Workshop provider；见上节
Zotero 文献已存在却显示“未导入” 检查 DOI/ISBN/标题/第一作者/年份是否完整，及 .bib 是否未保存
导入到错误文件 检查 bibliographyFile、当前文档所属 workspace root 和同名 .bib 层级
群组库无结果 使用准确名称或数字 library ID
一直超时 检查 extension host 位置、端口、沙箱/Remote 边界，不要开放公网
bibliography 未自动保存 如果导入前它已经 dirty，这是保护行为；手动审阅后保存

完整排查见 故障排查。

相关页面

TeXLeaf 0.8.11

开始

片段

AI 写作

文献

预览

贡献与发布

Clone this wiki locally