GitHub

使用手册

浏览器扩展

Motrix 浏览器扩展可以把网页中的下载发送给本机 Motrix 或远程 Motrix Server，并在扩展里查看进度、管理任务。它还能发现页面已经加载的视频、音频和图片，把支持的流媒体交给 Motrix 下载并合并。

安装 Motrix Extension

Motrix Extension 配合 Motrix 2 使用。Chrome、Microsoft Edge 和 Firefox 从扩展商店安装，macOS Safari 通过 GitHub Releases 单独下载：

需要开发版时，可参阅扩展仓库中的构建与手动加载说明。

macOS 上的 Safari

Safari 扩展目前通过 GitHub Releases 提供预发布版，已签名并通过 Apple 公证，支持 macOS 13 及以上的 Apple 芯片和 Intel Mac。它不是 Mac App Store 版本，也不包含在 Motrix 桌面安装包中。

  1. 打开上方 Safari 下载页面，在对应版本的 Assets 中下载以 safari-macos-universal.zip 结尾的安装包并解压。
  2. 把 Motrix Extension for Safari.app 移入「应用程序」并打开。请保留一份安装副本。
  3. 在 Safari → 设置 → 扩展中启用 Motrix Extension，按需授予使用网站的访问权限。此签名版本无需开启「允许未签名扩展」。
  4. 连接本机时，安装 Motrix 2 的 beta.44 或更新的签名 macOS 版本，手动打开准备使用的 Motrix.app，并完成首次启动流程。该版本起包含 Safari 所需的桌面引导服务；如果 macOS 提示批准后台项目，请在系统设置中批准。
  5. 点击 Safari 工具栏中的扩展，按下文完成配对。从开发版升级时，可能需要重新配对。连接远程 Server 时，请按连接 Motrix Server配置。

Note

Safari 可通过右键链接、手动新建任务或选择页面资源发起下载，暂不支持自动接管浏览器下载；原生通知仍属实验功能。网页资源不可见或无法发送时，先检查该网站的扩展访问权限。

如果 Safari 启动了旧的 Motrix 副本，请重新打开准备使用的已安装 Motrix.app，以更新引导服务注册。仅下载新副本不会更新注册，不需要删除数据库或配对凭据。未签名开发构建无法建立正式分发所需的注册关系。

配置步骤

  1. 安装扩展。 使用上方对应浏览器的链接安装；Safari 先完成前一节的安装与启用。然后手动打开本机的 Motrix 2。阅读首次启动条款，确认同意后继续进入主界面，再开始配对。
  2. 在 Motrix 里放行连接。 设置 → 集成 → 浏览器扩展 里的 「连接浏览器扩展」 默认就是开的。Chrome、Edge 和 Firefox 所需的 Native Messaging host 由 Windows、macOS 安装包和 Linux DEB／RPM 包自动注册。Safari 使用前述桌面引导服务；Flatpak 需要按下文说明单独安装。
  3. 发起配对。 打开扩展并点击 「配对」。桌面版会自动发现这台电脑上的 Motrix；如果发现多个实例，先选择正确的一个。
  4. 输入配对码。 Motrix 会显示浏览器、扩展身份和八位配对码。确认请求是你发起的，再把该配对码输入扩展。若请求可疑，直接在 Motrix 中拒绝；不操作的话请求会自动过期。

Note

从 Chrome、Edge 或 Firefox 商店安装，无需开启开发者模式，也无需手动添加受信任的扩展 ID。按上述步骤完成配对即可。

Note

**Flatpak：**配对前，先在宿主系统安装对应版本的 Native Host companion，.flatpak 主程序无法代为注册。安装命令、浏览器发行包的支持范围与排查方法，见 Flatpak 安装与浏览器集成。

Note

Motrix AppImage 安装包目前不支持本机浏览器集成。在 Linux 上需要本机配对时，请使用 DEB 或 RPM 安装包。

批准过的浏览器会出现在 「已连接的扩展」 列表里，带 「上次活跃」 时间和 「断开」 按钮——想强制重新配对，断开即可。

本机配对失败怎么办

先手动打开 Motrix，完成首次启动流程。如果仍停留在条款页面，请阅读并在同意后确认，进入主界面后再回到扩展重试。Motrix 会在这一步完成后初始化服务，因此仅安装 App 还不足以完成本机配对。

如果通过 Homebrew 安装 Motrix 后仍无法配对，可以尝试改用官方 GitHub Releases 中的 Motrix 2 安装包。打开新安装的 App，完成首次启动流程，再重试配对。

Note

有用户反馈，Homebrew 安装后无法配对，改从 Releases 安装并确认首次启动条款后恢复正常。这是一条用户验证过的排查办法，尚不能据此确定是安装来源还是未完成首次启动流程导致了失败。

仍然失败时，点击扩展连接报错框中的**「诊断」**，用诊断报告右上角的小复制按钮复制信息，并在反馈问题时附上。开发版或未打包扩展还需检查：当前扩展 ID 是否已加入 Motrix 的受信任扩展及 Native Host 白名单。Flatpak companion 只注册内置的官方扩展 ID，在 Motrix 中添加自定义 ID 不会更新其浏览器 manifest。

连接 Motrix Server

远程 Server 不使用桌面版的 native messaging 发现链路。管理员需要先把 Server 升级到支持远程 MBP1 的版本，并显式开启远程浏览器扩展路由。Server 启动日志会打印扩展应填写的准确 WS/WSS 地址；在扩展的 Server 设置中添加该地址并发起配对，Motrix Web 界面会显示八位配对码，把它输入扩展即可完成认证。

Important

旧 beta Server 的远程 URL token 和旧配对记录不能迁移到 MBP1。升级 Server 与扩展后，请删除旧 Server 配置并重新配对。WS 可以用于可信局域网，业务内容仍由 MBP1 加密，但连接元数据和首次服务器身份缺少 TLS 保护；公网或不可信网络请使用 WSS。

配对后，还需在扩展的设置 → 集成中为该 Server 开启**「远程下载」**。Cookie 和页面请求标头默认不向远程 Server 发送，只有下载需要时才为该 Server 单独授权。

参数、NAS 上的 WS/HTTP 风险确认和 WSS 反向代理路径，参见 Motrix 服务器版（Docker）。

能发送什么

  • 普通文件——扩展可携带下载所需的请求头和 Cookie；是否发送取决于下载方式及你授予的权限。需要登录或使用临时链接的下载仍可能因会话过期而失败。
  • 流媒体视频（HLS/DASH）——Motrix 先下载分片，再用 FFmpeg 把音视频合成一个文件。FFmpeg 在 设置 → 集成 → 媒体工具 里管理（用内置副本、自定义路径还是系统安装，卡片上写得明明白白）。
  • 磁力链接——直接进入种子流程。

手抖点了两次发送也没关系——同一个下载的重复请求会被自动忽略。

移交失败了怎么办

扩展会把 Motrix 的真实原因用大白话告诉你：

提示含义
「直播流暂不支持下载」这是正在进行的直播，不是已完成的文件
「受 DRM 保护的内容无法下载」内容被 DRM 加密——Motrix 不会绕过它
「会话已过期 — 请在浏览器中刷新页面后重试」你在网站上的登录在移交途中失效了
「ffmpeg 合成阶段失败」最后的合并一步失败——去 「媒体工具」 查看 FFmpeg 状态
「续传失败；请重新开始下载」服务器拒绝续传残留的半个文件

受信任的扩展（进阶）

在 「受信任的扩展」 里可以授权第三方扩展与 Motrix 通信：点 「添加扩展」，粘贴扩展 ID，选好浏览器（Chrome/Edge 或 Firefox）。设置界面自己也说了：通常不需要使用——官方扩展开箱即受信任。

Note

桌面版与 Server 版都支持官方浏览器扩展，但信任作用域不同：桌面版通过本机 native messaging 配对，Server 版通过显式开启的 MDXP over MBP1 远程配对。两边的凭据不能互换。