Jellyfin 12.0 稳定版发布与升级注意事项

很高兴为大家带来 Jellyfin 12.0 新稳定版。本版本延续 10.11 的方向：完成数据库转换所开启的工作，将新基础转化为实际性能提升，并让书籍和漫画终于获得多年来应得的支持。

如果你只想快速了解升级并运行系统所需的关键信息，请阅读下方“TL; DR”部分；若想全面了解 Jellyfin 12.0 的主要特性和改进，可继续阅读。你还可在 server 和 web 的 GitHub 发布中查看完整更新日志。

- Cody

TL; DR​

提示

升级 Jellyfin 12.0 之前务必阅读本节！未这样做可能会导致问题！如有不清楚或遇到困难，请随时到 我们的聊天室 寻求帮助。

本版本会更改数据库结构，并在首次启动时主动重写数据，因此备份是你退回旧版本的唯一途径。

1. 大版本升级历来如此：请务必 停止 Jellyfin，并在升级前完整手动备份你的数据和配置目录！

2. 升级 12.0 前，必须运行 Jellyfin 10.10.7 或任意 10.11.x 版本。从 10.11.x 直接升级完全支持，无需中间步骤。如果你使用的版本低于 10.10.7，请 首先 升级到 10.10.7，再升级到 12.0。

3. 升级前请检查用户名。用户名现在不区分大小写，因此两个账户不能只靠大小写区分。如果存在这种情况，数据库迁移将会失败。

4. 升级后必须执行完整媒体库扫描。作为修复替代版本存储方式的一部分，升级过程中会清除 Jellyfin 自动归组的版本，而不是你自行合并的版本。在完成扫描之前，这些版本会显示为缺失。

5. 升级后的首次扫描会明显比平时慢，部分电影可能会显示为新添加，这是正常现象。Jellyfin 现在会将媒体库中的每个条目与磁盘上的文件逐一核对，以清理旧版本遗留的数据，之前归类错误的条目也会在过程中被自动纠正。迁移进行期间请不要停止服务器。

6. 安装完成后，如果发现界面有任何异常，请强制刷新（如 Ctrl+Shift+R 或类似操作）和/或清除 Jellyfin 实例的浏览器缓存。缓存资源过期是这类问题的头号原因。

7. 升级前请先移除所有第三方插件。为 10.11 构建的插件无法在 12.0 上加载，需要作者发布新版本，请耐心等待后再重新安装。官方插件已全部适配 12.0。

8. 过于老旧的第三方客户端将无法使用。旧版 /emby/ 和 /mediabrowser/ 地址已被移除，已废弃的登录方式也被禁用，包括在现有服务器上。多年未更新的客户端就是受影响的对象。

9. 本版本包含安全修复，建议在准备就绪后尽快升级，不要停留在旧版本上。

10. 和以往的大版本一样，Jellyfin 12.0 难免存在 bug。提交 bug 报告时请加上 "[12.0]" 前缀，方便我们快速分类处理。另外再提醒一遍第 1 条：务必备份。

接下来看看激动人心的新功能！

为什么是 12.0？​

本版本最显眼的变化就在版本号上：我们抛弃了命名方案中的主版本号 "10"。原本应该叫 10.12.0 的版本，现在直接叫 12.0，服务器上报的版本号为 12.0.0。10.11.x 是最后一个沿用旧命名方案的版本分支。

原因来自 10.11.0 之后收到的反馈，这个问题我们最早在 1 月提出，也在 5 月确认。按任何合理标准，10.11.0 都称得上大版本——它重写了 library database——但版本号让它看起来像小更新，用户也带着小更新预期升级。开头的 10. 从不变化，也不传递任何信息，结果只是把真正重要的数字挤到中间，让“大版本”看起来像小版本。去掉它之后，重大版本发布时第一位数字就会变化。

如果你维护任何解析 Jellyfin 版本字符串的组件——比如客户端、监控检查、部署脚本、固定容器镜像 tag——升级前请先关注这条。

新数据库调优​

Jellyfin 10.11.0 完成了 library database 工作机制的重建，也为本次版本的性能优化打开了空间。我们还没做完，但浏览时应该能明显感觉到提升。

其中改动最大的一项，是 playlist 和 collection 的存储方式。以前，playlist 里的所有内容都作为一个大列表保存在 playlist 自身中，数据库无法查看这个列表内部。任何需要获取的信息，都得先加载并展开整个 playlist。统计条目数、计算已观看进度，或显示单页，成本都和加载完整列表一样。编辑也同理：增删一条，都要把整个列表写回。

现在，playlist 中的每条内容都会单独成为一行。数据库可以按行计数、返回一页、增删单条而不影响其他内容，因此大 playlist 的性能应有明显提升。collection 和 boxset 之前也是这种存储方式，现在同样得到修复。

此外：

• 一次性删除大量条目时，不再中途失败。
• Continue Watching、Next Up、重看、音乐的 Latest Media、artist 查询，以及文件夹的已观看统计应该会更快。
• 高负载的数据库维护不再在 library 扫描期间运行，两者不再抢占同一资源。

大多数优化最终体现为：以前会卡住的页面不再卡住。

需要注意的一点是，这次改进的是 Jellyfin 读取媒体库的流程，而不是媒体库扫描器。扫描速度可能会顺带略快，但本次并非以加速为目标。

首次启动时会执行什么​

照例，Jellyfin 的新版本包含多个数据库迁移。迁移完成所需时间取决于媒体库规模以及累计了多少无效数据。

如果你希望主动执行这一步，而不是让它在首次启动时自动发生，服务器现在支持 --mode MigrateSystem，它会执行升级并退出，而不会启动 Jellyfin 的其余部分。

剧集多版本​

自引入以来，多版本一直只是电影专属功能。12.0 中也适用于剧集，因此拥有播出版本和加长版的节目，或同一集同时存在 1080p 和 4K 副本的情况，都能像电影一样分组。断点续播数据也会跟随你实际观看的版本。

这也是升级后必须扫描的原因：要让多版本在剧集中正确生效，需要修复版本链接的存储方式，并基于磁盘上的文件重建自动解析出的版本。

图书与漫画，这次做对了​

在 Jellyfin 中，图书长期为视频播放让路，本次版本开始改变这一现状。Bookshelf 插件过去承担的大部分功能现已迁移到服务器本身。

在服务器端：

• 图书元数据现在直接读取自 OPF 和 ComicInfo 文件，或 ComicBookInfo 注释，无需插件。
• 会为 EPUB 和所有支持的漫画压缩包格式生成海报，有声读物文件也可使用外部封面。
• 名称、索引、年份和系列会从图书文件名读取；若漫画文件名中包含卷号和章节号，也会自动识别。
• 可从漫画压缩包和 PDF 中提取页数。
• 可从有声读物中提取章节。
• Bookshelf 已拆分为独立的 GoogleBooks 和 ComicVine 提供商，新增的 OpenLibrary 插件可提供元数据和图片。
• 支持 ISBN 外部 ID 和链接。

网页客户端方面：

• 图书库新增 Modern 布局，支持视图类型和分页，并提供作者、合集和文件夹标签页。
• 书籍会显示作者信息，作者页面则列出其著作和有声书。
• 阅读界面经过重新设计，各类书籍统一标准，全屏行为一致，PDF 还支持滑动翻页。
• 受支持的电子书恢复了进度指示，新增按序号和发布日期排序，EPUB 的字号选择也有所改进。
• iOS 设备上支持后台播放有声书。

note

Bookshelf 插件已废弃，其功能已合并进服务器，或拆分到 ComicVine 和 GoogleBooks 提供者中。

更智能的推荐，以及可被插件扩展的搜索​

“更多类似内容”和建议栏的数据来源不再固定。现在你可以在选择元数据提供者的同一个地方，为每个媒体库单独指定来源，比如电影用一个来源，音乐用另一个。

ListenBrainz 已随服务器内置，作为可选来源之一。把音乐库指向它，相似艺人推荐就会基于真实收听数据，而不只是标签。

搜索也是同样的思路：插件可以在 Jellyfin 自身结果之外补充自己的搜索结果。如果你曾希望 Jellyfin 同时搜索其他地方，现在装个插件就行，不用再维护 fork。两套机制都在发布说明中为插件作者提供了文档。

Modern 布局成为默认​

之前标注为“实验性”的布局现在正式更名为 Modern，在桌面和移动端上，凡未主动选择其他布局的用户都将默认使用它。原布局仍然可用，更名为 Legacy。电视端保持不变：TV 设备继续使用 TV 布局，仍运行在 legacy 应用上。

随着转正，这套布局也做了一系列打磨：

• 所有主题——Dark、Light、WMC、Blue Radiance、Apple TV 和 Purple Haze——现在都基于 CSS 变量构建的共享基础主题派生。如果你在维护自定义主题，值得一看。
• 媒体库工具栏已并入应用栏，并新增固定式媒体库标题栏。
• 所有媒体库均可使用“合集”和“播放列表”标签页，合集也会在媒体详情页中显示。
• 音乐视频、混合媒体、合集与播放列表以及书籍视图均已更新；家庭视频和照片媒体库新增了默认标签页选项及文件夹视图。
• 新增音频与字幕语言筛选器、“重置筛选”按钮，以及工作室搜索。

升级后可能注意到的变化​

除了上面提到的旧版客户端移除之外，还有一些行为与 10.11 不同：

• 字幕设置现在按媒体库分别配置，而不再为整个服务器统一设置，因此原来的服务器级字幕选项已取消。
• 排序规则更加一致，部分媒体库的排序可能会与以往略有不同。
• 封面图不再被拉伸到超过实际尺寸。低分辨率海报现在按原始大小显示，而不是放大填满，因此看起来更小但更清晰。
• .ogg 文件现被视为音频，而非视频。如果你曾有 .ogg 视频文件，它们会在下次扫描时重新归类。
• 用户名现在可以更改大小写。因此，两个账户不能再仅凭大小写区分用户名。如果你的服务器中存在仅大小写不同的用户名，数据库迁移将会失败。
• 符号链接媒体现在会在播放时跟随链接，而不是在扫描媒体库时跟随。

安全​

本版本为服务端和 Web 客户端修复了多项安全问题。其中几项可阻止构造的请求访问 Jellyfin 应提供内容之外的文件；其他修复则包括：避免在未登录的情况下于配置不当的服务端重新运行安装向导、拒绝名称不安全的插件包、在更多位置应用家长控制，以及修复 Web 客户端中的 cross-site scripting 问题。

新功能与增强​

用户体验 - Web 客户端​

• 新增“仍在观看”提示。
• 播放中可按 , 和 . 逐帧浏览。
• 拖动进度条时，章节名称会显示在预览气泡中；播放信息浮层更紧凑，同时展示更多细节。
• 文件夹可标记为已观看。
• 优化即将播出视图，并在系列资料库中新增“全部播放”和“随机播放”按钮。
• 查看照片或阅读时不会触发屏保；Modern 布局中新增屏保时间设置。
• 担任多个角色的演职人员会合并到同一张卡片，电视节目创作者信息会显示在条目详情中。
• 照片幻灯片的切换延迟可配置。
• Web 客户端会在浏览器中缓存更多数据，因此已访问页面的返回速度更快，高清显示屏上的封面图也不会再模糊。
• 修复手柄导航问题，键盘快捷键可适配非拉丁语键盘布局，并支持遥控器上的快退和快进按钮。

管理员体验 - Web 客户端​

• 日志查看器可实时跟踪日志，无需手动刷新。
• 活动页面支持排序和筛选。
• 相似条目和推荐数据来源可按资料库配置。
• Jellyfin 现在会用 CACHEDIR.tag 标记其缓存目录，以便备份工具识别并跳过，而不是备份这些文件。
• 客户端可请求以指定语言返回响应，因此同一服务器中偏好不同语言的用户体验会更好。
• 数据库文件可放置在默认位置以外的路径。
• 已禁用的插件重启后不会再被重新启用。
• 备份遇到损坏记录时不再整体失败；恢复备份前会先弹出警告，在媒体库扫描进行时启动备份也会收到提示。
• 启动界面焕然一新，可以显示版本和活动信息。
• 合集和播放列表可以按媒体库筛选，每个媒体库只显示自己的内容。
• 搜索演职人员时增加了更多筛选方式；音频可选优先使用影片原声语言；条目页面新增"合集"列表。
• Live TV：支持导入 XMLTV 背景图和剧集缩略图；不再向客户端返回无法访问的"服务器本地"流媒体地址；XMLTV 节目指南导入时会跳过数据未变化的节目，让重复刷新指南的开销大幅降低。
• 元数据：电影支持 TVDB ID；新增 AudioDb 艺人搜索；从音乐文件读取 ReplayGain 专辑增益；MusicBrainz 查询更加健壮；识别文件名中的 WEB-DL 标记；支持在季和剧集的文件夹名上设置 provider ID。
• 解析 Provider Identifier 时除了方括号，现在还支持花括号和圆括号，并新增别名：tvdb 对应 tvdbid、imdb 对应 imdbid、tmdb 对应 tmdbid。
• 优化数据库任务在触发时和关机时都会对数据库执行分析和清理（vacuum）。
• Refresh People 任务现在能正确清理已删除的演职人员，并为缺失图片的人员检查更新。
• Live TV：EPG 现在遵循 SchedulesDirect API 的错误码，避免被锁定；HDHomeRun 调谐器可在支持的客户端上直接播放；M3U 调谐器不再直接播放，默认改为 remux。
• 播放列表媒体库的图片现在可以通过 Metadata Manager 为所有用户统一设置。播放列表也允许添加重复曲目了。

转码与媒体处理​

• 升级到上游全新的 FFmpeg 8.1。
• 优化了 CUDA 转置、OCL 缩放和 OCL 色调映射的性能，其中色调映射针对 Mali GPU 做了专项优化。
• HLG 色调映射现在使用 BT.2446 Method B 的 EOTF。
• 为 Dolby Vision Profile 5 提供符合规范的 dvh1 HLS 变体，提升设备兼容性。
• 修复了 HLS 在视频转码、音频 remux 时可能出现的音画不同步问题。
• 字幕写入现在通过 SubtitleEdit 处理，避免了旧的 SSA 转 ASS 转换及随之而来的样式丢失。
• 支持 VobSub 字幕；转码时可将外置字幕嵌入 MKS，字幕提取超时时间可配置，图像字幕可在重封装时由客户端渲染。
• 为无法处理旋转视频的 Android TV 盒子增加设备 profile 选项，使横拍的手机视频可以正向播放。
• Trickplay 现在扫描时会复用已存在的文件，而不是重新生成；不再为隔行扫描视频产生重复项；可处理源文件中的坏时间戳；生成失败时会自动清理相关文件。
• Web 客户端改进设备支持：webOS 25 及更高版本支持 MKV 文件中的 Dolby Vision，TV 客户端支持 AV1 直接流播放，Tizen 支持 anamorphic 视频直接播放，iOS 支持息屏后台播放，并修复音频归一化影响音高和播放速度的问题。

客户端开发变更​

以下变更适用于所有客户端应用开发者。请仔细查看，并根据需要更新你的应用。

HTTP API​

• 已弃用的授权机制现在默认禁用。如果尚未迁移，请参阅此拉取请求中的详情。
• GetItems 现在为异步，并在请求包含筛选条件时应用 recursive，该限制仅适用于包含 includeItemTypes 的请求。与 10.11 相比，相同查询可能返回不同的结果集。
• ItemByName 响应受限，人员数据已去重。
• 新弃用但仍可用：GetTrailers（改用 GetItems 并指定 includeItemTypes=Trailer）、GetArtists 和 GetAlbumArtists（改用 GetPersons）、GetArtistByName（改用 GetPerson）、GetMusicGenre（改用 GetGenre）、音乐流派即时混音接口（改用 GetInstantMixFromItem）、GetRecordingsSeries，以及启动路由（改用配置接口）。UserDto.HasPassword 也已弃用，且不再提供有用信息。HLS 控制器已从 OpenAPI 规范中隐藏。
• Swashbuckle 已更新至 v10，这会改变生成的 OpenAPI 文档。SDK 需要重新生成。
• 已移除路由：POST /Users/\{userId\}/EasyPassword、GET /Items/\{itemId\}/CriticReviews、GET /Environment/NetworkShares、POST /System/MediaEncoder/Path 和 GET /LiveTv/Recordings/Groups/\{groupId\} 均已是弃用的空操作，只会返回 403、404 或空结果。GET /QuickConnect/Initiate 原本可用，是 POST 路由的别名，因此使用 GET 形式的客户端需改用 POST。

关于 API 支持政策的一般提醒：若接口未列在 OpenAPI 规范中，则不应使用；若接口或参数被标记为弃用，也不应使用。弃用项通常会在一个完整的主要版本周期内保持标记，之后才移除。

插件​

• 服务器现以 .NET 10 为目标，多个插件接口已发生变化。插件需要重新指向 .NET 10 并针对 12.0 重新构建。
• 插件可新增以下能力：提供搜索结果、相似度与推荐数据、漫画元数据、未播出或缺失剧集数据，使用演职员的聚合 credits，为有声书等非视频项目保存章节，处理服务器无法识别的用户名对应的密码重置，并在项目数据被清理时清除自身提取的文件。Live TV 插件还可通过服务器查询 Schedules Direct 可用性，而无需自行实现。
• 原先支持备选版本或播放列表内容的插件需要关注，因为这些数据不再存储在父项目内。现针对这两类数据提供了新的库方法。
• 新增、变更和移除的接口完整列表见发布说明——其中主要的破坏性变更包括 ISearchEngine、IAuthenticationProvider.HasPassword、IItemRepository 的部分内容，以及 IUserManager 的若干成员。

弃用内置 TLS/SSL 支持​

我们在 10.11.0 的发布说明中宣布过，将在本版本移除内置的 TLS/SSL 支持。该移除计划已推迟到未来的版本。我们的立场没有变——仍然推荐在反向代理后面运行 Jellyfin。所以如果你正在用 Jellyfin 内置 TLS 运行面向公网的实例，这次只是多给你一些迁移时间，并非网开一面。

祝观影愉快！