qBittorrent 聚合搜索从零到一：5 分钟装好 search-plugins，一个搜索框搜遍全网资源

qBittorrent 聚合搜索从零到一：5 分钟装好 search-plugins，一个搜索框搜遍全网资源

【免费下载链接】search-pluginsSearch plugins for qBittorrent search feature项目地址: https://gitcode.com/gh_mirrors/se/search-plugins

search-plugins 是 qBittorrent 官方维护的搜索插件合集，内置 EZTV、Pirate Bay、LimeTorrents 等站点插件，配合 Jackett 还能把 qBittorrent 聚合搜索的范围扩展到 500 多个索引站。这篇实操指南不讲空理论，直接带你从安装、配置走到日常使用与排错，让"逐站找资源"变成"一次搜索搞定"。

一个让人想摔键盘的傍晚

先讲一段真实经历。前阵子我想找一部冷门剧的高清版，浏览器标签页一口气开了六七个站点，挨个输入关键词、比对种子数和文件大小、复制磁力链接，再切回 qBittorrent 一个个粘贴添加。折腾快一个小时，才发现其中一个网站其实有 1080p 版本，前面那堆低清资源全白下了。

后来朋友演示了一招：在 qBittorrent 的 Search 标签页敲一个关键词，十几秒内所有站点的结果整整齐齐列在同一个窗口里，种子数、大小、做种人数一目了然，勾选后直接进下载列表。省下的时间用来喝杯茶不香吗？这个体验背后，就是 search-plugins 项目。

不过在动手之前，有一件事必须先弄明白，否则你会踩一个大坑。

动手前先分清：qBittorrent 搜索插件的两代玩法

很多人装上插件没效果，十有八九是版本对不上。qBittorrent 的搜索功能经历过一次代际更替，插件也分成了两套玩法：

说人话就是：4.5.0 之前，qBittorrent 自带一个基于 Python 的搜索引擎，靠一个个.py插件去各个站点"爬页面、抠结果"；4.5.0 之后，官方砍掉了这套原生引擎，改为调用 Torznab 兼容 API——你在 qBittorrent 里填一个索引器地址，它就把查询发给 Jackett 这类服务，再由后者广播到几百个站点。

所以请先看一眼你的版本号，再决定走哪条路线。下面两条路我们都会走一遍。

老版本路线：三步把 .py 插件装进 nova3/engines

如果你的 qBittorrent 还是 4.5.0 之前的版本，那么恭喜，直接安装仓库里的 Python 插件即可。

第一步，拿到插件文件。先克隆仓库：

git clone https://gitcode.com/gh_mirrors/se/search-plugins cd search-plugins/nova3/engines

这个目录里躺着 8 个插件文件，各自负责不同的站点：

第二步，把插件放进引擎目录。各系统的默认位置如下：

• Windows：%LOCALAPPDATA%\qBittorrent\nova3\engines
• Linux：${XDG_DATA_HOME:-$HOME/.local/share}/qBittorrent/nova3/engines
• macOS：~/Library/Application Support/qBittorrent/nova3/engines

也可以不走文件目录，直接在 qBittorrent 里点 Search 标签 → Search plugins… → Install a new one，选本地文件完成安装，效果一样。

第三步，启用并验证。依次点击菜单 View → Search Engine，勾选后主界面会多出 Search 标签页，输入关键词回车，坐等结果即可。

这里有两个提醒。一是环境需要 Python 3.6 以上，2020 年起这个项目已经彻底放弃 Python 2，别再拿老环境去试；二是插件本质是第三方 Python 脚本，装之前建议先打开读一遍，只从可信来源获取，这也是项目 README 里反复强调的安全底线。

进阶玩法：让 Jackett 插件替你搜遍 500+ 站点

装完上面那批插件，你大概能覆盖七八个站点。想更进一步，就得请出仓库里最特别的一个——jackett.py。

它和别的插件不一样，自己不去爬任何网页，而是把搜索请求转交给本机运行的 Jackett 服务。Jackett 再把你的一句话广播给已配置的几百个索引站，把各自的结果统一翻译成标准格式回传。换句话说，站点列表的维护工作全被 Jackett 社区包圆了，你只管搜。

它需要一个独立的配置文件jackett.json，必须和 jackett.py 放在同一个目录。首次运行会自动生成，内容如下：

{ "api_key": "YOUR_API_KEY_HERE", "url": "http://127.0.0.1:9117", "tracker_first": false, "thread_count": 20 }

四个参数各有分工，照着这张表填就行：

如果 API Key 没填就搜索，插件不会静默失败，而是直接在结果里打出一行带错误说明的条目（比如Jackett: api key error!），右键该行打开描述页就能看到完整帮助。另外，如果你身处需要代理的环境，jackett.py 还会自动读取http_proxy、https_proxy环境变量并支持 SOCKS，网络受限时这是救命的功能。

新版路线：5 步配好 Torznab 一站式聚合搜索

如果你的 qBittorrent 是 4.5.0 及以上的新版本，就别再折腾 .py 插件了，直接走 Torznab 路线，体验反而更顺。

第 1 步，装好 Jackett。去官方仓库按系统下载安装，强烈建议装成系统服务，开机自启、自动更新。装完打开 Web 界面（默认地址http://127.0.0.1:9117），把常用的站点一个个 Add indexer 加进去。

第 2 步，在 qBittorrent 里打开搜索功能。点菜单 View → Search Engine，看到下面这个勾选项就对了：

搜索功能默认是关闭的，在 View 菜单里打开后，主界面才会出现 Search 标签页

第 3 步，打开索引器管理窗口。切到 Search 标签页，点击右下角的 Indexers… 按钮：

此时还没配置任何索引器，页面会提示"没有可用的搜索索引"

第 4 步，逐个添加 Torznab 索引器。点 Add…，在弹出的窗口里填三项：Name 随意起个好认的名字；Torznab URL 和 API Key 从 Jackett 的 Web 界面里复制。Jackett 里每个站点都提供一条专属的 Torznab feed 地址，长这样：

Torznab URL 和 API Key 都来自 Jackett Web 界面，逐站复制即可

第 5 步，验证并发起第一次搜索。添加完成后回到索引器列表，右键可以随时启用、编辑或删除某个索引器：

想临时关掉某个反应慢的站点，右键取消勾选 Enabled 即可

然后回到搜索框，输入关键词点 Search，所有已启用索引器的结果会合并展示，还能按种子数范围做二次筛选：

结果页顶部自带筛选器，可以按种子数、文件大小和名称范围缩小范围

老规矩提一句：无论用哪种路线，请只访问你所在地区法律允许的内容，尊重版权，这是玩转所有搜索工具的前提。

日常使用：三个小技巧让搜索结果又快又准

配置完成后，日常使用还有几个值得养成的习惯：

1. 多索引器并行，但别贪多。全勾上虽然一次能搜几百个站，但结果排序会变乱、响应也慢。建议保持 3～5 个主力站点启用，其余按需临时打开。
2. 善用结果筛选器。找热门资源时把最小种子数设为 5 以上，能过滤掉一批"僵尸种"；搜索特定版本（比如系统镜像 ISO）时，再叠加文件大小区间，把精简版和残缺版排除掉。
3. 单站点排障用 Manual search。怀疑某个索引器有问题时，不用在 qBittorrent 里折腾，直接去 Jackett Web 界面的 Manual search 验证这个站点本身通不通：

如果 Jackett 里能搜出结果而 qBittorrent 里没有，问题多半出在配置而不是站点

搜索无结果？按这 4 个方向排查

遇到"搜了个寂寞"的情况别慌，绝大多数问题出在下面四个环节：

1. 版本错位。这是最高发的原因——在 4.5.0+ 上装老 .py 插件，或者在老版本上想直接配 Torznab 索引器。先核对版本，再核对走的哪条路线。
2. 配置抄错。API Key 多打一个字符、URL 末尾多了斜杠、Jackett 服务没启动，都会导致空手而归。检查jackett.json或索引器配置，必要时删除重配。
3. 站点本身失效。网站改版、加了反爬，插件解析逻辑就会失灵。先看 qBittorrent 和 Jackett 的日志，再去仓库拉一次最新代码——社区维护者会持续修复这类问题。
4. 网络受限。地区屏蔽或需要代理时，老版本插件可以配置环境变量走代理，新版本则要确认 Jackett 绑定地址和防火墙规则。另外，如果是远程访问无界面的 qBittorrent，记得把 Jackett 默认的127.0.0.1绑定改成可达的地址。

进阶彩蛋：10 分钟看懂插件是怎么写出来的

折腾完安装，你可能和我一样好奇：这些插件内部长什么样？其实门槛比想象中低得多。

每个插件就是一个 Python 类，实现固定的几个字段和方法即可，以 eztv.py 为参考：

class eztv: name = "EZTV" url = 'https://eztvx.to/' supported_categories = {'all': 'all', 'tv': 'tv'} def search(self, what, cat='all'): # 在这里请求站点、解析 HTML # 用 prettyPrinter 把结果输出给 qBittorrent pass

套路很简单：search()方法负责发出请求并解析页面，把每条结果通过prettyPrinter以统一格式吐出来；download_torrent()负责处理磁力链接或 .torrent 文件。解析部分可以用 Python 标准库的 HTMLParser（eztv.py 就是这么干的），也可以用正则表达式，怎么顺手怎么来。

如果你想认真学，官方有一份详细指南 How-to-write-a-search-plugin.md，而 nova3 目录下的测试与工程化配置也相当完善：先装uv，执行uv sync建好环境，然后just test跑单测、just check做类型检查、just lint查规范、just format统一格式——每个引擎在tests/下都有对应的测试文件，写完插件顺手补个测试，质量就有保障了。

现在轮到你了

两条路线都摆在眼前：老版本用户直接克隆https://gitcode.com/gh_mirrors/se/search-plugins，把nova3/engines里的插件装进引擎目录；新版用户装好 Jackett，在 Search 标签里添加几个 Torznab 索引器。无论哪条路，10 分钟之内你都能拥有属于自己的 qBittorrent 聚合搜索。

回顾一下这篇文章的核心收获：search-plugins 帮你把多站点搜索压缩成一次回车；Jackett 插件或 Torznab 方案能把覆盖面扩展到 500+ 索引站；装完遇到问题，先查版本、再查配置、然后看日志，九成问题都能自己解决。

动手吧，先把仓库 clone 下来，再决定走哪条路线——你的下一个搜索任务，值得更快的打开方式。🚀

【免费下载链接】search-pluginsSearch plugins for qBittorrent search feature项目地址: https://gitcode.com/gh_mirrors/se/search-plugins