jlegewie/zotfile · 上手攻略

是什么

Zotfile 是 Zotero 上的一款老牌附件管理插件，核心三件套：

  1. 自动重命名 + 移动 PDF——按 Zotero 条目的元数据（作者-年份-标题-期刊）把散落在 Downloads/、Desktop/ 的 PDF 重命名并放到统一目录；
  2. 平板/手机 PDF 阅读器同步——把 Zotero 库里的 PDF 推送到 iPad、Android 平板的 PDF 阅读器（GoodReader / PDF Expert / 各种云盘），改完的批注再抽回 Zotero；
  3. PDF 批注抽取——把 PDF 高亮 / 下划线 / 笔记抽到 Zotero 条目的 Notes 字段，方便后续做文献综述。

⚠️ 维护状态（README 自陈）：「Zotfile is currently not actively developed and maintained! Updates are extremely rare and I will mostly not respond to issues and pull requests here on github.」写稿时上游仓库以"低频维护"状态挂着；社区存在 fork / 替代品（详见下文"同类对比"）。安装前建议先在 Zotero 论坛与 GitHub Issues 看最近一个 release 的时间戳。

解决什么问题

Zotero 默认把 PDF 直接存在 storage/ 目录，文件名是随机字符。在三类场景下极不方便：

  1. 多人协作 + 文件命名一致性：要交论文到协作组 / OSF / arXiv 备份目录时，storage/ABCDEF.pdf 这种文件名是灾难；
  2. 多设备阅读：在 iPad 上用 PDF Expert / GoodReader 看文献、做批注，再把批注带回到 Zotero；
  3. 综述阶段批量整理批注：写作时要快速把几十篇文献的高亮集中到一个文档或 Notion / Obsidian。

Zotfile 的解决方案是「在 Zotero 和文件系统之间加一层中间层」——让你定义 PDF 的存放路径与命名规则，把批注作为结构化文本抽出来。

快速安装

⚠️ 写稿时仍以「下载 .xpi → Zotero 内安装」为标准路径；若 Zotero 7 之后改用 manifest v3 插件机制（Zotero 官方插件文档为准），请按官方流程调整。

方法 A：稳定版 .xpi（推荐）

  1. 打开 zotfile.com 或 GitHub Releases，下载最新 .xpi；
  2. Zotero 内 Tools → Add-ons（中文：工具 → 附加组件）；
  3. 右上角齿轮 → Install Add-on From File... → 选 .xpi；
  4. 重启 Zotero，看到 Zotero PDF Tools 或 Zotfile 菜单即成功。

方法 B：开发版（GitHub 源码）

git clone https://github.com/jlegewie/zotfile.git
cd zotfile
# Linux / macOS / Cygwin 有 Makefile，直接：
make
# 会产出当前目录的 .xpi（install.rdf 与 chrome/ 在顶层）

⚠️ Makefile 路径里的 install.rdf 与 chrome/ 必须处于 zip 根目录，不能嵌套 zotfile/ 子目录——README 强调过这一步是常见踩坑点。Windows 用户用 7-Zip / PowerShell Compress-Archive 自己压。

核心用法

1. 自定义 PDF 存储与命名

Zotero → Preferences → Zotfile：

  • Linked Files Base Directory：自定义存放目录，例如 ~/Zotero/storage-pretty/，或 NAS 路径；
  • Rename Rule：默认 {year} {author} - {title}，可拼期刊 {publication}、shorttitle、citekey 等；
  • Subfolder Rule：可按作者首字母 / 期刊 / collection 分子目录。

触发重命名：

选中条目 → 右键 → Manage Attachments → Rename and Move Attachments
# 或：右键 → Send to Tablet（见用法 2）

批量操作：

Tools → Zotfile Preferences → Advanced → 
  ☑ Watch for newly added files / 自动重命名新 PDF

2. 平板/手机同步

预设好平板的 PDF 阅读器路径（iCloud / Dropbox / WebDAV 都行），在 Zotero 选条目：

右键 → Send to Tablet

插件把 PDF 推到目标设备对应位置；之后阅读器改的批注回到同步目录后，Zotero 内：

右键 → Get Annotations from Tablet  （即「抽回批注」）

Zotfile 把 PDF 中的高亮 / 下划线 / 文本笔记批量写入对应 Zotero 条目的 Notes 字段，可直接复制到写作工具。

3. 抽取 PDF 批注到 Zotero Notes

Tools → Zotfile Preferences → General → 
  ☑ Extract Annotations
# 默认快捷键：选中条目 → 右键 → Extract Annotations

⚠️ PDF 必须是文本型（非扫描件）；扫描件要先 OCR。Zotfile 基于 pdf.js，受其 PDF 标准支持范围限制，少数 PDF（特殊字体 / 加密 / 损坏 ToUnicode 表）抽不出高亮。

典型适用场景

  1. 博士生 / 研究员的本地文献库整理：把 Zotero 库与本地文件系统解耦，PDF 用可读命名 + 统一目录；
  2. 跨设备阅读与批注回收：iPad 标注 → Zotero 同步 → 写作时一键导出；
  3. 综述写作：批量抽高亮到 Markdown / Notion / Obsidian，再人工串成 outline；
  4. 协作组共享 PDF：用稳定命名规则让 PDF 目录能脱离 Zotero 单独被他人索引；
  5. 机构知识库（IR）归档：把 PDF 用标准命名规则导出后批量上传到 IR / OSF / Zenodo。

坑与注意

⚠️ 维护状态：上游 README 自陈「not actively developed」。在新版 Zotero（Zotero 7 之后）下使用前请到 GitHub Issues / zotero.org 论坛搜「zotfile not working zotero 7 / zotero 8」，确认最近 release 与你 Zotero 版本的兼容性；如果不兼容，社区有 fork（详见下文）。

⚠️ 插件与 Zotero 版本的耦合：Zotfile 是「legacy XUL/overlay」插件的典型代表；从 Zotero 5 → 7 期间部分 API 调整曾导致批量抽批注失效。新装机器先跑一次 Extract Annotations + Rename and Move Attachments 小批量验证，再批量。

⚠️ PDF 命名规则的"覆写陷阱"：把默认 {year} {author} - {title} 中 author 用全名会导致重名作者冲突；建议 {auth last name et al.} 或 {auth short}。Title 里有非法字符（:、/、?）时，部分文件系统会拒写，提前在 rename rule 里替换。

⚠️ 存储路径与云盘：不要把 Linked Base Directory 放在同步盘的「活跃同步目录」里（Dropbox 同步中的文件被改名 / 移动会触发上传风暴）；要么关闭实时同步、要么走「Send to Tablet」单独目录。

⚠️ 批注抽取失败：扫面件 PDF / 加密 PDF / 损坏字体表的 PDF 是高发场景；先在 PDF 阅读器里试「复制粘贴」能否拿到文本，拿不到就别指望 Zotfile。

⚠️ Notes 字段膨胀：所有抽出的高亮都进 Zotero Notes，一个条目 200 条高亮会让 Zotero 数据库显著变大；建议抽完后导出到外部 Markdown / Notion，Zotero Notes 留可索引的「链接 + 关键句」即可。

⚠️ macOS 权限：Zotfile 在 macOS 上访问 ~/Documents 外目录（如 NAS / iCloud Drive）需要在「系统设置 → 隐私与安全性 → 文件与文件夹」里给 Zotero 授权，否则静默失败。

⚠️ Citekey 与 Zotfile 共存：若同时装 Better BibTeX，rename rule 里建议加 {citekey} 段（{citekey} - {year} {author} - {title}），文件名同时兼容 BibTeX 引用键，方便后续脚本化处理。

与同类对比

工具 定位 优点 短板
jlegewie/zotfile（本项目） 附件重命名 + 平板同步 + 批注抽取 三件套整合；配置项细；老牌稳定 上游维护停滞；与新 Zotero 版本兼容性需要确认
retorquere/zotero-better-bibtex 引用键（citekey）自动生成 + 导出 Zotero 同步导出体验最丝滑；生态广 不做 PDF 重命名 / 批注抽取
windingwind/zotero-better-notes Zotero 内 Markdown 笔记 + 模板 笔记结构化强、可自定义模板 PDF 高亮抽取靠其它插件
windingwind/zotero-actions-tags 批量规则引擎 配合 Zotfile 做「抽完批注自动打标签」 自己写规则
argenos/zotero-mdnotes 把 Zotero 条目导出为 Markdown + frontmatter 写作 pipeline 友好 不替代 Zotfile 的批注抽取
bwiernik/zotero-shortdoi / northword/zotero-format-metadata 元数据辅助 补 Zotfile 不涉及的元数据缺口 与本插件正交
l0o0/jasminum（中文） Zotero 中文文献元数据补全 国内场景必要 与 Zotfile 功能不重叠

简单说：Zotfile = 文件系统侧的"中间层"，主要解决 PDF 在文件系统里的可读命名 + 跨设备批注回收；不解决元数据、不解决 citekey、不解决 Markdown 笔记——那些交给 Better BibTeX / Better Notes / mdnotes。

一句话推荐结论

需要「PDF 文件名可读 + 跨设备批注回收」就直接装；如果是 Zotero 7+ 新环境、且 Zotfile 兼容性有问题，先看社区 fork（zotfile-zotera / others）再决定是否换 Better Notes + mdnotes 的组合。