Kodi字幕库插件ZimukuX十分钟安装配置与乱码时间轴排查

折腾 Kodi 的人多半都撞见过同一个场面：片子已经点开播放，片头过去两分钟了，人还在另一台设备上翻字幕站，下载、解压、改名、拷回共享目录，一顿操作猛如虎，回头一看字幕是另一个版本的，时间轴差了好几秒。这类重复劳动我干过好几年，直到把字幕库插件 ZimukuX 装进 Kodi，整个流程才被压缩到十分钟以内——这不是形容词，是我拿秒表把安装、配置、验证三段分别计过时的结果。

这篇东西想解决的问题很具体：让一个只用过 Kodi 基本播放功能的人，能在十分钟里把 ZimukuX 这类字幕库插件装好、配对、跑通第一次字幕下载，并且知道后面搜不到字幕、字幕乱码、时间轴对不上时该往哪一层查。它适合家里有 NAS 或者本地影音库、习惯用 Kodi 做统一入口、片子以中文或中英双语字幕为主的用户；如果你只是偶尔在手机上看两部片，装插件反而是负担。下面所有内容都基于我自己在 Windows 客户端、Android 电视盒子和一台常年开着的 Linux 小主机上的实际配置整理，参数取值和踩坑记录都来自真实调试过程。

1. 先说清楚：Kodi 的字幕为什么总是不听话

1.1 原生字幕机制的三个硬伤

Kodi 本身对字幕的支持并不差，它能加载 SRT、ASS、SSA、SUB、VTT 这一票格式，能调字号、颜色、描边、垂直位置，播放中还能实时调延迟。问题在于它是被动的——Kodi 只负责"读"，不负责"找"。你在媒体库里点开一部片子，Kodi 会按约定去视频同目录下找同名同语言标记的字幕文件，找到就加载，找不到就静默跳过，连个提示都不给。

第一个硬伤就是这种"静默失败"。很多人以为插件没装好，其实是字幕文件命名不符合规范，Kodi 压根没认出来。第二个硬伤是语言标记的混乱：Kodi 认的是 ISO 639 系的两位或三位语言码，.zh.srt、.chi.srt、.zh-cn.srt在它眼里不完全等价，而各大字幕站导出的文件名五花八门，影片名.chs.srt、影片名.简体.srt、影片名.中英.srt都有，Kodi 全靠文件名后缀猜，猜不中就当成未知语言。第三个硬伤是版本漂移，同一部片子的蓝光版、WEB 版、导演剪辑版时长能差出几分钟，字幕时间轴自然对不上，Kodi 不会替你做这个判断。

这三个问题叠加起来，结果就是"我知道有字幕，但 Kodi 不用"。字幕库插件要解决的正是中间那段最烦的人工环节：搜索、比对、下载、落盘、重命名。

1.2 字幕插件到底补上了哪块短板

Kodi 的插件体系里，字幕下载属于一类很特殊的存在——它不是普通的script脚本，而是service类型服务。区别在于，脚本插件你要主动去"程序插件"里点开运行，而服务插件装好启用之后，会挂接到播放器的字幕菜单里，你在播放时按一下遥控器上的字幕键，菜单底部就多出一个"下载字幕"的入口。

以 ZimukuX 这一类字幕库插件的工作方式来看，它做的事情大致分四步：从 Kodi 拿到当前播放文件的路径和媒体库元数据（片名、原始片名、年份、季集号），把这些信息拼成搜索关键词去字幕源查询，把返回的结果列表按语言和匹配度排序展示给你，你选中之后它负责下载并把文件写到指定目录，同时按 Kodi 认的规则重命名。

真正有价值的是第四步。手动下载字幕最烦的不是找，是改名和放对位置。插件把这一步自动化之后，"看片前先花三分钟找字幕"这件事才真正消失。而且它拿得到媒体库里的originaltitle字段——也就是影片的原始语言片名，中文片名搜索命中率低的时候，用原始片名去搜往往一击即中，这个信息手动操作时你根本不会想起来用。

1.3 这套方案适合谁、不适合谁

说句实在话，字幕插件不是人人都需要装。我把它分成三类场景来看，你可以对号入座。

适合装的情况：片源集中在一个媒体库里，几百上千部，靠人工补字幕根本不现实；片源以非中文原声为主，需要中文字幕；家里有多个播放端，Kodi 是统一入口，字幕跟着媒体库走比跟着设备走更省事；片源目录可写，插件能直接把字幕写回去。

不太需要装的情况：片源本身内嵌字幕轨（MKV 里封了字幕流），Kodi 直接切换字幕轨就行，外挂字幕纯属多余；观看内容以流媒体插件为主，不走本地媒体库，插件的元数据来源会失效；片源放在只读挂载的共享目录里，插件下载完写不进去，装了也是白装。

这里要强调一点：这套东西只适合给你自己合法持有观看权限的影音内容配字幕。字幕文件本身是辅助理解的文本，但把它配到没有观看权限的片源上，性质就变了，这个界限自己心里要有数。

2. 装之前必须做的四件准备

2.1 版本对齐：插件与 Kodi 主程序的兼容关系

这一步被跳过的概率最高，出问题的概率也最高。Kodi 每个大版本都会调整 Python 运行时：18 及以前是 Python 2，19 开始切到 Python 3，20 和 21 又各自抬高了最低 API 版本。插件包里的addon.xml会写明它依赖的xbmc.python版本号，版本不匹配时，从 ZIP 安装会直接弹"依赖无法满足"，或者装上了但菜单里根本不出现。

实操上，先确认你的 Kodi 主版本号，位置在设置 → 系统信息 → 关于，或者在主界面左下角的系统菜单里能看到。然后去找对应版本的插件包。我的经验是：宁可找旧一档的插件版本，也不要硬把新包塞进旧主程序，后者即使装上也会在调用某些 API 时直接崩掉，而且崩溃日志里只报一个模糊的AttributeError，排查起来非常浪费时间。

另外提醒一句，Kodi 的插件目录结构是固定，service.subtitles.xxx这种命名不是随便起的，前缀决定了它在系统里被归到哪一类。手动解压安装时如果改了文件夹名，插件会加载失败。

2.2 文件命名与媒体库整理

字幕插件能搜得准，前提是 Kodi 知道你在放什么片。而 Kodi 判断"这是什么片"，靠的是文件名解析加媒体库刮削。如果你的文件叫movie_1080p_x265_final.mkv这种，刮削器猜不出片名，媒体库里就是一堆"未识别"，插件拿不到元数据，搜索自然无从谈起。

我建议在装插件之前，先花二十分钟把片名规范一遍。推荐的命名格式是中文片名.英文片名.年份.分辨率.mkv，刮削器对这套格式的识别率最高。整理完之后在 Kodi 里对视频源做一次"扫描到库"，确认每部片子都能正确显示海报和简介，再往下走。

还有一个容易被忽略的点：季集号。剧集的命名规范比电影严格得多，剧名.S01E03.mkv是通用写法，插件靠这个正则提取季集信息去匹配对应字幕。写成剧名 第三集.mkv或者剧名_ep3.mkv，电影部分可能还能救，剧集基本废掉。

2.3 目录写权限：最容易翻车的一环

插件下载字幕之后要写文件，写到哪、能不能写，是整套流程里最容易翻车的一环，而且失败表现很隐蔽——界面上显示"下载成功"，实际文件根本没落地，或者落在了一个你根本找不到的临时目录里。

分平台说。Windows 上如果是本地磁盘，一般没问题；如果片源在映射的网络驱动器上，要看映射账号有没有写权限。Android 电视盒子上，Kodi 需要拿到存储访问权限，Android 11 之后对外部存储的访问限制变严，Kodi 只能写它自己的应用私有目录和用户明确授权的目录，这时候把字幕下载目录设成视频同目录大概率失败，得改成"下载到 Kodi 私有目录然后手动搬"，或者干脆把片源放在授权过的路径下。

Linux 小主机和 NAS 上最常见的问题是挂载参数。SMB 或 NFS 挂载成只读（ro）的时候，Kodi 读得到文件但写不进去。检查方法很直接，在 Kodi 的文件管理器里试着在视频目录新建一个空文件夹，建不了就是权限问题，跟插件无关。

注意：不要在没确认写权限的情况下反复重装插件，那是在治感冒吃胃药。先把"能不能在这个目录写文件"这一件事验证掉。

2.4 网络与请求节奏的基本认知

字幕源站点是别人的服务器，不是你家局域网。插件搜一部片子，背后可能是好几次 HTTP 请求，批量补字幕的时候请求量会成倍上涨。这里有两个基本原则。

一是控制节奏。插件设置里一般有"请求间隔"或"每次搜索的结果数"这类选项，默认值往往偏激进。我习惯把单次结果数压到 10 条以内，请求间隔留个一两秒。这不是技术洁癖，是实际体验问题——请求打得太密，对方返回空结果的概率反而上升，你会误以为是插件坏了。

二是留好超时余量。默认超时通常设得很短，家宽访问境外或者跨运营商的站点时，一次握手就可能超时。把超时从默认值往上调一档，比如调到 15 到 20 秒，能显著减少"搜不到"的误报。这个参数在插件设置里通常叫"超时"或者"Timeout"，单位是秒。

3. 十分钟装完：从 ZIP 包到第一次成功搜索

3.1 安装包与依赖的落地方式

Kodi 装插件有两条路：从官方或第三方插件仓库在线安装，以及从本地 ZIP 包安装。字幕插件这类东西，在线仓库里能直接搜到的越来越少，多数时候得走 ZIP 包路线。整个流程分四步，我按实际操作顺序写。

第一步，把 ZIP 包放到 Kodi 能访问到的位置。最省事的做法是放在片源同目录，或者放 U 盘插到盒子上。安卓盒子上也可以先用系统自带的文件管理器把包拷到 Download 目录。

第二步，在 Kodi 里添加这个位置为文件源。路径是 设置 → 文件管理器 → 添加源 → 浏览，选中 ZIP 包所在的文件夹，起个名字比如local，确定。

第三步，安装。路径是 设置 → 插件 → 从 ZIP 文件安装，选中刚才那个源，找到 ZIP 包，点确定。安装过程中屏幕上会闪一行"插件已启用"的提示，一闪而过，很多人以为没成功。

第四步，验证。回到 设置 → 插件 → 我的插件，往下翻，看是不是真的出现了这个字幕插件的图标。出现了但显示灰色或者带个感叹号，说明依赖没满足，这个下一节讲。

Kodi 用户数据目录（userdata）位置参考： Windows %APPDATA%\Kodi\userdata\ Linux ~/.kodi/userdata/ macOS ~/Library/Application Support/Kodi/userdata/ Android /sdcard/Android/data/org.xbmc.kodi/files/.kodi/userdata/

插件装好之后，它的配置文件会落在userdata/addon_data/service.subtitles.xxx/settings.xml，这个文件后面调试时会经常看，建议先记住位置。

3.2 关键配置项逐条说明

装完不等于能用。打开插件的设置界面（我的插件 → 选中插件 → 配置，或者从播放时的字幕菜单进去），里面有十来项参数，其中有五项必须调。

字幕语言。这一项决定了搜索时优先返回哪种语言的结果。常见选项有简体中文、繁体中文、中英双语、英文。如果你主要看中文，勾简体中文就行；想让插件优先给双语字幕，就勾中英双语。我一般会勾两个：简体中文和中英双语，让插件在这两类里挑。

下载目录。这里有两个选项，一个是"下载到视频同目录"，一个是"下载到指定目录"。前者最省事，字幕和视频放一起，Kodi 下次自动加载；但前提是 2.3 里说的写权限没问题。后者适合片源在只读目录下的场景，但你需要自己维护一个映射关系，长期下来很烦。我建议能用前者就用前者。

字幕文件命名规则。这是决定"能不能被 Kodi 自动认出来"的核心项。正确的规则是让下载下来的文件名跟视频文件名完全一致，再加语言后缀。比如视频是片名.2023.1080p.mkv，字幕就该是片名.2023.1080p.zh.srt。插件设置里通常有"使用视频文件名"的选项，务必勾上，别用"使用字幕原始文件名"。

超时时间。前面提过，调到 15 到 20 秒。

优先片名来源。这一项有的插件叫"使用原始标题"，有的叫"优先使用英文名"。打开它，插件会优先用媒体库里的originaltitle字段搜索，中文片名搜不到的时候这是救命选项。

剩下那些"结果数量""是否显示下载量"之类的，按默认走就行，调多了反而干扰判断。

3.3 第一次搜索的验证方法

配置完成之后，必须做一次端到端验证，别等到正式看片时才发现问题。

挑一部你确定有字幕资源的片子，最好是有点知名度的老片，资源丰富。在媒体库里点开播放，播放中按遥控器或者键盘上的字幕键（Kodi 默认快捷键是T，遥控器上是字幕图标），弹出字幕菜单，最下面一项应该能看到"下载字幕"。

点进去，插件会开始搜索，几秒后弹出结果列表。列表里每条通常显示字幕标题、语言、格式、下载次数。选中一条下载，正常情况下会弹一个"下载完成"的提示，然后字幕立刻加载上屏。

验证成功的标志有三个：字幕出现在屏幕上；视频目录下多了一个同名.zh.srt文件；退出播放再重新进入，字幕能自动加载。三个都满足，说明配置完全正确，后面就是纯使用问题了。

如果列表是空的，别急着重装，先看下一节的排查逻辑。如果列表有内容但下载后没反应，八成是写权限或者下载目录的问题。

4. 匹配率不够？把搜索逻辑吃透再调

4.1 文件名匹配的清洗规则

字幕插件的搜索本质上是字符串匹配，它的输入是文件名清洗后的结果。理解清洗规则，你就能主动调整文件名来提高命中率。

常规的清洗流程是这样的：先去掉扩展名，然后按点、下划线、空格切分成若干段，再用正则过滤掉分辨率标记（1080p、2160p、4K）、编码标记（x264、x265、HEVC）、音轨标记（DTS、AAC、TrueHD）、发布组标记（方括号里的内容和结尾的连字符后缀），最后把剩下的部分拼成搜索词。

问题出在中文片名上。中文没有词间空格，流浪地球2和流浪地球 2在切分逻辑里完全不同。很多插件对中文的处理是整串保留，不做切分，这就导致流浪地球2.2023.2160p.mkv能搜到，而流浪地球2蓝光版.2023.mkv因为多了"蓝光版"三个字就搜偏了。

我的处理办法是手动规范：中文片名和数字之间加个空格或者点，附加信息一律不用中文写，全部用标准的英文技术标记。这看起来是小事，实测下来对命中率影响非常大。下面这段正则是我在自己环境里用来预检文件名规范性的，跑一遍就能看出哪些文件"不干净"。

import os import re TECH_PATTERN = re.compile( r'(2160p|1080p|720p|480p|4k|uhd|bluray|blu-ray|web-?dl|webrip|hdtv|' r'x264|x265|h264|h265|hevc|avc|aac|dts|truehd|atmos|10bit|hdr|dv|remux)', re.IGNORECASE ) def check_name(fname): stem = os.path.splitext(fname)[0] if re.search(r'[\u4e00-\u9fff]{2,}\d', stem): return 'SUSPECT', '中文与数字之间缺少分隔' if re.search(r'[\u4e00-\u9fff](蓝光|高清|修复|国粤|双语|完整版)', stem): return 'SUSPECT', '含中文附加信息，建议改用英文标记' if not TECH_PATTERN.search(stem): return 'WARN', '缺少技术标记，刮削可能不准' return 'OK', '' for root, _, files in os.walk('/path/to/media'): for f in files: if f.lower().endswith(('.mkv', '.mp4', '.avi', '.ts')): status, msg = check_name(f) if status != 'OK': print(f'[{status}] {f} -> {msg}')

这段脚本不能替你改名，但能帮你把问题文件挑出来，比一个个肉眼扫快得多。

4.2 语言标记与字幕优先级

Kodi 对字幕语言的识别完全依赖文件名里的语言后缀。规范写法是视频文件名.语言码.扩展名，语言码用 ISO 639-1 的两位码最省事：zh中文、en英文、ja日文、ko韩文。带地区的写zh-CN、zh-TW也能识别，但兼容性不如两位码。

为什么这件事重要？因为 Kodi 在播放时会按你在 设置 → 播放器 → 语言 → 字幕 里配置的"首选字幕语言"顺序自动加载。如果你配的顺序是简体中文优先，而字幕文件叫xxx.chs.srt，Kodi 不认chs，就会跳过它去找下一个，最后可能加载了一个英文字幕或者干脆不加载。

还有一个细节：不带语言后缀的字幕文件（视频文件名.srt）会被 Kodi 当作"默认字幕"，优先级最高。很多人手动下载字幕之后直接改成视频同名，结果中文片源里本来就有一份英文字幕，两边打架。规范做法是一律带语言后缀，哪怕只有一份。

4.3 多版本片源的取舍策略

同一部片子，你的库里可能有 1080p 和 4K 两个版本，播放时长差几十秒。字幕资源大多对应其中一个版本，插件搜出来也不会告诉你是哪个版本的。这时候怎么选？

我的经验是按"帧率"和"片长"两个维度判断。字幕站的条目里通常会写适配的版本信息，比如"蓝光版""WEB 版"，或者直接标注时长。选中之前扫一眼这些信息，比下载完发现对不上再换要省事得多。

如果没有版本信息，就看下载量和更新时间。下载量特别高的通常是通用版，偏移不会太离谱；更新日期很近的往往对应最新的片源版本。实在判断不了，就先把候选的都下下来，在播放器里逐个试，Kodi 的"下一字幕"快捷键切换起来很快。

还有一个取巧的办法：如果你的库里有多个版本，先用 1080p 版本去搜字幕，因为字幕资源绝大多数是针对 1080p 蓝光做的分离，4K 版本往往需要重新对齐。

5. 编码、字体、时间轴：三个高频字幕病

5.1 中文乱码的三种成因与对症处理

中文乱码是外挂字幕最常见的毛病，但成因分三种，处理方式完全不同，搞混了就白折腾。

第一种是文件编码问题。国内老字幕大量使用 GBK 或 GB18030 编码，而 Kodi 默认按 UTF-8 读取，中文就会变成一堆方块或者问号。判断方法很简单：在电脑上用文本编辑器打开这个 srt，如果编辑器提示"检测到 GBK 编码"或者打开后中文是乱的，那就是第一种。处理方法是在 Kodi 里临时切换字符集（设置 → 播放器 → 语言 → 字幕 → 字符集，选中文简体 GBK），或者更彻底的办法，把文件转成 UTF-8。

# 批量把 GBK 字幕转成 UTF-8，先备份 mkdir -p subs_backup for f in *.srt; do cp "$f" "subs_backup/$f" if ! iconv -f UTF-8 -t UTF-8 "$f" > /dev/null 2>&1; then iconv -f GB18030 -t UTF-8 "$f" > "$f.tmp" && mv "$f.tmp" "$f" echo "converted: $f" fi done

第二种是字体缺失。文件编码没问题，但屏幕上显示的是方块，这通常发生在 ASS 字幕上，因为 ASS 指定了具体字体名，而你的播放设备上没有这个字体。安卓电视盒子上尤其常见，字幕里写的是"微软雅黑"，盒子上压根没装。处理方法是在播放器设置里把字幕字体改成"默认"或设备自带的中文字体，或者把字体文件放到 Kodi 的字体目录里。

第三种是界面字体问题，跟字幕无关。表现为 Kodi 的菜单、标题全是方块，但字幕显示正常。这是皮肤字体不含中文字形，需要换皮肤或者装中文字体。这个坑很多人会误判成字幕问题，白折腾半天。

5.2 ASS 样式在 Kodi 里的渲染差异

SRT 是纯文本加时间轴，简单粗暴；ASS 带样式、定位、特效，观感好得多，但也更容易出问题。Kodi 用的是 libass 引擎渲染 ASS，跟主流播放器的实现不完全一致，具体表现有几个。

字体回退策略不同。ASS 里指定的字体找不到时，libass 会回退到一个默认字体，而不同平台的默认字体差别很大，Windows 上可能退到黑体，安卓上可能退到一个不含中文的拉丁字体，中文直接变方块。

定位和边距的百分比算法有差异。ASS 里的MarginL、MarginR、MarginV是像素值，但 Kodi 在缩放时会按屏幕分辨率做换算，4K 屏幕上字幕可能贴到屏幕最下沿或者飘到画面中间。这种情况要么手动改 ASS 的样式行，要么在 Kodi 的字幕设置里调垂直位置。

特效支持不完整。ASS 的绘图指令、卡拉 OK 特效、动态旋转这类东西，libass 支持一部分，Kodi 的版本差异又会让支持范围变化。如果字幕带大量特效，最省事的做法是找该片的 SRT 版本，而不是跟 ASS 死磕。

我的处理原则是：日常看片优先用 SRT，只有遇到排版对观感影响很大的片子（比如多人物对白的复杂场景）才上 ASS，并且提前测一次渲染效果。

5.3 时间轴偏移的手动与批量修正

时间轴偏移的表现是：字幕整体比声音早或晚固定的秒数，从头到尾偏移量一致。这种最好修。播放中用字幕菜单里的"字幕延迟"调节，Kodi 允许以 0.1 秒为步进微调，也能设更大的步进做粗调。调好之后，Kodi 会把偏移量记在这个文件上，下次播放自动应用。

如果是整个库都偏移，那可能是帧率问题。23.976 和 24 帧的片子互相套字幕，两小时的电影能差出好几秒。这种偏移不是线性的固定值，越到后面差得越多，播放器里的延迟调节治不了，只能重新找对应帧率的字幕，或者用工具重采样时间轴。

批量处理的话，我一般用ffmpeg做时间轴缩放：

# 把按 25fps 做的字幕适配到 23.976fps 的片源 ffmpeg -i input.srt -vf "setpts=PTS*23.976/25" -f srt output.srt

命令里的比例是目标帧率除以源帧率，反了就来回倒腾一下。这条命令不改变文本内容，只改时间戳，处理完记得抽查头尾两处，确认没有累积误差。

6. 常见问题排查速查表

6.1 症状对照表

出问题的时候，先按症状定位到层级，再往下查，比盲目重装高效得多。下面这张表是我这几年攒下来的，覆盖了八成以上的实际故障。

表格里最值得多说一句的是"下载提示成功但无字幕"。这个症状下，插件本身大概率是好的，问题出在文件落地环节。Kodi 的提示只看 HTTP 请求是否 200，不看文件是否写入成功。所以一旦遇到，第一件事不是重装插件，是去目标目录看一眼文件到底在不在。

6.2 日志怎么看

Kodi 的日志文件在userdata/kodi.log，安卓盒子上路径是/sdcard/Android/data/org.xbmc.kodi/files/.kodi/temp/kodi.log。默认只记错误级别的信息，排查插件问题需要打开调试日志：设置 → 系统 → 日志 → 启用调试日志。

打开之后复现一次故障，然后去日志里搜插件 ID 关键字。字幕插件的日志通常长这样：[service.subtitles.xxx] Searching for: 片名，后面跟着请求的 URL、HTTP 状态码、返回结果条数。看到HTTP 403说明请求被拒，HTTP 000说明连接根本没建立，返回条数为 0 说明请求通了但没结果，三种情况的处理方向完全不同。

还有一个技巧：日志里如果出现UnicodeDecodeError或者UnicodeEncodeError，几乎可以断定是字幕站点返回的编码跟插件预期的编码不一致，属于插件层面的问题，不是你的配置错。这种情况换一个字幕源或者等插件更新，自己改代码成本很高。

7. 批量补字幕与长期维护的野路子

7.1 用脚本预扫描字幕缺口

片库大到一定程度之后，一部部点开找字幕是不现实的。我的做法是先跑一个本地扫描脚本，把"有视频没字幕"的清单拉出来，然后集中时间批量处理。这个脚本不需要调 Kodi 的任何接口，纯文件系统层面操作，简单可靠。

import os VIDEO_EXT = {'.mkv', '.mp4', '.avi', '.ts', '.m2ts'} SUB_EXT = {'.srt', '.ass', '.ssa', '.vtt'} def scan(root): missing = [] for dirpath, _, files in os.walk(root): names = {os.path.splitext(f)[0] for f in files} videos = {f for f in files if os.path.splitext(f)[1].lower() in VIDEO_EXT} subs = {f for f in files if os.path.splitext(f)[1].lower() in SUB_EXT} for v in videos: stem = os.path.splitext(v)[0] # 只要存在以视频名开头的字幕文件就算有字幕 if not any(s.startswith(stem) and os.path.splitext(s)[1].lower() in SUB_EXT for s in subs): missing.append(os.path.join(dirpath, v)) return missing if __name__ == '__main__': result = scan('/path/to/media') print(f'缺字幕文件 {len(result)} 个') with open('missing_subs.txt', 'w', encoding='utf-8') as fp: fp.write('\n'.join(result))

把结果写到文本文件里，打开一份，按顺序在 Kodi 里过一遍。实测下来，一部两小时的片子从点开到字幕上屏大概十五秒，一百部也就半小时，比想起来才补要高效得多。

7.2 字幕仓库的目录约定

如果片源分散在多个目录，我建议单独建一个字幕仓库目录，用符号链接或者硬链接挂到视频目录下。这么做的好处是字幕文件的版本管理变得可控——你可以定期备份这一个目录，也可以在换设备时整包迁移，不用满盘去找散落的 srt 文件。

目录结构建议按语言分：subs/zh/、subs/en/、subs/zh-en/，每个文件仍然保持"视频全名.语言码.srt"的命名。Linux 下用ln -s建软链，Windows 下用mklink。注意别在 SMB 共享上做这个，软链在 SMB 协议下经常失效，直接复制文件更省心。

7.3 版本升级后的回归检查

Kodi 每次大版本升级，插件生态都会有一波动荡，字幕插件尤其明显，因为它依赖的 API 面比较宽。升级之前，建议先做三件事：导出一份媒体库（设置 → 媒体 → 视频库 → 导出视频库，选择导出独立文件），备份userdata/addon_data目录，记下当前能正常工作的插件版本号。

升级完之后，别急着全库扫描，先拿一部片子做端到端验证：能不能搜到、能不能下载、能不能自动加载。三项都通过再继续用，有任意一项失败就回滚插件版本。我吃过一次亏，主程序升完级没测，直接跑批量子幕，跑了两百多部才发现插件下载的文件全部落在临时目录里，白忙活一晚上。

8. 我在实际使用中攒下的几条经验

装了快三年，换过三套设备，说几条文档里不会写的东西。

第一，别迷信"自动匹配"。插件再聪明也只是字符串比对，它不知道你看的是导演剪辑版还是院线版。真正省时间的做法是在搜索时多看一眼结果条目的版本说明，宁可多花五秒钟，也别下载完发现对不上再重来。

第二，中文字幕的命中率跟片名的英文写法关系极大。我养成了一个习惯：媒体库刮削完先抽查几部的originaltitle字段对不对，不对的手动改。这个字段是插件搜索时最可靠的输入，比任何配置项都重要。

第三，字幕下载目录不要设在系统临时目录。有些插件默认往special://temp/写，这个目录会被系统定期清理，你今天下好的字幕过两周就消失了，而且 Kodi 重启之后不会重新加载，表现为"明明有字幕文件却用不了"。统一设成视频同目录，一劳永逸。

第四，多设备场景下，字幕跟着片源走而不是跟着设备走。我家里三台设备共用一个媒体库，字幕写在片源同目录，任何一台设备打开都能自动加载，不用每台机器单独配一遍插件。这个设计上的小选择，长期省下来的时间相当可观。

第五，遇到搜不到的字幕，先怀疑片名，再怀疑网络，最后才怀疑插件。顺序反了，排查时间会翻好几倍。这个顺序是我踩了无数次坑之后总结出来的，按它走，绝大多数问题五分钟内能定位。