转换失败类问题
EPUB/MOBI/PDF 等格式互转时遇到的各种报错
EPUB 转 MOBI 失败，提示 "Conversion Error"
原因分析：源 EPUB 内部结构不规范（缺少 toc.ncx、HTML 语法错误、图片路径无效等）
- 在 Calibre 中右键书籍 → "编辑书籍"，检查 EPUB 内部 HTML 是否有红色错误标记
- 运行"检查书籍"功能（编辑器中工具栏），会自动修复常见结构问题
- 尝试先转为 EPUB（EPUB → EPUB），以修复内部结构，再转为 MOBI
- 在转换设置中降低"分割文件大小"至 100KB，避免单文件过大导致转换超时
转换后中文全部变成乱码
原因分析：输出格式的字符编码设置错误，或源文件的字体声明缺失
- 转换设置 → 外观 → "嵌入字体家族"中勾选中文字体（如"宋体""黑体"）
- "输入字符编码"手动指定为 UTF-8（默认的自动检测有时会误判为 GBK）
- 确保源文件中 CSS 的 @font-face 声明了中文字体
转换后排版全部错乱，段落消失
原因分析：源文件的 CSS 样式与 Calibre 默认样式冲突，或段落使用了非标准标签
- 转换设置 → 外观 → "布局"中勾选"移除段落间空白"并保留首行缩进
- "过滤样式信息"勾选"字体""边距"等非必要属性
- 在"转换设置 → 查找与替换"中添加正则规则，清理源文件中的冗余样式
转换后文件大小为 0KB 或非常小
原因分析：源文件损坏（下载不完整）、Calibre 转换引擎在解析时崩溃
- 尝试用其他阅读器打开源文件，确认文件本身完整可用
- 将源文件在 Calibre 中先转为 EPUB（即使它已经是 EPUB），清理内部损坏节点后再转目标格式
- 降低转换设置中的"分割文件大小"至 50KB，减小单次转换负担
设备不识别类问题
USB 连接后 Calibre 无法检测到设备
USB 连接电纸书设备后，Calibre 没有任何反应
原因分析：数据线不支持数据传输（仅充电）、USB 接口供电不足、设备端选择了"仅充电"模式、驱动程序缺失
- 更换数据线：许多随设备附赠的线缆仅支持充电。换一根确认支持数据传输的 USB 线（手机原装线通常可用）
- 更换 USB 接口：优先使用电脑主机后置 USB 接口（供电更稳定）
- 检查设备端：确保电纸书选择了"传输文件"/"连接电脑"模式，而非"仅充电"
- 重启 Calibre（完全退出后重新打开）
- Windows 用户：打开设备管理器，查看是否出现带有黄色感叹号的未知设备。如有，右键更新驱动程序
Kindle 连接后显示为 MTP 设备，无法传输书籍
原因分析：较新的 Kindle 型号使用 MTP 协议而非 USB 大容量存储模式
- Windows 10/11 原生支持 MTP，通常无需额外操作
- 确保 Windows Media Player 功能已启用（控制面板 → 程序 → 启用或关闭 Windows 功能 → 勾选"媒体功能"）
- Linux 用户安装 MTP 支持：
sudo apt install mtp-tools libmtp9 - 如果 Calibre 仍不识别，尝试在 Kindle 上切换 USB 模式：设置 → 设备选项 → USB 模式 → 切换为大容量存储
设备已识别但发送书籍时提示"无法写入设备"
原因分析：设备存储空间不足、设备文件系统为只读模式、设备正在进行索引操作
- 检查设备剩余存储空间（在 Calibre 设备视图中可看到）
- 等待设备完成索引后再传输（刚插入时设备可能正在扫描已有书籍）
- 安全弹出设备、拔线、重启设备、重新连接
数据库类问题
metadata.db 相关的锁定、损坏与修复
Calibre 启动提示"数据库被锁定"
原因分析：另一个 Calibre 实例正在使用同一书库、书库位于网络驱动器（NAS/SMB）上且不支持文件锁、上次异常退出未释放锁
- 检查任务管理器中是否已经有 Calibre 进程在运行。如有，结束所有 calibre.exe 进程后重新启动
- 如果书库位于 NAS 或网络驱动器，建议将书库移到本地磁盘。Calibre 官方不推荐在网络上运行书库
- 进入书库文件夹，删除
metadata_db_prefs_backup.json（仅备份文件，不影响数据）后重试 - 如果上述步骤无效，关闭 Calibre，在书库文件夹中找到
metadata.db，复制一份到桌面，删除原文件，将备份更名为 metadata.db 放回
数据库损坏：书籍丢失、封面错乱、无法搜索
原因分析：计算机异常关机、磁盘错误、防病毒软件误删、书库路径变更
- Calibre → 书库 → 书库维护 → "检查书库"（自动修复数据库一致性问题）
- 如果检查失败，使用"恢复书库"功能：书库 → 书库维护 → 恢复书库（从 OPF 文件重建 metadata.db）
- 在恢复前，务必先备份书库文件夹（复制整个 Calibre Library 目录）
- 事后排查：检查磁盘是否有坏道（运行 chkdsk），检查防病毒软件是否隔离了 Calibre 的文件
迁移到新电脑后 Calibre 报错"书库路径不正确"
原因分析：书库文件夹路径变动，Calibre 配置文件中的旧路径失效
- 将整个 Calibre Library 文件夹复制到新电脑的固定位置（如 C:\Users\用户名\Calibre Library）
- 启动 Calibre → 书库 → 切换/创建书库 → 选择新位置
- 同时复制配置文件夹（偏好设置 → 杂项 → 打开配置目录），将旧配置覆盖到新电脑的同位置
封面与元数据类问题
封面不显示、元数据下载失败
封面在 Calibre 中显示正常，但发送到设备后不显示
原因分析：封面未嵌入电子书文件内部、设备缓存未刷新、Kindle 系统封面缓存机制导致
- 在 Calibre 中使用"修饰 EPUB"（安装 Modify ePub 插件）强制将封面嵌入文件
- Kindle 用户：发送书籍后，务必先"安全弹出"再拔线。拔线后等 Kindle 完成索引（屏幕不再闪烁）封面才会出现
- 如果封面仍不显示：重新连接 USB → 等待 Calibre 识别设备 → 直接安全弹出（不传书），Calibre 会在弹出时自动修复 Kindle 封面缓存
- Kobo 用户：安装 KoboTouchExtended 插件可自动修复封面显示问题
"下载元数据和封面"一直超时或返回空结果
原因分析：网络不通（数据源被墙）、数据源配置不当、书名过于模糊
- 偏好设置 → 元数据下载 → 调整数据源顺序：中文书籍优先用豆瓣/Amazon.cn
- 安装"Douban Metadata"插件获取更准确的中文书元数据
- 手动在"编辑元数据"窗口输入 ISBN 再下载（ISBN 匹配的准确率远高于书名）
- 如果使用代理，在 Calibre 中设置网络代理：偏好设置 → 杂项 → 网络代理
ISBN 查询超时或返回错误书籍信息
原因分析：ISBN 号有误（多了一位或少一位）、数据源无此书信息
- 确认 ISBN 号无误：标准 ISBN 为 10 位或 13 位数字
- 尝试去掉 ISBN 中的连字符后重试
- 更换数据源：Amazon 和豆瓣的 ISBN 库覆盖不同，交叉尝试
性能类问题
启动慢、卡死、内存占用高
Calibre 启动非常慢，打开需要几十秒
原因分析：书库过大（超过 1 万本）、磁盘慢（机械硬盘）、启动时加载了过多插件
- 将书库迁移到 SSD 上（metadata.db 随机读写频繁，SSD 提升明显）
- 禁用不常用的插件：偏好设置 → 插件 → 选中插件 → 禁用
- 定期清理书库中的无效条目和冗余格式
- 如果书库超过 5 万本，考虑拆分为多个独立书库（书库 → 切换/创建书库）
导入大量书籍（500+）时 Calibre 卡死
原因分析：元数据下载队列过载、自动转换设置导致并发任务过多
- 分批导入，每批不超过 200 本
- 导入时先不下载元数据（导入完成后再批量下载）
- 临时关闭自动转换：偏好设置 → 添加书籍 → 取消勾选"自动转换"
Calibre 内存占用超过 2GB
原因分析：内置阅读器打开了多个大文件、后台转换任务积压
- 关闭不用的电子书查看窗口（每个窗口都缓存了整本书）
- 检查右下角"任务"面板，确认没有卡住的转换任务
- 在"偏好设置 → 杂项"中限制同时运行的任务数
- 重启 Calibre 释放内存
插件类问题
插件安装失败、报错、版本不兼容
DeDRM 插件报错 "未配置密钥"
原因分析：DeDRM 需要输入你的设备序列号或 Adobe ID 才能正确解密
- Calibre → 偏好设置 → 插件 → 文件类型 → 找到 DeDRM → 自定义插件
- 添加 Kindle 序列号（设置 → 设备选项 → 设备信息中查看）
- 或添加 Adobe Digital Editions 的授权信息（ADEPT key）
- 重启 Calibre 后重新导入受保护书籍
"从文件加载插件"点击后无反应或提示格式错误
原因分析：插件文件格式不正确（不是 .zip 格式）、文件损坏、Calibre 版本过旧
- 确认插件文件扩展名为
.zip（不要解压！Calibre 直接加载 zip 文件） - 重新从源地址下载插件（GitHub 上的 Release 页面最可靠）
- 更新 Calibre 到最新版本（帮助 → 检查更新）
安装插件后提示"版本不兼容"
原因分析：插件开发者未及时跟进 Calibre 新版本 API 变更
- 降级 Calibre 到插件支持的版本（不推荐，可能失去安全更新）
- 前往插件的 GitHub Issues 页面查看是否有社区提供的兼容补丁
- 搜索是否有替代插件实现了相同功能
- 等待插件开发者更新，通常大版本适配周期为 1-4 周
Calibre-Web 类问题
Docker 部署后的常见服务端报错
登录页面无限循环，输入密码后又回到登录页
原因分析：Session 存储配置错误、反向代理未正确传递 Cookie
- 清除浏览器 Cookie 和缓存后重试
- 如果是反向代理环境，确保 proxy_set_header 正确传递了 Host 和 X-Forwarded-Proto
- 检查容器内 /config 目录的读写权限
数据库路径正确但仍然提示 "Invalid Database Location"
原因分析：容器内对 /books 目录没有读取权限、metadata.db 被其他进程锁定
- 检查宿主机上书库目录的权限：
ls -la /path/to/Calibre\ Library/ - 确保 PUID/PGID 与宿主机用户一致：运行
id查看 UID 和 GID - 确认没有 Calibre 桌面端同时打开该书库（metadata.db 不支持并发访问）
反向代理返回 502 Bad Gateway
原因分析：Calibre-Web 容器未运行、端口映射错误、Nginx/Caddy 配置的 proxy_pass 地址不正确
- 确认容器运行中：
docker ps | grep calibre-web - 确认端口映射：
docker port calibre-web查看宿主机端口 - Nginx 中 proxy_pass 必须指向正确的宿主机地址和端口
- 查看容器日志：
docker logs calibre-web --tail 50
转换服务异常，提示 "converter not found"
原因分析：DOCKER_MODS 未生效或 ebook-convert 路径配置错误
- 确认 docker-compose.yml 中包含
DOCKER_MODS=linuxserver/calibre-web:calibre - 修改 compose 文件后需要重建容器：
docker compose down && docker compose up -d - 在 Calibre-Web 管理面板中检查"电子书转换器路径"是否为
/usr/bin/ebook-convert