Skip to content

References and Zotero

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

文献与 Zotero

TeXLeaf 在 \cite{...} 及用户配置的其他 citation 命令中提供 VS Code 原生 Suggest。它先合并当前 bibliography 中已有的有效条目与 Zotero/Better BibTeX 中尚未加入该 bibliography 的条目，再对全库本地匹配和排序。相关度优先于来源；只有相关度相同时，已有 bibliography 条目才排在 Zotero 条目前。

接受已有条目只插入 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 1.0.0 的可搜索字段严格是：

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

查询会折叠大小写和常见重音，拆分成规范化词项并去重；多个不同词项按 AND 组合，但允许分别命中不同字段。例如标题词、作者姓氏和年份可以共同筛出一条记录。期刊/出版物（container）、摘要、标签和笔记不参与搜索，TeXLeaf 也不做拼写纠错；输入错误拼写不会被自动近似到另一个词。

结果按以下相关度层级排序：

  1. 原始 citation key（保留标点）的精确匹配；
  2. 去标点紧凑 key 的精确匹配或前缀匹配；
  3. DOI / ISBN 的精确匹配；
  4. 可搜索文本中的全词或词首匹配；
  5. 普通子串匹配。

因此 smith-2025 对原始 key 的精确命中，与去标点后 smith2025 的紧凑 key 命中属于不同等级。先比较相关度，只有相关度完全相同的结果才按 bibliography 优先于 Zotero 的来源规则打破平局；之后使用稳定的标题和 key 次序，避免列表无故跳动。

原生 Suggest 总共最多显示 100 条。这个上限不是 Zotero 读取上限：TeXLeaf 先对 bibliography 与 Zotero 的完整本地快照匹配和排序，再截取前 100 条。每次继续输入都针对完整快照重新计算，因此上一轮未进入前 100 条的文献仍可在查询缩窄后出现。

在一个 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 条目去重

候选和提交阶段都使用 fail-closed 身份规则：

  1. 精确 citation key 只有在现有与候选元数据没有明确冲突时才复用；
  2. 双方都提供有效 DOI 时，相同的规范化 DOI 是可跨 key 复用的强身份；不同的有效 DOI 则是明确冲突，即使标题、作者和年份看似相同也不判为同一文献；
  3. ISBN 不能单独证明文献相同。只有规范化标题一致，并且双方提供的年份与第一作者 family name 不矛盾时，ISBN 才作为辅助身份；共享同一本书 ISBN 的不同章节不会因此折叠；
  4. 没有标识符强证据时，只有规范化标题和年份一致、且第一作者有一致证据，才复用已有条目。

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

如果 Zotero 当前库中的多个记录拥有同一个 citation key，TeXLeaf 不会任选一条：该重复组的每个成员都会从补全中隐藏，Output → TeXLeaf 只记录重复组数而不输出文献内容。手动刷新后，旧 Suggest 中携带过期快照身份的候选也会在接受阶段被拒绝。

导入格式与原子编辑

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 秒，并作为当前 citation 会话的完整本地搜索快照。键入、删除或替换查询词时只重算这个快照，不会逐键请求 Zotero。以下操作会刷新或失效：

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

首次需要 Zotero 候选、缓存过期、相关设置改变或手动刷新时才请求本机 Zotero。自动加载失败有短暂冷却，避免重复轰炸本机端口；手动刷新会立即重试并显示可读错误。Zotero 不可用时，bibliography 中已有条目仍应可搜索和插入。

工作区信任与安全

未信任工作区中：

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

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

常见问题速查

症状 首要检查
\cite{} 没有 TeXLeaf 条目 文件是否已保存为 .tex、工作区是否信任、两个总开关、citation command 列表
只有 .bib 现有条目，没有 Zotero Zotero 是否运行、本机通信、端口、library、输出日志
搜索不到期刊、摘要、标签或笔记中的词 这些字段有意不参与搜索；请改用 key、标题、作者、年份、DOI 或 ISBN
拼错一个词后没有近似结果 1.0.0 不做拼写纠错；输入正确词、词首或子串
结果只有 100 条，或缩窄后出现新条目 Suggest 最多显示全库相关度排序后的 100 条；继续输入会从完整本地快照重新筛选
bibliography 条目没有总在 Zotero 前面 相关度优先；只有相关度相同才偏好 bibliography 来源
仍出现纯 key 行 判断是 VS Code word 候选还是 LaTeX Workshop provider；见上节
Zotero 文献已存在却显示“未导入” 检查 DOI 是否有效且一致；ISBN 还要求标题一致、已提供的第一作者 family name/年份不矛盾，并确认 .bib 未保存修改已被当前编辑器模型读取
某个 Zotero key 完全不显示 检查 Output → TeXLeaf 是否报告重复 citation key 组；同 key 的整组记录会全部隐藏，需先在 Zotero/Better BibTeX 中消除歧义
导入到错误文件 检查 bibliographyFile、当前文档所属 workspace root 和同名 .bib 层级
群组库无结果 使用准确名称或数字 library ID
一直超时 检查 extension host 位置、端口、沙箱/Remote 边界，不要开放公网
bibliography 未自动保存 如果导入前它已经 dirty，这是保护行为；手动审阅后保存

完整排查见 故障排查。

相关页面

TeXLeaf 1.0.0

开始

片段

AI 写作

文献

预览

贡献与发布

Clone this wiki locally