qBittorrent搜索插件上手全记录：从首次配置到把数百个站点装进一个搜索框

qBittorrent搜索插件上手全记录：从首次配置到把数百个站点装进一个搜索框

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

你是否也经历过这样的场景：想找一部老电影的高清资源，先打开浏览器，在五六个种子网站之间来回切换，反复输入同一段关键词，再手动对比哪个版本种子多、文件大、更新时间新，最后复制磁力链接回到下载器里慢慢添加任务。如果是这样，那么qBittorrent搜索插件正是为你准备的东西。它是一个专为 qBittorrent 搜索功能设计的开源插件集合，把"多站逐个找资源"压缩成"一次搜索看全部"。下面这份上手全记录，记录了我在 qBittorrent 里从零配置到顺畅使用这些插件的完整过程，希望能帮你少走几步弯路。

起因：我的下载流程为什么慢得让人抓狂

先说说我原来的工作流。晚上想看一部剧，我得先想清楚"去哪个网站搜"。EZTV 适合剧集、Pirate Bay 覆盖面广、LimeTorrents 综合性强……每个站点各有擅长，但也意味着我要记住每个站点的操作习惯。搜索出来的结果格式还不统一，有的显示做种数，有的只给个下载链接，比来比去非常费神。

后来我意识到，问题的根源不是"哪个网站好"，而是"工具太散"。我需要一个入口，把所有站点统一起来。qBittorrent 搜索插件解决的正是这个问题——它作为 Python 脚本挂在 qBittorrent 的搜索功能下，由客户端统一调度、统一格式输出、统一触发下载。

第一次尝试：找到那扇隐藏的搜索入口

安装插件之前，得先确认你用的是 qBittorrent 3.1.10 或更高版本（推荐 4.6 以上），并且已经安装 Python 3.6+ 环境。接下来有一个容易忽略的步骤：qBittorrent 的搜索功能默认是隐藏的，需要手动打开。

在主窗口顶部菜单栏点击View（查看），在下拉菜单里勾选Search Engine（搜索引擎），操作就算完成一半了。此时窗口会多出一个Search（搜索）标签页。

小贴士：这一步只在首次使用时需要。以后每次启动 qBittorrent，搜索标签页都会默认存在。

我第一次走到这里时有点懵——标签页有了，可搜索框里敲什么都是"未配置索引"。原来还差最后一步：把插件"喂"给 qBittorrent。

安装第一枚插件：比想象中简单

打开 Search 标签页，点击右下角的Indexers...按钮，进入索引器管理窗口。

qBittorrent 的插件本质上是放在特定目录下的.py文件。获取方式很简单：克隆项目仓库后，nova3/engines/目录里就是现成的插件源码，例如eztv.py、piratebay.py、torrentscsv.py等。安装有两条路可选：

方式一：本地文件安装（适合单个插件）

1. 把目标.py文件保存到电脑本地
2. 在索引器管理窗口点击Add...，选择"本地文件"
3. 选中刚才保存的文件，若提示"成功安装"即完成

方式二：整目录拷贝（适合一次装齐）

直接把nova3/engines/目录复制到 qBittorrent 的插件搜索目录（不同系统的默认路径见下表）：

装好后回到索引器管理窗口，勾选你希望启用的站点，就能在搜索框里输入关键词、选择分类并点下 Search 按钮了。从"想要插件"到"搜出结果"，全程不过几分钟。

进阶玩法：用 Jackett 插件把数百个站点统一起来

单靠内置的十几个插件，对大多数日常需求已经够用。但如果你追求更广的覆盖范围，就绕不开Jackett 插件配置这个话题了。

Jackett 本身是一个独立的代理服务，它专门负责把"搜索请求"翻译成各家种子站点的私有格式，再把结果回传。qBittorrent 只需对接 Jackett 一个地址，就能触达它背后数百个索引器。相比一个个维护插件，这套方案的省心程度是质的飞跃：

配置过程的关键是生成一个jackett.json配置文件，与jackett.py放在同一目录。内容大致如下：

{ "api_key": "你的API密钥", "url": "http://127.0.0.1:9117", "tracker_first": false, "thread_count": 20 }

四个参数各司其职：api_key对应 Jackett 界面右上角显示的那串密钥；url是 Jackett 服务地址（默认本地 9117 端口）；tracker_first决定是否把站点名放在每条结果开头；thread_count控制并发请求数，如果你希望减少同时发出的请求，把它调小即可。

如果文件不存在，插件首次运行会自动生成默认模板，你只需填入真实密钥。接下来在 qBittorrent 的索引器管理窗口点击Add...，填写 Torznab 地址与 API 密钥，就能看到类似下图的配置界面：

注意：如果 qBittorrent 和 Jackett 不在同一台机器上，记得把url从回环地址改成可路由的地址，并做好防火墙放行，同时尽量避免把 Jackett 直接暴露到公网。

使用心得：让搜索又快又准的几个小习惯

插件跑通之后，我总结出几个明显提升体验的习惯，分享给你：

习惯一：善用索引器启停。在索引器列表上右键，可以随时启用或禁用某个站点。某些站响应慢、结果质量低，直接禁用反而让整体搜索更快。

习惯二：结果列表不等于终点。搜索结果里，做种数（seeds）是最直接的信号，建议把它作为排序第一参考；文件大小则能帮你快速剔除明显不对的资源——比如搜索完整版系统镜像却跳出来一个 300MB 的文件，果断跳过。

习惯三：关键词要带"版本感"。找软件时带上版本号（如软件名 2024），找剧集时带上季数（如剧名 S05），命中率会高很多。模糊搜索留给"想不起来确切名字"的场景。

习惯四：降低并发，稳住响应。如果同时搜索太多站点导致卡顿，调低thread_count或减少启用的索引器数量，往往立竿见影。

好奇者的福利：插件背后其实是一套清晰的约定

如果你对"插件是怎么工作的"产生好奇，可以看看nova3/engines/里的源码。每个插件本质上就是一个 Python 类，核心约定非常简洁：类名与文件名必须一致，类里要有name、url、supported_categories三个静态属性，再实现一个search()方法。搜索结果通过prettyPrinter输出，qBittorrent 就能识别。

class example_search_engine: name = "示例搜索引擎" url = 'https://example.com/' supported_categories = {'all': 'all', 'tv': 'tv'} def search(self, what, cat='all'): # 抓取网页、解析结果，然后调用 prettyPrinter 输出 pass

项目对插件的质量要求也很明确：只用 Python 标准库、不向 stdout 打印调试信息（避免污染结果流）、尽量处理异常情况。仓库里还给开发者准备了完善的工具链——用just test跑测试、just check做类型检查、just format统一格式，写完新插件后按这套流程走一遍，质量就有基本保障。

想深挖的同学，官方 wiki 里的How to write a search plugin文档是很好的起点，里面连输出格式都给出了完整示例。

遇到问题的自救手册

使用过程中踩过的坑，也一并记录下来：

Q1：安装插件提示失败？先确认文件名与类名一致、文件确实是.py而非压缩包；再检查 Python 版本是否符合要求（2020 年 8 月起项目已移除 Python 2 支持，请使用 Python 3）。

Q2：某个站点总是搜不出结果？大概率是站点改版或加了反爬。可以试试稍后重试，或参考项目仓库里其他贡献者提交的修复版本；长期无解就禁用该索引器，改用 Jackett 里的同站替代。

Q3：Jackett 插件提示 API key 错误？打开jackett.json，确认api_key不是占位符YOUR_API_KEY_HERE，并与 Jackett 界面显示的密钥逐字符核对。注意配置文件更新后无需重启 qBittorrent，插件每次搜索都会重新读取。

Q4：搜索很慢怎么办？依次检查：并发数是否过高、是否有站点响应超时拖后腿（可单独禁用测试）、网络是否需要代理。插件对 HTTP/SOCKS 代理环境变量是支持的。

写在最后

回头再看这段从"浏览器多站来回切"到"一个搜索框通吃全部"的经历，最深的感受是：qBittorrent 搜索插件没有改变下载本身，它改变的是资源发现的效率。内置插件覆盖日常所需，Jackett 接入则把边界拓展到数百个站点，而模块化的插件设计又让每个人都能为它添砖加瓦。

如果你也想试试，建议按这个顺序行动：先确认 qBittorrent 版本与 Python 环境，克隆https://gitcode.com/gh_mirrors/se/search-plugins拿到插件源码，装上一两个最常用的站点先跑通流程，再按需决定是否引入 Jackett。慢慢你就会发现，找资源这件事，原来可以这么顺手。祝下载愉快！

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