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

• 仓库：obsidian-community/obsidian-zotero-integration
• 链接：https://github.com/community-archive/obsidian-zotero-integration
• 分类：academic-writing · knowledge-management
• 作者：Tom
• 更新：2026-08-14

这是什么

obsidian-zotero-integration（简称 Zotero Integration）是 Obsidian 的社区插件，实现 Zotero 文献库与 Obsidian 笔记之间的双向打通：插入引用 / 参考文献列表 / PDF 高亮标注 / 笔记注解。项目最初由 mgmeyers 开发（主库），后因作者长期不活跃，由 obsidian-community 组织接管维护（即本仓库）。

核心功能：

• 在 Obsidian 内直接导入单条 Zotero 条目的格式化引用
• 自动生成文末参考文献（Bibliography）
• 将 PDF 高亮标注（颜色、页码、批注）导入为 Markdown 笔记
• 支持 Nunjucks 模板自定义导入格式
• 支持 epub 和 snapshot（网页快照）标注导入（v3.x+）

解决什么问题

做学术研究的人通常在 Zotero 管理文献、用 Obsidian 写笔记，两者之前靠手动复制粘贴或第三方脚本桥接，标注颜色和页码信息容易丢失。

该插件让导入过程完全自动化，且通过模板系统保留 Zotero 中的完整元数据（作者、年份、期刊、DOI、标注颜色、页码等），实现"文献阅读 → 标注 → 笔记"的闭环。

快速安装

前置要求

1. Obsidian ≥ v0.13.24
2. Zotero + Better BibTeX for Zotero 插件（必装，Zotero 端负责生成 citation key 和 Quick Copy 输出格式）

Better BibTeX 安装：在 Zotero → 工具 → 附加组件 → 搜索 "Better BibTeX" 安装，或访问 https://retorque.re/zotero-better-bibtex/installation/

3. Zotero 端设置 Quick Copy 输出格式（Plugin Settings 说明页面有截图指引）

安装插件

1. 打开 Obsidian → 设置（Settings）
2. 左侧菜单 → 社区插件（Community Plugins）
3. 点击浏览（Browse），搜索 Zotero Integration
4. 安装并启用

核心用法

基础导入单条文献

1. 在 Zotero 中选中一条文献
2. Obsidian 中打开命令面板（Ctrl/Cmd + P）
3. 输入 Zotero Integration: Insert literature note（或 Insert citation）
4. 插件按预设模板在当前光标处插入格式化引用

生成参考文献列表

1. 在 Obsidian 中放置光标到要插入参考文献的位置
2. 命令面板输入 Insert bibliography
3. 插件自动在该位置生成当前文件所有引用的参考文献

导入 PDF 标注（核心功能）

需要先配置模板（见下节）。

1. 在 Zotero 中打开带 PDF 的文献，选中若干高亮文本并添加批注
2. Obsidian 命令面板执行 Insert notes into current document
3. 插件读取 Zotero 中该条目的所有标注，按模板格式写入当前笔记

Nunjucks 模板配置

插件使用 Nunjucks 模板语言，数据由 Zotero 传入。

基本模板示例（含文献信息和摘要）：

## {{title}}

### 格式化引用

{{bibliography}}

{% if abstractNote %}

### 摘要

{{abstractNote}}
{% endif %}

标注模板示例（含颜色和页码）：

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

> {{annotation.annotatedText}}
> {% if annotation.comment %}评注：{{annotation.comment}}{% endif %}
> （第 {{annotation.page}} 页{% if annotation.color %} · {{annotation.colorCategory}}{% endif %}）
{% endif %}
{% endfor %}

使用 persist 标签保留增量内容（每次导入只追加新标注，不覆盖旧内容）：

{% persist "annotations" %}
{% set newAnnotations = annotations | filterby("date", "dateafter", lastImportDate) %}
{% if newAnnotations.length > 0 %}

### 新增标注：{{importDate | format("YYYY-MM-DD h:mm a")}}

{% for a in newAnnotations %}
> {{a.annotatedText}}
{% endfor %}
{% endif %}
{% endpersist %}

查看可用模板变量

Obsidian 命令面板 → Zotero Integration: Open data explorer，可查看当前条目所有可用字段（tags、annotations、creators、abstractNote 等），据此编写自定义模板。

典型适用场景

• 学术写作：在 Obsidian 写论文时直接引用 Zotero 文献，参考文献自动生成
• 文献精读：PDF 阅读批注自动同步到 Obsidian，保留颜色分类（问题 / 重要 / 待验证等）
• 卡片盒笔记法（Zettelkasten）：每篇文献对应一个笔记，通过双向链接关联已有笔记网络
• 文献综述：通过模板将多篇文献的摘要和高亮组织进同一 Obsidian 文档
• 硕博论文：长文档中多处引用同一文献，通过 Better BibTeX citation key 保持一致性

坑与注意

必须安装 Better BibTeX

没有 Better BibTeX，插件无法获取 citation key，无法工作。这是 硬性依赖，无法绕过。

Zotero 端 Quick Copy 格式必须配置

插件依赖 Zotero 的 Quick Copy 功能输出 citation。需在 Zotero → 设置 → 高级 → 快捷复制（Quick Copy）选择一个Bibliography Style（建议 Better BibTeX 格式）。未配置会导致导入为空。

导入后标注颜色丢失

用"Insert notes into current document"模式导入会丢失颜色和图片标注。正确做法是通过模板直接从 Zotero 读取原始标注数据（annotation.color / annotation.colorCategory 字段），不要先在 Zotero 侧做预处理。

PDF 标注在 Zotero 能看见但 Obsidian 不显示

可能是 BibTeX 或插件的数据解析 bug，参考 #107。可用 Data Explorer 确认 Zotero 返回的原始数据是否包含 annotations 字段。

模板变量名大小写敏感

Nunjucks 模板中访问字段用 annotation.annotatedText（驼峰），不是 annotation.annotated_text。写错大小写会导致字段读取为空。

文档尚不完整

插件官方文档（/docs/README.md）目前内容极少，FAQ、Templating、PDF Annotations 页面有内容但覆盖不全。遇到问题优先参考： - Obsidian 官方论坛模板讨论：https://forum.obsidian.md/t/zotero-desktop-connector-import-templates/36310 - 插件 GitHub Issues

与同类对比

推荐优先级：obsidian-zotero-integration（社区版） > 旧版 citation-plugin。Better BibTeX 是必要前提，配合该插件可覆盖绝大多数学术笔记工作流。

一句话推荐结论

做学术文献管理，Zotero + Better BibTeX + obsidian-zotero-integration 是目前最完整、模板最灵活的开源方案，熟练使用 Nunjucks 模板后可实现"读 Paper → 标注 → 笔记"全流程自动化。