qBittorrent / 安装与平台
安装 qBittorrent：官方渠道、平台差异与无界面构建
它有两个构建目标：带图形界面与无界面（qbittorrent-nox）。桌面用户用前者，NAS/服务器用后者。源码编译有明确的依赖下限——官方文档写得很具体：Qt 6.6.0–6.x、libtorrent-rasterbar 1.2.19–1.2.x 或 2.0.10–2.0.x、OpenSSL ≥3.0.2、Boost ≥1.76、CMake ≥3.16。安装包只从官方渠道取并校验，这一页也说明为什么。
三条安装路线怎么选
官方项目站点是 qbittorrent.org；仓库里的 INSTALL 主要讲源码编译。三条路线各有取舍。
| 路线 | 怎么做 | 优点 | 代价 | 适合谁 |
|---|---|---|---|---|
| ① 官方发布物 | 从官方项目站点/官方仓库 Releases 取对应平台安装包 | 官方构建、有 PGP 签名可比对 | 需要自己跟进新版本 | Windows / macOS 桌面用户 |
| ② 发行版仓库 | 用系统包管理器安装（如发行版自带的包） | 升级跟着系统走，依赖自动处理 | 版本通常滞后于官方最新稳定版 | Linux 桌面与服务器 |
| ③ 源码编译 | 按 INSTALL：cmake 配置 → 构建 → 安装 | 可控制版本与构建选项（含 nox） | 要满足依赖下限、耗时 | NAS、要特定构建、要自己出包 |
平台差异：Windows / macOS / Linux 各注意什么
同一份代码，三个平台的注意事项并不一样。
| 平台 | 安装方式 | 要特别注意 | 常见问题 |
|---|---|---|---|
| Windows | 官方安装包（有 PGP 签名的构建） | 安装包来源必须可验证；不要用「绿色版/破解版」 | 防火墙首次弹窗要允许；被安全软件拦截时先核对来源再放行 |
| macOS | 官方发布的磁盘影像 | 未签名的第三方包会触发系统拦截提示 | 权限与磁盘访问授权；从第三方站取包更容易踩 Gatekeeper |
| Linux 桌面 | 发行版仓库或用源码编译 | Qt 版本要与官方下限（6.6+）匹配 | 发行版仓库版本偏旧时，功能与安全修复会滞后 |
| Linux / NAS 无界面 | -DGUI=OFF 编译得到 qbittorrent-nox | 只能通过 Web UI/API 操作，务必先做访问控制 | nox 启动后要显式指定 Web UI 端口与账号 |
| 容器环境 | 以 nox 为基础自行构建镜像 | 数据卷要挂出来，否则重启丢配置 | 镜像来源属于第三方分发，需自行审计 |
源码编译：依赖要求与命令
下面全部来自仓库 INSTALL 原文。官方特别提示：依赖版本号会定期上抬，用更老的版本能编过也不提供支持。
装齐依赖（以下为官方下限）
Boost ≥1.76；libtorrent-rasterbar 1.2.19–1.2.x 或 2.0.10–2.0.x；OpenSSL ≥3.0.2；Qt 6.6.0–6.x；zlib ≥1.2.11；CMake ≥3.16（仅编译期需要）；Python ≥3.13.0（可选，仅内置搜索引擎使用）。
注意 libtorrent 的重名陷阱
官方文档专门提醒：另一个库（rTorrent 用的那个）名字很像，装错会在链接或运行阶段出问题。取包时认准 libtorrent-rasterbar。
配置（图形界面版）
cmake -B build -DCMAKE_BUILD_TYPE=Release。预期：配置阶段无缺依赖报错。构建与安装
cmake --build build然后cmake --install build。预期：安装完成后可直接运行。无界面版（NAS / 服务器）
同上，但配置时加开关：
cmake -B build -DCMAKE_BUILD_TYPE=Release -DGUI=OFF，产物是qbittorrent-nox。预期：启动后无图形界面，通过 Web UI 访问。
wiki.qbittorrent.org）有独立的「Compilation」章节，覆盖更多发行版与选项；INSTALL 只是入口。报构建问题前官方建议先查 wiki 与论坛。装完先做哪些检查
安装完成不等于可用，这三步能避免后面大量无效排查。
| 步骤 | 目的 | 怎么做 | 不做的后果 |
|---|---|---|---|
| ① 核对来源与签名 | 确认安装包来自官方发布流程 | 用官方公布的校验值 / PGP 公钥验证（见安全检查页） | 可能装上被二次打包的版本 |
| ② 确认监听端口 | BT 需要别人能主动连你 | 在客户端里看当前监听端口，并在防火墙放行 | 表现为「能下载但极慢、几乎不上传」 |
| ③ 设定下载目录与限速 | 避免把系统盘写满、避免占满带宽 | 下载/完成目录分开；按需设限速与时段 | 磁盘打满会导致任务失败甚至系统异常 |
| ④ 决定要不要开 Web UI | 远程管理的前提 | 只在需要时开启，并先设强密码 + 限制来源 | 裸奔在公网会被扫描到，见WebUI 与 API |
| ⑤ 检查版本是否最新稳定版 | 获得安全修复 | 与官方最新稳定版号比对 | 官方只修最新稳定分支，老版本漏洞不修 |
升级与数据位置：别把配置和任务弄丢
BT 客户端的「数据」有两类：配置文件和任务清单，它们和下载内容不在一处。
| 类型 | 是什么 | 升级/迁移时要做什么 | 注意点 |
|---|---|---|---|
| 配置文件 | 客户端的全部设置 | 先备份再升级 | 容器部署时必须挂载，否则重建即丢 |
| 任务清单（.torrent 与状态数据） | 每个任务的元数据与进度 | 一并备份 | qBittorrent 新版提供 .torrent 备份相关设置，可在 Changelog 中查到 |
| 已下载的数据 | 你指定的下载目录 | 保持路径不变或同步改设置 | 路径变了必须重新校验或重新指定位置 |
| 日志 | 排错依据 | 出问题前先保留一份 | 不要只贴截图，日志文本更有用 |
CONTRIBUTING.md 要求 issue 一律用英文，并且提交前必须自己先做排查（官方列出的「不是 bug 报告」的情形包括：可从 wiki/论坛解决的用法问题）。另外仓库 AGENTS.md 明确不鼓励 AI 代提交 issue/PR——本站不代任何用户提交。安装与平台常见问题
命令与依赖版本以官方 INSTALL / 官方站点为准；本站未实机编译验证。
官方发布页面是哪个？
官方项目站点是 qbittorrent.org，源码在 github.com/qbittorrent/qBittorrent，文档 wiki、求助论坛、bug 跟踪都在 *.qbittorrent.org 下。搜索引擎里能搜到很多名字里带 qbittorrent 的中文站，那些不是官方站点——本站不把它们称为官方站点，也不推荐从那里取安装包。
编译时提示找不到 libtorrent 怎么办？
先确认装的是 libtorrent-rasterbar，不是同名的另一个库——官方 INSTALL 专门写了这条提醒，因为 rTorrent 用的那个库名字很像。其次核对版本是否落在官方区间：1.2.19–1.2.x 或 2.0.10–2.0.x。版本低于下限虽然有时能编过，但官方明确不为这种组合提供支持。
为什么我的 Qt 版本不行？
官方要求 Qt 6.6.0–6.x。老发行版自带的 Qt 5 或较旧的 Qt 6 都不在支持范围内。这也是「用系统仓库安装更省事」的代价之一：版本会滞后，而官方只维护最新稳定分支的安全修复。
nox 版怎么启动和访问？
它没有图形界面，启动后通过 Web UI 访问。具体端口、账号密码的配置项以你所用版本的官方文档与界面为准；务必在开放远程访问前先设强密码并限制访问来源，相关风险见WebUI 与 API。
能装在路由器上吗？
取决于设备架构与资源。qBittorrent 是 C++ 程序且依赖 Qt/libtorrent，不是所有嵌入式设备都提供这些依赖。可行与否请以你的设备固件与官方构建文档为准；本站不推荐具体固件或第三方包。
安装包被杀毒软件报了，是病毒吗？
不能只看报毒结果下结论，也不能反过来直接忽略。正确顺序：①确认包来自官方渠道；②按官方方式验证签名/校验值；③核对文件大小与官方发布记录；④仍不放心就在隔离环境里装。本站不承诺任何文件「绝对安全」——这类承诺本身就是不可验证的。
升级前要不要备份？
要。备份配置文件与任务清单（.torrent 及状态数据）。大版本升级曾涉及数据迁移（5.2.x 的发布说明里就有「修复潜在的错误迁移流程」这类条目），备份是唯一能兜住迁移异常的手段。