书屿读取 Calibre 数据库：理解 metadata.db 与书籍路径

Calibre 的 metadata.db 保存书库资料，但它不是一本包含全部电子书的文件。书屿可以通过 NAS 连接读取这种书库结构，再按需取得对应书籍。正确配置的关键，是让数据库与它引用的作者、书名和格式文件保持原有相对关系。

先确认你拿到的是完整书库

在 NAS 上找到 Calibre 书库根目录，里面通常有 metadata.db 和按作者、书籍组织的子目录。先确认这份目录来自你自己的 Calibre 书库，并且数据库与电子书文件属于同一次有效备份或当前一致状态。只复制一个数据库文件，不会把正文一起带走。

不要手工改动内部文件夹名字来追求整齐，也不要把所有 EPUB 从子目录拉到根目录后仍期待原路径有效。Calibre 的数据库会记录文件位置，外部随意重排容易破坏对应关系。第一次可使用已经备份好的小型书库副本验证，不要直接在唯一主库上试验文件移动。

在书屿「NAS 连接」中配置 WebDAV 或 SMB，确认能进入该 Calibre 根目录，并看见数据库和至少一本书的文件。此时只验证读取，不需要为了导入给账户开放不必要的写权限。相关 NAS 与 Calibre 功能需要藏书家 Pro，权限不足与会员状态应分开排查。

记下书库根目录相对于连接起点的路径。例如连接起点已经是 Books，Calibre 库在其下的 Calibre Library，就要按当前表单的路径规则填写，避免把 Books 重复一次。路径里有空格并不自动表示错误，关键是与远端实际目录一致。

进入「设置」→「Calibre 书库」，添加书库，选择 NAS metadata.db 对应来源类型。填写容易辨认的名称、书库路径，并选择刚才验证过的 NAS 连接。这里通常填写包含数据库的书库目录，而不是任意一本电子书路径；具体按界面提示的路径示例核对。

保存后执行同步，等待元数据读取完成。若提示关联 NAS 连接不存在，先恢复或重新选择有效连接；若提示路径无效，先在 NAS 浏览器中逐层检查。不要在没有确认路径的情况下反复改变数据库文件名，应用需要识别的是正确结构，而不是一个看起来更像“书库”的名字。

同步完成后浏览目录，找到一本你明确知道位置的书，核对作者、标题和格式。然后选择下载，等待导入完成并打开正文。如果目录能显示但文件取不到，优先检查数据库中的相对路径与 NAS 实际文件是否一致，而不是马上认为数据库解析失败。

例如数据库记录的是某作者目录下的一本 EPUB，但你曾在外部把作者文件夹改名，目录元数据仍可能显示正常，实际下载却找不到文件。应回到 Calibre 管理或完整备份流程修复结构，再重新同步。把缺失路径指向另一本同名书，会制造更隐蔽的内容错误。

当你在电脑 Calibre 中添加或移动书籍后，应按自己的同步或备份方式，把相关数据库与文件完整更新到 NAS，再让书屿刷新。不要只更新数据库却漏掉新书，也不要只复制书籍文件却没有相应元数据。两种不完整更新都可能造成“目录有书但打不开”或“文件在却目录里找不到”。

如果复制过程尚未结束，先不要急着刷新大书库。等目标目录稳定后再同步，选新增的一本做检查即可。阅读记录也应单独保护：重新建立库、删除旧记录和替换数据库不是轻量的刷新动作，处理前保留原文件与重要笔记，避免把多个操作混在一起。

完成本篇后，应能确认三件事：目录能列出正确书籍；指定书籍能下载并打开；离线时已下载内容仍可阅读。每一步证明的范围不同，不能用同步成功提示代替后两步。远端有一千本书，并不要求手机保存一千本文件，按需下载正适合设备空间有限的场景。

书库资料中的标签和作者有助于查找，但不能保证手机与 Calibre 的每个字段都双向保持完全相同。通过 NAS 数据库方式取得书籍后，Calibre 目录仍应在原来的管理工具中维护；阅读进度也有单独的同步入口。需要两台设备延续阅读时，应另行配置书屿提供的阅读数据同步。

只上传 metadata.db，为什么看到封面或书名却读不了？ 数据库主要描述书库，正文仍在关联文件中。把完整书库目录按原结构放到 NAS，再核对路径与权限，才具备实际下载条件。

可以把目录改成自己喜欢的分类树吗？ 不要直接在 Calibre 管理的内部结构里手工改名。分类可以使用 Calibre 元数据或书屿标签；若确实要重新组织文件，先用合适的管理流程并保留备份，再验证数据库引用。

这种方式比 Content Server 更好吗？ 它适合已有完整 NAS 书库的情形；Content Server 适合由运行中的 Calibre 服务提供目录和文件。选择取决于你已有的部署，不能仅以少填一个地址来判断哪种更稳。

需要服务器方式时，参考Calibre 内容服务器；还未配置网络共享，可先读SMB 私人书库或WebDAV 私人书库。

资料核对于 2026 年 10 月 23 日。公开版本为书屿 1.1.3，最低要求 iOS / iPadOS 15.6。本文按公开功能说明与相应功能入口整理，界面名称可能随版本调整。参考App Store 官方说明与Apple 版本信息。