community-archive/obsidian-zotero-integration · 上手攻略

  • 仓库：community-archive/obsidian-zotero-integration
  • 链接：https://github.com/community-archive/obsidian-zotero-integration
  • 分类：学术工具 · 文献管理 · Obsidian 插件
  • 作者：Tom
  • 更新：2026-08-12

是什么

community-archive/obsidian-zotero-integration 是 Obsidian 的官方社区插件，用于将 Zotero 中的文献条目、PDF 标注、笔记和参考文献目录直接导入 Obsidian 笔记库。它支持高亮、下划线、删除线、矩形批注等多种 PDF 标注类型的提取，并通过 Nunjucks 模板实现高度自定义的导入格式。

本仓库是原始维护仓库（mgmeyers/obsidian-zotero-integration）的社区归档镜像，核心功能与原仓库一致。

⚠️ 前提依赖：必须安装 Better BibTeX for Zotero 插件（Zotero 端），否则插件无法正常工作。

解决什么问题

写学术笔记最常见的痛苦是：PDF 在 Zotero 里、笔记在 Obsidian 里，两者割裂。每次要引用文献要么手动复制粘贴，要么依赖不稳定的双向链接插件。

obsidian-zotero-integration 让这个流程自动化：选中 Zotero 条目 → 一键提取 PDF 标注和文献信息 → 按自定义模板生成 Markdown 笔记 → 直接存入 Obsidian 保险库。引用、标注、文献信息全部结构化，后续可直接链接、检索、引用。

快速安装

步骤 1：安装 Better BibTeX for Zotero（必须）

在 Zotero 中：工具 → 附加组件 → 搜索 "Better BibTeX" → 安装并重启 Zotero。

步骤 2：在 Obsidian 中安装插件

  1. 打开 Obsidian → 设置 → 社区插件
  2. 确保「社区插件」开关打开
  3. 点击「浏览」→ 搜索「Zotero Integration」→ 安装
  4. 启用插件

⚠️ 版本要求：Obsidian 版本至少 v0.13.24。若版本过低需先重装 Obsidian。

步骤 3：配置 Quick Copy 样式

在 Zotero 中： 1. 编辑 → 首选项 → Better BibTeX → Quick Copy 2. 选择一种 citation style（任选一种即可，插件只要求此处有值）

步骤 4：验证 Quick Copy 可用

在 Zotero 中选中任意条目，确认可以复制 citation（这是插件触发数据交换的方式）。

核心用法

基本导入流程

  1. 在 Obsidian 中打开命令面板（Ctrl/Cmd + P）→ 搜索「Zotero」相关命令
  2. 选中要导入的 Zotero 条目（支持多选）
  3. 运行导入命令，插件按预设模板生成 Markdown 文件
  4. 文件保存到 vault 中，包含文献信息 + PDF 标注内容

PDF 标注类型支持

插件通过外部工具 pdf-annots2json 提取 PDF 标注，支持：⚠️ 标注提取工具非 100% 完美，但对主流平台（Windows x64 / Linux x64 / Mac Intel & Apple Silicon）支持良好。遇到问题可提 issue。

  • 高亮（Highlights）
  • 下划线（Underlines）
  • 删除线（Strikethroughs）
  • 笔记（Notes）
  • 矩形批注（Rectangles） → 转换为图片保存

Nunjucks 模板系统

插件使用 Nunjucks 模板语言，模板文件可存放在 vault 任意位置，在插件导入设置中指定路径即可。

可用变量示例：

变量 说明
{{title}} 文献标题
{{bibliography}} 格式化参考文献
{{abstractNote}} 摘要
{{annotation.annotatedText}} 标注原文
{{annotation.comment}} 标注旁的读者笔记
{{annotation.color}} 标注颜色
{{annotation.page}} 所在页码
{{tags}} 标签列表
{{importDate}} 导入日期

基础文献模板示例：

## {{title}}

### Formatted Bibliography

{{bibliography}}

{% if abstractNote %}

### Abstract

{{abstractNote}}
{% endif %}

基础标注模板示例：

{% for annotation in annotations %}
{% if annotation.annotatedText %}

> {{annotation.annotatedText}}
{% endif %}
{% if annotation.comment %}
> {{annotation.comment}}
{% endif %}
{% endfor %}

带标签列表的模板：

Tags: {% for t in tags %}{{t.tag}}{% if not loop.last %}, {% endif %}{% endfor %}

增量导入（增量更新）

每次从同一 Zotero 条目导入时，Markdown 文件会被覆盖。使用 {% persist "annotations" %} 块可以保护已有内容不被覆盖，实现增量追加：

{% persist "annotations" %}
{% if isFirstImport %}
- [ ] first thing
- [ ] second thing
{% endif %}
things to add each time you import
{% endpersist %}

{% if isFirstImport %} 块内内容仅在首次导入时写入；后续导入追加 things to add each time 部分。配合 newAnnotations 过滤器可实现「只导入上次以来的新增标注」：

{% persist "annotations" %}
{% set newAnnotations = annotations | filterby("date", "dateafter", lastImportDate) %}
{% if newAnnotations.length > 0 %}
### Imported: {{importDate | format("YYYY-MM-DD h:mm a")}}
{% for a in newAnnotations %}
> {{a.annotatedText}}
{% endfor %}
{% endif %}
{% endpersist %}

Data Explorer

不确定某个变量名是什么？在 Obsidian 命令面板中运行「Zotero Integration: Data Explorer」，插件会展示当前条目所有可用数据字段和结构，助你精准编写模板。

典型适用场景

  1. 学术论文阅读笔记：在 Zotero 读 PDF 时随手高亮、批注，导入 Obsidian 后自动生成带页码的引用标注，可直接用于写笔记和论文
  2. 文献综述写作：导入多个文献的摘要和标注，快速搭建文献笔记库，配合 Obsidian 的双向链接做知识图谱
  3. 课程阅读管理：每门课的 Reading 用 Zotero 管理，标注导入 Obsidian 作为课程笔记的一部分
  4. 每日/每周文献消化：用增量导入功能，每次打开笔记只看到新增的标注，避免重复内容堆积

坑与注意

  1. Better BibTeX 是必须前提：未安装或未启用 Better BibTeX，插件完全无法工作。务必先装 Zotero 端插件再装 Obsidian 插件。
  2. Obsidian 版本要求 v0.13.24+：低版本 Obsidian 无法安装此插件，需要先升级。
  3. Quick Copy 样式必须设置：Zotero 中 Better BibTeX 的 Quick Copy 若未配置，导入命令无法获取 citation 数据。
  4. PDF 标注提取非 100% 准确：pdf-annots2json 工具在某些 PDF 格式或特殊标注上可能出现提取错误，遇到问题时可向 GitHub 提 issue。
  5. 模板语法有学习曲线：Nunjucks 功能强大但语法需要适应，建议从简单模板开始，逐步加入 {% if %} / {% for %} / {% persist %} 等高级功能。
  6. 文件路径需提前规划：模板文件放在 vault 任意位置均可，但建议在 vault 根目录建立 templates/zotero/ 目录统一管理，便于同步和多设备共享。
  7. 注释颜色分类需插件支持：Zotero PDF reader 中用不同颜色高亮，默认会被记录颜色字段，可据此在模板中做分类筛选（如「红 = 重要 / 绿 = 方法 / 黄 = 待验证」）。
  8. 矩形批注转图片：PDF 中的矩形批注（截图类批注）会被转换为图片保存，需在插件设置中配置图片输出路径（Image Output Path）。

与同类对比

方案 优点 缺点
obsidian-zotero-integration（本插件） 官方维护、Nunjucks 模板灵活、增量导入、标注类型丰富 Better BibTeX 门槛、部分标注提取偶有误差
Zotero Better Notes Zotero 内置笔记功能 笔记在 Zotero 内，与 Obsidian 割裂
obsidian-citation-plugin 轻量、引文插入方便 主要做引文管理，无 PDF 标注导入
Mdnotes (Zotero 插件) Zotero 端直接导出 Markdown 模板灵活性弱，无增量导入
Zotero + 自己写脚本 完全可控 需要自己维护，版本更新易坏

核心差异：obsidian-zotero-integration 是目前 Obsidian 生态中 PDF 标注导入最完整的方案——标注类型覆盖全（Nunjucks 让格式完全自定义）、增量更新保护已有笔记、社区活跃持续维护。

一句话推荐结论

如果你同时用 Zotero 管理文献、用 Obsidian 写笔记，obsidian-zotero-integration 是把两者打通的最完整方案——Better BibTeX 是唯一必须的门槛，Nunjucks 模板让文献笔记格式完全受你控制，增量导入避免重复内容堆积。

⚠️ 注意：本仓库为 community-archive 镜像归档，核心功能以 mgmeyers/obsidian-zotero-integration 为准。原始仓库：https://github.com/mgmeyers/obsidian-zotero-integration