calibre 图书目录生成完全指南用 AZW3/EPUB/MOBI 格式打造你自己的电子书图书馆目录【免费下载链接】calibreThe official source code repository for the calibre ebook manager项目地址: https://gitcode.com/GitHub_Trending/ca/calibre本篇技术指南围绕 calibre 官方用户手册中的「Creating AZW3 • EPUB • MOBI catalogs」一章源码位于 manual/catalogs.rst展开系统讲解 calibre「Create catalog创建目录」功能的完整使用流程从选择待编目图书、配置包含章节、前缀规则、排除规则到排除流派、缩略图、注释合并等进阶选项并深入到命令行calibredb catalog与底层源码实现。读完本文你将能够为整座书库或任意图书子集生成一份结构清晰、可随身上设备阅读的 AZW3/EPUB/MOBI 格式目录并学会用前缀标记「已读」「心愿单」等状态、用排除规则过滤无关书籍、用正则裁剪流派分类。目录功能概述与适用场景calibre 的 Create catalog 功能可以把你的书库或其中一部分生成一份独立成书的目录文件支持多种输出格式。官方帮助文档明确指出该功能针对 AZW3、EPUB、MOBI 三种格式提供了专门的可视化配置界面见 manual/catalogs.rst此外项目还同时提供 CSV/XML、BibTeX 等目录插件可在 src/calibre/gui2/catalog/ 目录下看到catalog_csv_xml.py、catalog_bibtex.py、catalog_epub_mobi.py等实现。典型的应用场景包括为整座书库生成一份可按作者、书名、系列、流派浏览的「馆藏索引」为某个专题如最近 30 天新增图书生成子集目录在目录条目上以符号前缀标记「已读」「心愿单」「馆藏位置」等个性化状态配合排除规则把临时标签如Catalog或归档书籍从目录中剔除。从代码结构看目录功能由「GUI 对话框 → 插件式生成器 → 转换管线」三层构成GUI 配置入口在 src/calibre/gui2/dialogs/catalog.pyAZW3/EPUB/MOBI 专属选项面板在 src/calibre/gui2/catalog/catalog_epub_mobi.py真正执行生成的插件在 src/calibre/library/catalogs/epub_mobi.py。阅读本文后你可以顺着这三条路径深入钻研任何细节。选择要编目的图书编目全库如果希望整座书库都被编目只需在 calibre 主窗口清空任何搜索或过滤条件。此时即使只选中了一本书全库所有图书都会成为目录的候选对象。个别图书是否最终入册还会受到后续「排除规则」「排除流派」等条件的二次筛选。编目部分图书官方文档给出了两种只编目部分图书的方式见 manual/catalogs.rst多选图书在主窗口用 Ctrl/Shift 多选需要编目的图书当选中数大于 1 时仅这些书会被编目。搜索或标签过滤使用主窗口的搜索框或 Tag browser 过滤出想要的图书集合只有当前显示出来的书会被编目。这一逻辑在源码中也有印证在 src/calibre/gui2/actions/catalog.py 中generate_catalog()会先读取当前选中行若选中行少于 2 行则回退为把整个模型即当前过滤后的全部行作为候选 ID 列表——也就是说「单选一本书 全库无过滤」等价于编目全库。启动方式与对话框概览从菜单Convert books Create a catalog of the books in your calibre library即可打开目录生成对话框也可以到Preferences Interface Toolbars menus里把一个Create catalog按钮加到工具栏方便随时调用。对话框由 src/calibre/gui2/dialogs/catalog.py 中的Catalog(QDialog, Ui_Dialog)类构建它会枚举所有已安装且未禁用的 catalog 插件catalog_plugins()并按插件声明的file_types动态填充「Catalog format」下拉框——这也是为什么该对话框能同时容纳 CSV、XML、BibTeX、AZW3/EPUB/MOBI 等多种格式的原因。在Catalog options中Catalog format选择AZW3、EPUB 或 MOBI作为输出格式Catalog title填写目录标题该名称将用于生成的文件。若同名称、同格式的目录已存在生成时会自动覆盖旧目录。勾选Send catalog to device automatically后目录生成完成时会自动下载到已连接的设备上。从 src/calibre/gui2/dialogs/catalog.py 可以看到标题、格式、同步开关等偏好会被持久化到dynamic配置catalog_last_used_title、catalog_preferred_format、catalog_sync_to_device、catalog_add_to_library下次打开对话框时会自动恢复上次的设置其中默认格式偏好为 CSV、默认标题为「My books」。目录包含的章节Included sections勾选显示勾选标记的章节会被包含进生成的目录。官方文档定义了以下六个可选章节见 manual/catalogs.rst章节内容与排序规则Authors作者全部图书按作者排序以列表形式呈现非系列书排在系列书之前Titles书名全部图书按书名排序以列表形式呈现Series系列属于某个系列的图书按系列排序以列表形式呈现Genres流派逐个流派以列表呈现按作者和系列排序Recently Added最近添加全部图书按添加时间倒序排列先列出最近 30 天添加的图书再按月列出更早添加的图书Descriptions描述为每本书生成详细描述页包含封面缩略图与评论comments按作者排序非系列书排在系列书之前这些章节开关在源码中对应 src/calibre/gui2/catalog/catalog_epub_mobi.py 里注释列出的generate_titles、generate_series、generate_genres、generate_recently_added、generate_descriptions等复选框控件以及额外的cross_reference_authors开关——后者用于在 Authors 章节中为多作者图书创建交叉引用。生成器的行为有两个值得注意的细节见 src/calibre/library/catalogs/epub_mobi.py如果在 CLI 环境下没有指定任何章节开关生成器会自动启用全部六个章节并给出警告如果输出格式是MOBI 且只勾选了 Descriptions生成器会强制在前面追加一个Authors 章节——因为 MOBI 格式需要该章节来组织内容结构。前缀规则Prefixes前缀规则允许你在满足特定条件时为图书条目加上一个前缀符号。典型用途给已读图书打上勾✓、给心愿单图书打上叉×等。规则表单包含四列见 manual/catalogs.rst第一列复选框启用/禁用该规则Name规则名称由你自行命名Field字段来源可以是Tags或书库中的某个自定义列Value要匹配的字段内容Prefix规则命中时添加的前缀符号。当规则命中时该书条目就会被标记上所选的前缀。多条规则按顺序评估第一条命中的规则提供前缀被禁用或不完整的规则会被忽略。官方文档给出的示例配置见图Read book自定义列Last read中有任何日期的图书前缀为勾选符号 ✓Wishlist item带Wishlist标签的图书前缀为 ×Library books自定义列Available in Library值为 True或 Yes的图书前缀为双箭头符号。源码中的默认前缀规则与文档示例一致见 src/calibre/gui2/catalog/catalog_epub_mobi.py内置了Read book字段 Tags、模式、前缀✓和Wishlist item字段 Tags、模式Wishlist、前缀×两条默认规则。命令行侧的默认值则定义在 src/calibre/library/catalogs/epub_mobi.pydefault((Read books,tags,,✓),(Wishlist item,tags,Wishlist,×))前缀符号不是任意输入的PrefixRules类见 src/calibre/gui2/catalog/catalog_epub_mobi.py内置了一张包含 100 多种符号的下拉列表涵盖箭头←→↑↓、卡片花色♠♥♦♣、数学符号÷×±∞、货币符号$€£¥以及字母数字等方便你挑选不会与书名内容冲突的标记。关于 Field 的可选范围源码fetch_eligible_custom_fields()src/calibre/gui2/catalog/catalog_epub_mobi.py显示除了固定的 Tags 之外只有数据类型为bool、composite、datetime、enumeration、text的自定义列才可用于前缀/排除规则。Value 下拉框会根据 Field 的数据类型动态变化源码 L1185-L1208enumeration/text列出该列现有的全部取值boolTrue / False / unspecifiedcompositeany value / unspecifieddatetimeany date / unspecifiedTags列出书库中全部标签。其中any date、any value会被转换为正则.*unspecified被转换为None见 源码 L166-L172。排除规则Excluded books排除规则用于指定不会进入目录的图书。表单结构与前缀规则类似第一列复选框启用规则Name 为规则名Field 是 Tags 或自定义列Value 是要匹配的内容。所有规则都会对每本书进行评估被禁用或不完整的规则会被忽略。官方文档示例见 manual/catalogs.rstCatalogs带有Catalog标签的图书从目录中排除Archived Books自定义列Status值为Archived的图书从目录中排除。内置的默认排除规则是Catalogs字段 Tags、模式Catalog见 src/calibre/gui2/catalog/catalog_epub_mobi.py。命令行侧默认值见 src/calibre/library/catalogs/epub_mobi.pydefault((Catalogs,Tags,Catalog),)规则数据的内部表示是元组(rule_name, field, pattern)GUI 表格通过GenericRulesTable及其子类ExclusionRules源码 L1222-L1322进行增删、上下移动、启用/禁用等管理最终由construct_tw_opts_object()源码 L150-L181过滤掉禁用与不完整的规则后打包成元组列表传给生成器。一个容易被忽略的细节是排除规则在 GUI 中默认对「Catalog」标签生效——这正是为了让已生成的目录本身calibre 会把目录作为图书加入书库并打上相应标签不会出现在下一份目录里。排除流派Excluded genres生成目录时书库中的标签Tags会被当作流派Genres使用。例如你使用Fiction、Nonfiction标签它们就会成为目录中的流派分类图书会出现在它拥有对应标签的每一个流派分类下见 manual/catalogs.rst。问题在于你可能会把某些标签用于其他用途——比如用标记已读书或用[Amazon Freebie]这类带方括号的标签标记图书来源。这些标签显然不该作为流派出现。Excluded genres 正则就是用来指定「不作为流派」的标签的。默认排除正则模式为\[.\]|^\$既排除所有形如[tag]的方括号标签也排除默认的已读书标签注意手册原文写作\[.\]\而当前仓库源码中 GUI 默认值与命令行默认值均为r\[.\]|^\$见 src/calibre/gui2/catalog/catalog_epub_mobi.py 与 src/calibre/library/catalogs/epub_mobi.py本文以仓库源码为准。也可以直接用正则写出精确标签例如[Amazon Freebie]或[Project Gutenberg]要排除多个精确标签用管道符|连接[Amazon Freebie]|[Project Gutenberg]如果将正则留空GUI 会把它转换为a^一个永不匹配的正则等价于「不排除任何流派」见 源码 L544-L546 与 src/calibre/library/catalogs/epub_mobi.py。Results of regex区域会实时显示基于当前书库的标签与所输入的正则最终会有哪些标签被排除。该预览由exclude_genre_changed()源码 L183-L255驱动它把正则应用到书库全部标签上若流派来源选的是自定义列则应用到该列的全部取值并实时刷新结果文本若正则非法会提示regex error若所有流派都被排除会提示All genres will be excluded。另外Genres 章节的流派来源并不仅限于 Tags在「Genres」相关的下拉框中你可以把流派来源切换为某个text 或 enumeration 类型的自定义列见 源码 L613-L623此时排除预览会自动基于该列取值计算。其他选项Other optionsCatalog cover目录封面该选项决定生成新封面还是沿用已有封面。你可以为目录定制专属封面详见下文「自定义目录封面」一节如果已有想复用的封面选择Use existing cover否则选择Generate new cover。从源码看src/calibre/library/catalogs/epub_mobi.py生成器会先按title:目录标题 author:calibre在书库中搜索已有目录若能找到且use_existing_cover为真则复用其封面文件否则调用calibre_cover2(opts.catalog_title, calibre)生成一张新封面书名 calibre 字样并通过Plumber的cover推荐项写入最终文件。Extra Description note描述页附加说明该选项指定一个自定义列其内容会被插入到 Descriptions描述页面中、封面缩略图旁边。例如你可以在自定义列Last Read中记录上次阅读日期然后让它在描述页显示出来。源码中该字段为header_note_source_field见 src/calibre/library/catalogs/epub_mobi.py 的--header-note-source-field选项GUI 中允许选择的数据类型为 bool、composite、datetime、enumeration、text见 src/calibre/gui2/catalog/catalog_epub_mobi.py。Thumb width缩略图宽度该选项为 Descriptions 页面中的封面缩略图指定宽度偏好单位为英寸。缩略图会被缓存以提升性能第一次用某个新宽度生成目录时会比较慢但之后的目录构建会直接利用缩略图缓存速度明显加快。因此官方建议先用少量图书试生成、确定偏好的宽度再生成完整目录见 manual/catalogs.rst。源码中的约束与实现src/calibre/library/catalogs/epub_mobi.py、L375-L386类常量定义了下限THUMB_SMALLEST 1.0与上限THUMB_LARGEST 3.0命令行帮助文本标注的典型推荐范围为 1.0–2.0 英寸传入值若超出上下限会被钳制coerce到合法区间并给出警告日志GUI 中的默认值为 1.0见 catalog_epub_mobi.py L99。Merge with comments与评论合并该选项指定一个自定义列其内容会在目录生成时以非破坏方式合并进 comments评论元数据。例如你有一个自定义列Author bio希望把它附加到评论后面。你可以选择将自定义列内容插入到评论部分的之前或之后并可选地在两者之间插入一条水平分隔线horizontal rule。可用的自定义列类型为text、comments和composite见 src/calibre/gui2/catalog/catalog_epub_mobi.py。在底层GUI 会把选择打包为形如#自定义列:[before|after]:[True|False]的规则字符串merge_comments_rule见 源码 L538命令行侧对应的选项是--merge-comments-rule默认值为::即不合并说明见 src/calibre/library/catalogs/epub_mobi.py。自定义目录封面Custom catalog covers如需为目录制作专属封面可在安装了Generate Cover 插件后使用。插件安装入口为Preferences Advanced Plugins Get new plugins。安装后回到目录对话框在 Catalog cover 中选择Use existing cover即可复用你制作好的封面。另外GUI 还内置了「预设Preset」机制在 E-book options 选项卡中可以把当前整套选项章节开关、规则表、封面、缩略图宽度、标题、格式等保存为命名预设JSONConfig(catalog_presets)见 src/calibre/gui2/catalog/catalog_epub_mobi.py 与preset_save()之后无论是 GUI 还是命令行都能一键复用同一套配置——命令行通过--preset指定预设名详见下一节。命令行生成目录calibredb catalog除了 GUIcalibre 还提供完整的命令行入口calibredb catalog非常适合脚本化、批量化的场景。其实现位于 src/calibre/db/cli/cmd_catalog.py。基本用法calibredb catalog /path/to/destination.epub [options]输出格式由目标文件扩展名决定.csv、.epub、.mobi、.xml等若扩展名不被任何已安装的 catalog 插件支持会自动回退为 EPUB。注意输出文件名必须写在任何选项之前且不同格式支持的选项集合不同——想要查看某格式的全部选项只需指定输出文件后加--help。所有格式共用的通用选项见 cmd_catalog.py L47-L73选项说明-i, --ids逗号分隔的数据库 ID 列表只编目这些书若指定则--search被忽略默认编目全部-s, --search用搜索查询过滤结果默认不过滤-v, --verbose输出详细过程信息便于调试AZW3/EPUB/MOBI 格式的专属选项由插件动态注册plugin.cli_options见 cmd_catalog.py L22-L31完整清单及默认值定义在 src/calibre/library/catalogs/epub_mobi.py选项默认值说明--catalog-titleMy Books目录标题写入元数据--generate-authors关闭包含 Authors 章节--generate-titles关闭包含 Titles 章节--generate-series关闭包含 Series 章节--generate-genres关闭包含 Genres 章节--generate-recently-added关闭包含 Recently Added 章节--generate-descriptions关闭包含 Descriptions 章节--cross-reference-authors关闭为多作者图书在 Authors 章节创建交叉引用--exclude-genre\[.\]|^\$指定不作为流派的标签正则--exclusion-rules((Catalogs,Tags,Catalog),)排除规则模型为(规则名,Tags,逗号分隔标签列表)或(规则名,自定义列,模式)--prefix-rules((Read books,tags,,✓),(Wishlist item,tags,Wishlist,×))前缀规则模型为(规则名,来源字段,模式,前缀)--genre-source-fieldTagsGenres 章节的流派来源字段--header-note-source-field空插入到描述页头的说明文字所来自的自定义列--merge-comments-rule::格式#自定义列:[before|after]:[True|False]把自定义列内容合并进评论--output-profile无输出设备配置如kindle/kindle_dx会生成带 Sections/Articles 的层级目录--thumb-width1.0封面缩略图宽度英寸帮助文本标注范围 1.0–2.0--use-existing-cover关闭复用已有目录封面而非生成新封面--preset无使用 GUI 保存的命名预设一次指定全部设置--debug-pipeline无保存转换管线各阶段的输出到指定文件夹用于定位 bug使用示例——生成只含作者、书名、流派章节、排除[Project Gutenberg]标签、并为已读书加 ✓ 的目录calibredb catalog ~/catalogs/my_library.epub \ --generate-authors --generate-titles --generate-genres \ --exclude-genre \[.\]|^\$ \ --prefix-rules ((Read,tags,,✓),)如果使用预设则一行即可复用 GUI 中保存的整套配置calibredb catalog ~/catalogs/weekly.epub --preset Weekly digest命令行解析细节--prefix-rules与--exclusion-rules若以字符串形式传入会先用ast.literal_eval解析为元组结构并对每条规则的参数个数做校验前缀规则必须为 4 个参数、排除规则必须为 3 个参数非法输入会报错并中止见 epub_mobi.py L388-L412。目录生成的底层流程从 GUI 点击到成品文件理解底层调用链有助于你判断在哪个环节排查问题。一次完整的 GUI 目录生成流程如下入口工具栏/菜单触发GenerateCatalogActionsrc/calibre/gui2/actions/catalog.py收集选中或过滤后全部图书的数据库 ID调用gui2.tools.generate_catalog()对话框generate_catalog()打开Catalog对话框src/calibre/gui2/dialogs/catalog.py用户在「Catalog options」选择格式/标题/同步「E-book options」选项卡PluginWidget见 src/calibre/gui2/catalog/catalog_epub_mobi.py配置章节、规则等options()收集并持久化到gprefsgui.json任务调度确认后生成动作作为一个后台 Job 提交给job_manager执行状态栏显示Generating 格式 catalog...完成后若勾选了「Add to library」会把目录本身作为图书加入书库add_catalog()再按需同步到设备catalog.py L63-L87生成器真正的构建工作由EPUB_MOBI插件完成src/calibre/library/catalogs/epub_mobi.py它先根据--output-profile与已连接设备信息确定优化目标检测到 Kindle 设备时自动选用kindle/kindle_dx输出配置并据此裁剪描述与作者文本长度见 L268-L286处理--preset预设合并、解析规则字符串、钳制thumb_width然后交给CatalogBuildersrc/calibre/library/catalogs/epub_mobi_builder.py生成目录源文件OPF XHTML 源转换管线最后通过Plumbercalibre.ebooks.conversion.plumber把源文件按ebook-convert管线转换成最终的目标格式文件epub_mobi.py L521-L532封面、输出配置、调试参数等均通过recommendations注入转换器。此外生成器会硬编码sort_descriptions_by_author True——即描述页始终按作者排序、系列书排在非系列书之后epub_mobi.py L291-L292这与文档中 Descriptions 章节的排序说明完全一致。常见问题与调试建议未选择任何章节CLI 环境下会自动启用全部章节并打印警告GUI 环境下会中止生成并提示「No enabled Sections」检查 E-book options 选项卡里的 Included sections 勾选状态。目录反复出现在新目录里默认排除规则已对Catalog标签生效如果你给目录自定义了其他标签请记得在 Excluded books 中添加对应排除规则。缩略图生成很慢这是首次以新宽度生成时的正常现象缩略图有缓存后续生成会明显加快。定位生成问题使用-v/--verbose查看详细日志或用--debug-pipeline 文件夹保存转换管线各阶段的中间产物GUI 侧的对应说明见 src/calibre/gui2/dialogs/catalog.py 中help()的注释。Kindle 目录结构不理想为 Kindle 生成目录时建议显式使用--output-profile kindle或kindle_dx以获得带 Sections/Articles 的层级目录MOBI 输出还会自动追加内嵌 TOC 等优化推荐见 epub_mobi.py L485-L490。通过 GUI 的完整可视化配置、命令行calibredb catalog的脚本化能力以及「规则表 → 生成器 → 转换管线」这条清晰的源码实现链你现在已经可以按需定制并深入调试自己的 AZW3/EPUB/MOBI 书库目录了。想进一步了解模板定制或参与目录功能讨论可参考官方手册中提到的 MobileRead 论坛相关主题如需查阅本文对应的原始帮助文档可直接阅读 manual/catalogs.rst。【免费下载链接】calibreThe official source code repository for the calibre ebook manager项目地址: https://gitcode.com/GitHub_Trending/ca/calibre创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考