CrossWatch 路径匹配（Path Matching）详解：ID 对不上时，文件路径如何救场-平芜编程栈

【免费下载链接】CrossWatch

Synchronize your data across media servers, media agents and trackers. Keep your movies and shows in sync, no matter where you watch.

项目地址：https://gitcode.com/gh_mirrors/cr/CrossWatch

点击查看免费下载

当你的媒体同时存在于 Plex、Jellyfin、Emby 等多台服务器时，CrossWatch 路径匹配（Path Matching）提供了 ID 之外的第二重保险：只要两边文件路径的尾部结构一致，CrossWatch 就能把它们识别为同一部影片或同一集剧集，从而让观影历史、评分和播放进度照常同步。本文面向新手，完整讲解这项功能何时该开、如何匹配、以及哪些情况会匹配失败。

为什么 ID 匹配不够用？

不同媒体服务器会为同一部电影分配各自不同的内部 ID；即使使用外部 ID（IMDb、TMDB 等），也常常出现一边有、一边缺的情况。CrossWatch 的常规流程是：

优先用 ID 匹配（Strict ID matching 开启时只会用 ID）；
ID 无法解析时，才轮到本文的主角——按文件路径兜底匹配。

典型场景：你把Alien (1979)从 Linux NAS 迁移到 Windows 媒体服务器，两边路径完全不同盘符和分隔符，但只要尾部目录结构一致，就能对上：

/mnt/media/movies/Alien (1979)/Alien.mkv D:\Movies\Alien (1979)\Alien.mkv

官方说明文档见 docs/path-matching.md。

如何开启“Match by file path”？

该选项位于配对（Pair）配置中，默认关闭：

打开对应 pair →General → Matching→ 勾选Match by file path

开启前请先确认你的组合是否受支持：

支持情况	说明
✅ 支持	Plex、Jellyfin、Emby 两两配对（含同一服务器的不同实例）
❌ 不支持	Kodi 目前暂不支持此选项

勾选后，该选项对双向 pair 的两个方向同时生效，且与 Strict ID matching 可以叠加——它会允许路径兜底，但不会开启按标题搜索，匹配逻辑依然是保守的。UI 开关实现位于 assets/js/modals/pair-config/index.js。

路径匹配到底怎么“对”？

核心逻辑在 cw_platform/path_matching.py 中，规则可以概括为：

电影：比较路径的最后 2 段（影片文件夹 + 文件名）
剧集：比较最后 3 段 + 季数 + 集数（文件夹/剧集文件夹/文件名 + SxxExx）
分隔符（\与/）和大小写会先做归一化，所以 Linux 和 Windows 路径可以互认
带显式分集编号的多部分电影（Part 1 / Part 2）会被区分开，不会互相混淆
整个过程不读取文件内容，纯粹做字符串索引比对

匹配成功的日志会记录为path_match（reason 文案为 “Matched by file path”），并附带resolution_method=file_path，方便你在事件日志中确认它确实走了路径兜底。标签定义见 cw_platform/reason_labels.py，同步侧对接逻辑见 providers/sync/_path_matching.py。

支持什么、不支持什么？

数据类别	是否支持
🎬 电影 / 剧集观看历史	✅
⭐ 评分	✅
📈 播放进度（Playback Progress）	✅
👀 追剧列表（Watchlist）、播放列表、收藏集	❌
📡 Trakt、SIMKL 等 Tracker 服务	❌

也就是说，路径匹配是媒体服务器之间的兜底手段，不会延伸到 Tracker 或列表类数据上。追剧列表页面例如

哪些情况会匹配失败？

CrossWatch 要求恰好命中一个目标条目，否则宁缺毋滥（实现见 cw_platform/path_matching.py 的PathIndex.resolve）：

日志 reason	含义
`path_not_found`	目标库里没有路径尾部一致的条目
`path_ambiguous`	命中了多个条目（路径重复），为避免同步错数据而跳过
`path_id_conflict`	路径虽然一致，但外部 ID 互相冲突，同样跳过

另外还有三种“天然对不上”的情况：

两边文件名不同（比如一个叫Alien.mkv，另一个叫Alien.1979.1080p.mkv）
尾部文件夹结构不同（多套了一层目录或改名）
剧集季集编号不同（一边 S01E01，另一边用别的编号体系）

这些被跳过的条目都会写入日志，便于你针对性地手动修正命名。

性能影响与目录缓存

需要开启前知道的一点：路径兜底可能需要完整读取目标库的元数据目录（包括未观看的条目），大库首次同步会明显变慢。

为此 CrossWatch 把目录缓存在本地 SQLite 中，并在同一服务器、同一凭据、同一选库范围的 pair 和特性之间复用，避免反复全量拉取：

目录超过24 小时或检测到服务器端内容变更信号 → 整体刷新
服务器无法提供可信的变更信号时 → 缓存有效期缩短为5 分钟
单个适配器内的检查结果最多缓存90 秒
7 天未被使用的目录会被自动清理

缓存策略的测试覆盖见 tests/test_path_catalog_cache.py，匹配规则本身的单测见 tests/test_path_matching.py。另外在Maintenance → Retry provider items中还可以主动清空已保存的路径目录缓存并重建。

小结

🎯 一句话总结：ID 优先、路径兜底、严格到宁可跳过。如果你的 pair 是 Plex/Jellyfin/Emby 组合、且两边目录命名习惯一致，那么打开 General → Matching 下的Match by file path，就能在 ID 缺失时自动救回大量本会丢失的历史、评分和进度同步。记得开启后观察一次事件日志，确认path_match按预期出现即可。