命名与元数据

首页 · 导入与整理 · 支持格式 · English

想让书名、作者和封面显示正确，可以规范文件与目录名称、补充旁挂 OPF，或在应用中编辑、联网识别。本页说明各方法实际会影响哪些信息，以及哪些文件会在扫描时读取。

• 整本、单卷和音轨的区别
• 定义标题和作者
• 目录布局示例
• 各格式的元数据支持
• 应用编辑、联网识别和 OPF 示例
• 来源优先级
• 生效步骤与文件写回
• 没有识别或更新时的排查

先分清整本、单卷和音轨

信息属于谁	用途	例子
整本图书／作品	书库中的入口，保存整本的标题、作者、简介、标签、系列和封面	“三体全集”，作者“刘慈欣”
可读资源	可以独立打开的一个文件、图片目录或音轨目录，保存自身的标题、卷号、简介、出版信息和封面等	“三体 第二卷”、某个 PDF、某一卷漫画
音轨	有声书中的一段音频，标题用于音轨列表	“001 开篇”，不是整本书名

“单本”组织方式会把每个识别出的可读资源独立成书；图片目录、多音轨目录可以各自形成一个资源。“分卷”方式以第一级文件夹作为整本作品，里面的资源归到它下面，根目录单独文件仍独立成书。目录结构决定归组，名称相似不会自动合并。

整本只有一个已启用资源时，可以继承该资源的本地候选信息；有多个资源时，不会任取某一卷的内嵌书名、作者或简介作为整本信息。多卷作品最好在作品目录放置 metadata.opf，或直接编辑整本图书。

怎样定义标题和作者

整本作品的名称示例

以下只展示名称来源能提供的信息。OPF 或内嵌信息优先、或者相关字段已被手动编辑时，最终显示可能不同。

文件名／作品目录名	名称提供的整本标题	名称提供的作者
三体.epub	三体	无
三体 - 刘慈欣.epub	三体	刘慈欣
[三体][刘慈欣].epub	三体	刘慈欣
三体 作者：刘慈欣.epub	三体	刘慈欣
三体 [作者：刘慈欣]（目录）	三体	刘慈欣
三体 第二卷 - 刘慈欣.epub	三体；可提供卷号 2	刘慈欣

推荐使用 书名 作者：作者名，也支持 作者:、Author:、Author： 这样的明确标记。Windows 文件名不能包含半角冒号，实际命名可使用示例中的全角 ：。上表文件示例会去掉已识别的格式扩展名；目录名不按文件扩展名处理。

只解析对象自己的名称，不根据上级文件夹猜作者。例如 刘慈欣/三体.epub 在“单本”模式下，不会仅凭父目录自动得到作者“刘慈欣”。使用“分卷”时，第一级 刘慈欣/ 会成为作品入口，因此也不适合用作者目录直接替代作品目录。

单卷标题与整本标题的区别

资源的名称回退会保留完整卷名，只有明确的作者标记才会从资源标题中提取作者部分。例如：

名称	整本名称解析	资源名称回退
三体 - 刘慈欣.epub	标题“三体”，作者“刘慈欣”	卷标题保留“三体 - 刘慈欣”；不会用这个分隔符为资源提取作者
三体 第二卷 作者：刘慈欣.epub	标题“三体”，作者“刘慈欣”，卷号 2	卷标题“三体 第二卷”，作者候选“刘慈欣”，卷号 2

资源读取到有效 OPF 或内嵌标题时，仍按本地来源顺序选择标题。“单本”模式使用出版物的原始标题作为图书标题，不会仅因内嵌系列信息就把所有卷显示为同一系列名。

副标题、版本和系列怎么写

名称中的分隔符、括号可能被当作标题与作者的分界，不应把版本说明放到作者位置。例如不要用 三体（修订版） 表达作者，也不要把 书名 - 副标题 - 作者 当作无歧义的格式。建议这样写：

[三体：修订版][刘慈欣].epub
书名-副标题 作者：张三.epub
[Spider-Man][Stan Lee].cbz

需要完全指定标题、多个作者或特殊标点时，用 OPF 或应用编辑更明确；多个作者在 OPF 中分别填写多个 dc:creator，不要依赖文件名中的逗号来定义多人结构。

字段	表达什么	示例
标题／卷标题	作品名或当前可读文件的名字	整本“三体全集”；资源“三体 第二卷”
系列名（丛书名）	作品所属的系列	地球往事
系列序号	当前作品在系列中的位置	2
卷号	当前资源的卷册编号，不是全套总卷数	2

名称中的 第二卷、Vol.02 等结尾可以提供卷号；001 这样的文件排序编号不等于一定写入系列序号。元数据也不会根据系列名自动移动文件或重新归组。

可直接参考的目录布局

下面每个代码块的 library/ 都是书库根目录。示例元数据名称用于演示，实际标题仍由后文的来源顺序决定。

单本电子书

library/
  三体 作者：刘慈欣.epub
  散文集 作者：张三.pdf
  游记 作者：李四.txt

选择“单本”：每个文件是一本书。根目录单独文件在“分卷”模式下也独立成书。

分卷作品及多种文件格式

library/
  三体全集 作者：刘慈欣/
    metadata.opf
    第一卷.epub
    第一卷.opf
    第二卷.epub
    第二卷.opf
  散文集 作者：张三/
    metadata.opf
    散文集.epub
    散文集.pdf

选择“分卷”：得到“三体全集”和“散文集”两个作品入口，分别进入后选择卷或文件格式。选择“单本”：每个 EPUB、PDF 都独立成书，同一目录不会把多种格式合并为一本。

三体全集/metadata.opf 可以说明整套信息；第一卷.opf、第二卷.opf 分别说明单卷。同名的 散文集.epub 和 散文集.pdf 会共同命中 散文集.opf（如果存在），不能把它当作只影响 EPUB 的文件。

漫画图片目录与漫画包

library/
  漫画甲 作者：张三/
    metadata.opf
    001.jpg
    002.jpg
    003.jpg
  漫画乙 作者：李四/
    metadata.opf
    01.cbz
    01.opf
    02.cbz
    02.opf

“漫画甲”的图片目录是一个可读资源。“漫画乙”用“分卷”模式作为一个作品、两个资源；用“单本”模式则两个 CBZ 独立成书。CBZ／ZIP 内也按 001.jpg、002.jpg 等安排图片，若使用 ComicInfo.xml，推荐放在包内根目录。其 XML 示例见下文。

单文件、多音轨和多碟有声书

library/
  故事甲 作者：张三.m4b
  故事甲 作者：张三.opf
  故事乙 作者：李四/
    metadata.opf
    001 开篇.mp3
    002 启程.mp3
  故事丙 作者：王五/
    metadata.opf
    CD1/
      001.mp3
      002.mp3
    CD2/
      001.mp3
      002.mp3

故事甲是单文件资源；故事乙的多段音轨属于同一目录资源。CD1、CD2 是可以纳入同一有声书的碟片分组；Disc1、Disk1、碟1、盘1 等也支持。普通名称的子目录会划分资源，不要把不同故事放进同一个音轨目录，再指望文件名自动拆书。

图片页码和音轨建议使用连续、等宽编号，便于在文件管理器和其他软件中查看；补零不是导入的强制要求。音频还可能提供碟号、音轨号标签，不要让标签与文件编号互相矛盾。

各格式在扫描时识别什么

“内嵌”指信息保存在读物文件内部；“旁挂／旁车”指放在读物旁边的独立元数据文件。下表描述扫描导入，具体字段必须确实存在且能够读取。

格式	扫描自动读取的内嵌信息	可补充的旁挂文件	主要字段与限制
EPUB	EPUB 包内的 OPF	OPF	标题、作者、简介、标签、语言、出版社、出版日期、标识符／ISBN、系列／序号、封面引用；包内 OPF 由 EPUB 的容器信息定位，不是在外面随便放一个同名 XML
FB2	文件内 description 的 title-info、publish-info、document-info 等	OPF	标题、作者、简介、genre 标签、语言、出版信息、标识符、系列／序号；不是从正文提取作者
MOBI／AZW／AZW3／PRC	文件内可读取的出版物元数据	OPF	可提供标题、作者、语言、出版信息、标识符／ISBN、简介、标签、封面等；实际字段随文件而异，不支持 DRM
TXT	编码及有限语言探测，不从正文提取标题、作者、简介	OPF	用名称、OPF 或应用编辑补充标题作者；正文开头写“作者：某某”不会自动变成作者字段
PDF	Info 字典及 XMP	OPF	标题、作者、简介、关键词；XMP 还可提供语言、出版社、出版日期、标识符／ISBN。不是通过 OCR 或扫描正文识别
CBZ／ZIP 漫画包	包内 ComicInfo.xml	OPF	Title、Writer（缺少时用 Penciller）、Summary、Series、Publisher、Tags（缺少时用 Genre）；Volume／Number 会被解析，但不代表所有解析值都会写入图书展示字段
CBR／RAR 漫画包	当前扫描不提取包内 ComicInfo.xml	OPF	页面可以导入，不代表包内元数据也会读取；书名作者建议由名称或 OPF 提供
图片漫画目录	目录名称；无可用元数据封面时可取阅读顺序第一张图片	目录 OPF	不会在扫描时自动读取目录旁的 ComicInfo.xml，也不把图片内的 EXIF／IPTC 当作图书信息
音频文件／多轨有声书	支持的音频标签、封面和章节	文件或目录 OPF	专辑、作者、朗读者、系列／卷号及音轨标题等；不同音频格式和标签版本的支持并不相同，缺少可读取标签时保留未知值

PDF 字段对应关系

PDF 信息	应用中的用途
Info /Title；XMP dc:title	标题
Info /Author；XMP dc:creator（或 PDF Author）	作者
Info /Subject；XMP dc:description	简介
Info /Keywords；XMP dc:subject	标签候选；不要假定任意关键词字符串都会自动拆成多个标签
XMP dc:language、dc:publisher、dc:date、dc:identifier	语言、出版社、有效出版日期、标识符；带 ISBN 标记的标识符可提供 ISBN

同一字段优先使用有效 XMP 值，缺少时再用对应 Info 值；空白或“Untitled”等无效占位标题可能被忽略。

有声书标签怎么填

想设置什么	常见的可读取标签
单文件有声书的专辑／作品标题候选	album、MP4 ©alb、ID3 TALB
音轨标题	title、MP4 ©nam、ID3 TIT2
作者候选	albumartist／album artist、MP4 aART／©ART、artist、ID3 TPE1／TPE2
朗读者	narrator、readby、reader、composer、ID3 TCOM
碟号／音轨号	discnumber／disk／TPOS；tracknumber／trkn／TRCK
系列／卷号	可读取的 series、series_name、seriesname 和 volume、series_index 等标签

当前导入的标签读取覆盖 MP3、FLAC、M4A／M4B、WAV、AIFF 等受支持入口；AAC、OGG、OPUS 等格式能作为音频导入，并不保证能在扫描时读出标签。表中的名称是不同格式的候选键，不要求每个文件都写一遍。

**多音轨目录的标题来自目录名称或目录 OPF，不把某一轨的 album 当成目录标题。**单音频文件可以用 album 提供标题候选；title 主要用于音轨展示。有效、非泛化且不重复的音轨标题可用于列表，否则回到文件名。作者、朗读者是两个字段；如果你的文件把配音者写在 artist 中，识别结果可能把他作为作者，建议用 OPF 或应用编辑纠正。

ComicInfo.xml 的最小示例

将下面内容以 UTF-8 保存为 ComicInfo.xml，放在 CBZ／ZIP 包内，与页图一起打包：

<?xml version="1.0" encoding="utf-8"?>
<ComicInfo>
  <Title>示例漫画 第一卷</Title>
  <Series>示例漫画</Series>
  <Number>1</Number>
  <Writer>张三</Writer>
  <Penciller>李四</Penciller>
  <Summary>第一卷简介。</Summary>
  <Publisher>示例出版社</Publisher>
  <Tags>冒险, 奇幻</Tags>
</ComicInfo>

在当前扫描中，作者候选取 Writer，缺少时取 Penciller；不是把所有创作角色合并成作者。Number 等字段被解析，不等于每一项都写入资源或整本的展示字段。需要可靠指定卷号时，可使用资源编辑页或 OPF。把同一个 XML 放在 CBR 内、图片目录内，或改名为 作品.xml，不会得到相同的自动识别效果。

手动读取、写回与扫描是不同操作

应用的“识别”入口用于联网搜索和应用候选，不是选择任意 XML／JSON 文件的导入器。系统的显式文件元数据接口可以读取目录 ComicInfo.xml 等文件，或对部分格式写回；这不表示扫描支持同一范围，也不表示每个页面都有对应按钮。普通使用按本页的应用编辑、联网识别、OPF 三种方法操作即可。

.nfo、metadata.json、任意 说明.txt／作品.xml 不是通用自动元数据文件。TXT 若符合书库扫描规则，可能被当成另一份读物，而不是旁边图书的说明。OPF 应使用下面列出的确切文件名；在 NAS／Linux 上按示例大小写保存，不要依赖 Windows 的大小写宽容。

怎样补充和修正信息

方法一：在应用里编辑

以下操作入口以网页为准；需要相应管理权限。

1. 打开整本图书的操作菜单，选择“编辑”，进入“编辑图书元数据”。填写标题、作者、系列名、系列序号、标签和简介；在封面区域选择图片或移除自定义封面，保存信息。
2. 只改某一卷时，找到对应资源的操作菜单，选择“编辑”，进入“编辑可读资源”。这里填写卷标题、卷号、简介、出版社、出版时间、语言、ISBN 和标识符；音频资源还可填写朗读者。该表单没有独立的作者或标签输入框，作者和标签在整本层面管理。
3. 单卷封面从对应资源菜单“上传封面”修改；不要用整本封面编辑代替单卷封面操作。普通中间目录的“编辑”主要修改该目录的标题、简介和封面，也不是整本编辑器。

手动保存的字段，包括主动清空的字段，会受到保护；后续本地识别、重扫不会简单覆盖它们。需要纠正已手动设置的值时，在对应编辑器再次保存，或在联网识别中明确勾选并应用所需字段。不会因为改了展示标题就自动给原文件改名。

方法二：联网识别后选择字段

1. 打开“设置 → 智能整理”，配置并启用需要的数据源，检查全局识别顺序；AI 来源需要额外配置和启用。
2. 从整本或指定资源的操作菜单打开“识别”，核对当前目标，输入书名等关键词并搜索。
3. 对比候选的标题、作者、封面和其他信息，选择正确条目，勾选要应用的字段后应用。资源识别中也可能出现标明属于整本的作者、系列、标签字段，勾选它们会修改整本，不能把它们当成独立单卷作者。
4. 需要自动执行时，再配置定时识别或“新增后自动执行”等选项；仅扫描文件不等于已经联网识别，开启新增自动执行也不会一次性补齐所有历史书籍。

“本地元数据优先”开启时，自动整理的其他字段以补缺为主；AI 可以纠正未受保护的标题和作者。手动应用以本次勾选字段为准，不要只看默认勾选就直接全部覆盖。自动识别失败可查看整理记录；导入失败则看导入记录，两者不是同一任务。

方法三：补充旁挂 OPF

OPF 是独立的 UTF-8 XML 文件，可以给前述格式补充元数据，不用重新制作原书。最小标题／作者示例：

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://www.idpf.org/2007/opf"
         xmlns:dc="http://purl.org/dc/elements/1.1/"
         version="2.0" unique-identifier="book-id">
  <metadata>
    <dc:identifier id="book-id">local:sample-book</dc:identifier>
    <dc:title>三体</dc:title>
    <dc:creator>刘慈欣</dc:creator>
  </metadata>
</package>

例如读物是 三体.epub，将上述内容保存为同目录的 三体.opf，不要保存成 三体.epub.opf 或 三体.opf.txt。如果给整个作品目录设置元数据，使用目录内的 metadata.opf。

OPF 文件名与查找顺序

被识别的对象	第 1 个候选	第 2 个候选	第 3 个候选
文件 作品/第一卷.epub	作品/第一卷.opf	作品/metadata.opf	作品/作品.opf
目录 作品/	作品/metadata.opf	作品/作品.opf	与目录同级的 作品.opf

扫描采用第一个存在且可有效读取、解析的 OPF。较前候选损坏或不可用时会尝试后面的候选；多个有效 OPF 不会按字段合并。一个较前的 OPF 即使只填写标题，也不会再去较后的 OPF 取作者；作者会继续按“内嵌信息 → 名称”的来源顺序补缺。

不向上任意递归寻找祖先目录的 OPF。目录内的 metadata.opf 既可能说明整本作品，也可能成为直属文件的回退来源。因此同一目录内有不同书籍时，优先给文件各自创建同名 OPF；同名不同扩展名的文件则可能共用一个 OPF。

下面让整本与各卷分别拥有清楚的信息：

library/
  示例小说/
    metadata.opf        # 整本：示例小说、作者、全书简介
    cover.jpg           # 由整本 OPF 引用
    第一卷.epub
    第一卷.opf          # 单卷：第一卷标题、出版信息、卷号
    第一卷.jpg          # 由第一卷 OPF 引用
    第二卷.epub
    第二卷.opf

metadata.opf 填整本简介，卷 OPF 填各卷简介。没有单卷 OPF 时，直属文件可能回退使用目录 OPF，显示同样的标题或简介；不要把这误认为软件会自动生成各卷信息。

包含系列、朗读者和封面的完整示例

下面是虚构数据，演示第二卷的字段写法。用于有声书时可以保留朗读者；没有对应信息就删除该元素。保存为 第二卷.opf，把封面放在它旁边的 第二卷.jpg：

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://www.idpf.org/2007/opf"
         xmlns:dc="http://purl.org/dc/elements/1.1/"
         xmlns:opf="http://www.idpf.org/2007/opf"
         version="2.0" unique-identifier="book-id">
  <metadata>
    <dc:identifier id="book-id">local:example-volume-2</dc:identifier>
    <dc:identifier opf:scheme="ISBN">9780000000002</dc:identifier>
    <dc:title>示例小说 第二卷</dc:title>
    <dc:creator opf:role="aut">张三</dc:creator>
    <dc:creator opf:role="aut">李四</dc:creator>
    <dc:contributor opf:role="nrt">王五</dc:contributor>
    <dc:description>第二卷的简介；这是示例文字。</dc:description>
    <dc:subject>科幻</dc:subject>
    <dc:subject>冒险</dc:subject>
    <dc:language>zh-CN</dc:language>
    <dc:publisher>示例出版社</dc:publisher>
    <dc:date>2024-05-01</dc:date>
    <meta name="calibre:series" content="示例小说"/>
    <meta name="calibre:series_index" content="2"/>
    <meta name="cover" content="cover-image"/>
  </metadata>
  <manifest>
    <item id="cover-image" href="第二卷.jpg" media-type="image/jpeg"/>
  </manifest>
</package>

XML 字段	提供的信息
dc:title、dc:creator	标题、作者；作者可重复多个元素，无角色或 aut／author 角色可作为作者
dc:contributor opf:role="nrt"	朗读者；不要把朗读者混填为作者
dc:description、重复的 dc:subject	简介、多个标签
dc:language、dc:publisher、dc:date	语言、出版社、有效出版日期
dc:identifier、带 opf:scheme="ISBN" 的标识符	一般标识符、ISBN
calibre:series、calibre:series_index	系列名、当前系列位置，并提供当前卷号候选；这里的 2 不是总卷数
meta name="cover" 与 manifest 中匹配的 item	指定相对 OPF 位置的封面图片

也支持 EPUB 3 的 belongs-to-collection、group-position 等系列信息，以及部分二毛图书扩展；这些扩展不保证被所有其他阅读器理解。内嵌标题、系列和卷号会分别参与作品／资源标题选择；“单本”模式保留出版物原始标题，不把系列名强行用作图书标题。

OPF 应不超过 2 MiB，不含 DOCTYPE 或实体声明；文字中的 &、< 要写成 &、<。封面使用实际图片，大小不超过 20 MiB；路径相对 OPF 所在目录，不使用网址、绝对路径、.. 或指向目录外的链接。仅放 cover.jpg 并不是适用于所有格式的通用规则。TXT／FB2／MOBI 家族在没有内嵌封面时还会尝试同名图片、cover.*、folder.*，但不能把这套回退推广到所有资源。

多个来源冲突时用谁

默认本地顺序为：OPF 文件 → 文件内部元数据 → 文件路径（自身名称）。在“设置 → 智能整理 → 本地元数据识别顺序”中可调整顺序并保存；界面中的“文件路径”并不表示从整条父目录路径猜作者。

每个字段独立选择高优先级的有效值，缺少才用下一来源。例如 三体.epub 内部有标题“三体”和作者“刘慈欣”，旁边的 三体.opf 只有标题“三体（收藏版）”，结果可为：

字段	最终值	来源
标题	三体（收藏版）	同名 OPF
作者	刘慈欣	EPUB 内嵌信息

OPF 里的空元素通常表示没有提供该字段，不表示要求清空其他来源的值。需要主动清空时，在应用编辑器中保存空值。文件名中的作者也不会无条件盖过 OPF／内嵌作者。

人工字段保护、整本／资源归属、联网整理的补缺规则仍然适用，不会因为调整本地顺序就全部失效。已经手动改过的标题不应仅靠修改 OPF 再重扫来强制覆盖。

修改后怎样生效，是否会改原文件

补充 OPF 或修改文件后

1. 确认 OPF、读物和引用图片都已完整写入书库目录，服务端有读取权限。Docker 中必须是书库实际挂载的目录。
2. 等待自动扫描，或在书库设置中执行扫描；需要补齐或重试时使用对应内容入口的“继续导入”，到“导入记录”查看执行情况。
3. 等待导入及本地识别完成，再刷新整本和目标资源详情；存在文件不代表相关元数据已经处理完。
4. 如需联网补充，再执行“识别”或查看整理记录。重扫不等于重新调用全部联网数据源。

只改展示信息优先使用编辑器，不必改文件名。移动或重命名原件后，旧阅读进度和关联信息不保证迁移；操作前按备份与恢复保存备份。

保存到应用、保存 OPF、写回原文件

操作	实际影响
应用内编辑／应用识别结果	更新系统中的对应字段；本身不会给原文件改名，也不等于改写原文件内嵌标签
开启“元数据变化自动保存到旁车 OPF”	后续图书／资源元数据变化会异步生成 OPF 和独立封面；目录目标使用 metadata.opf，文件目标使用同名 .opf；原图书资产保持不变
显式写回文件元数据	另一种会修改所选文件或旁挂目标的操作，受具体格式、字段和权限限制；不能根据“能读取”推断“能写回”

自动保存开关只观察开启之后的变化，不会立即为全库补写；关闭后已排队任务仍会完成。队列容量不足时，系统元数据仍可能已保存，但该批 OPF 任务会被丢弃并记录系统警告，因此不要把“界面保存成功”等同于“OPF 已写出”。书库只读时不能写出旁挂文件，需检查任务和日志。

为什么没识别，或看起来没有更新

现象	优先检查
作者为空	名称是否有明确作者；不要依赖父目录或 TXT 正文。检查 OPF dc:creator，以及文件是否实际带作者标签
文件名改对了，标题仍旧	OPF／内嵌信息是否优先，字段是否已被手动保护，扫描和本地识别是否完成
单卷正确，整本仍缺作者	多资源作品不会随意继承某一卷信息；给整本目录加 metadata.opf 或编辑整本
多卷显示一样的标题／简介	文件是否都回退命中目录 OPF；为每卷增加同名 OPF，或分别编辑资源
修改了后面的 OPF 但没有作用	前面是否已有一个有效 OPF；多个 OPF 不会逐字段合并，先查实际查找顺序
ComicInfo.xml 没作用	是否在 CBZ／ZIP 包内；图片目录和 CBR／RAR 的自动导入不按同一规则读取
有声书作品名变成音轨名，或作者是配音者	区分 title 与 album，检查 artist／albumartist 的内容；多轨目录用目录 OPF，朗读者单独填写
标签没有按预想拆开	OPF 每个标签使用一个 dc:subject；不要假定各种格式的一个字符串都会拆成相同的多标签
封面没出现	OPF item ID 是否匹配、相对路径和大小写是否正确、图片是否可读有效；只放一个 cover.jpg 并非通用保证
XML 文件存在但被跳过	检查真实扩展名、UTF-8 编码、XML 语法、命名空间、文件大小、权限和符号链接；到系统日志查看原因
应用保存成功但磁盘没有 OPF	检查自动保存开关、后续是否发生变化、处理队列、目录写权限和系统警告

文件本身没有导入时，先按导入与整理检查书库、扫描规则和导入记录；不要只改扩展名或反复上传同一文件来尝试补元数据。