Flatpak

Motrix 官方 Flatpak 的应用 ID 为 app.motrix.native。本指南介绍 GitHub Releases 提供的 .flatpak 单文件包，以及用于浏览器集成的可选 Native Messaging host。

选择下载文件

打开一个 Motrix 2 Release，查看 Assets 列表。主程序与浏览器 companion 分别下载：

`uname -m`	主程序包	Native Host companion
`x86_64`	`Motrix-VERSION-x86_64.flatpak`	`Motrix-Native-Host-VERSION-linux-x64.tar.gz`
`aarch64`	`Motrix-VERSION-aarch64.flatpak`	`Motrix-Native-Host-VERSION-linux-arm64.tar.gz`

需要使用浏览器扩展时，请从同一个 Release 下载这两个文件。直接在 Motrix 中添加下载任务不需要 companion。VERSION 是版本号占位符，不含开头的 v，执行命令前请替换为下载文件名中的实际版本号。

Note

如果某个 Release 只有 Motrix-Native-Host-…tar.gz，说明它没有提供 Flatpak 主程序，请选择同时包含 .flatpak 产物的 Release。Flathub 上的 net.agalwood.Motrix 是旧版 Motrix，不会升级为 app.motrix.native。

下文命令以 x86_64／x64 文件名为例。ARM64 用户请分别替换为 aarch64／arm64。

安装主程序

尚未安装 Flatpak 时，先通过发行版的包管理器安装，具体参见 Flatpak 发行版安装指南。本文使用用户级安装（--user），以下命令均以当前桌面用户执行，无需 sudo。

添加 Flathub remote 以获取共享 runtime，然后安装下载的主程序包：

flatpak remote-add --user --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo
flatpak install --user --or-update ./Motrix-VERSION-x86_64.flatpak
flatpak info --user app.motrix.native
flatpak run app.motrix.native

Flatpak 会在安装时解析所需的 runtime。这里的 Flathub remote 用于提供依赖，Motrix 主程序来自本地单文件包，不会因此订阅 Motrix 的更新仓库。

Beta 版本使用 beta 分支，正式版本使用 stable 分支，可通过 flatpak info 查看。使用浏览器 companion 时，请只保留一个 Motrix 分支，并避免在用户级与系统级安装中重复安装同一个应用，以便浏览器启动预期的实例。

首次启动时，先完成 Motrix 的语言选择和使用声明流程，再进行浏览器配对。

文件与权限

沙箱默认允许访问 XDG 下载目录。需要使用其他位置时，在 Motrix 的目录选择器中通过桌面 portal 授权。如果目录选择器无法正常工作，请检查发行版是否安装了 xdg-desktop-portal 以及适配当前桌面环境的 portal backend。

Flatpak 版 Motrix 的配置与应用数据位于 ~/.var/app/app.motrix.native/。DEB、RPM、AppImage 或旧版 Flatpak 中的设置与任务不会自动迁移。下载到该目录之外的文件仍保存在你选择的目标位置。

浏览器集成

浏览器在宿主系统上启动 Native Messaging host，而 Motrix 运行在 Flatpak 沙箱内。companion 可执行文件 motrix-flatpak-native-host 负责连接两者。主程序已包含沙箱内的 broker；你需要另外安装 companion，并为当前用户注册。

支持的浏览器

安装器为宿主系统上安装的 Chrome、Chromium、Microsoft Edge 和 Firefox 写入 Native Messaging manifest。请配合官方 Motrix Extension 使用。

通过 Flatpak 或 Snap 安装的浏览器还有自己的沙箱，其发行包可能需要单独支持的 Native Messaging proxy。仅安装 Motrix companion 不能保证这类浏览器连通。若扩展找不到 host，请查阅对应浏览器发行包的文档。

安装 Native Messaging host

安装 Motrix 后，将对应的 companion 压缩包解压到当前用户拥有的目录，执行安装器，无需 sudo：

tar -xzf Motrix-Native-Host-VERSION-linux-x64.tar.gz
cd Motrix-Native-Host-VERSION-linux-x64
./motrix-flatpak-native-host install
./motrix-flatpak-native-host status

安装器会复制可执行文件，并将浏览器 manifest 写入用户级目录。使用默认 XDG 路径时，可执行文件位于 ~/.local/share/motrix/native-messaging/motrix-flatpak-native-host，配置位于 ~/.config/motrix/native-messaging/flatpak-companion.json。如果设置了 XDG_DATA_HOME 或 XDG_CONFIG_HOME，则使用对应路径。安装成功后可以删除解压目录。

安装器默认使用 /usr/bin/flatpak。如果发行版将 Flatpak 安装在其他位置，请传入其绝对路径：

./motrix-flatpak-native-host install --flatpak-bin /absolute/path/to/flatpak

打开 Motrix，启用设置 → 集成 → 浏览器扩展 → 用浏览器扩展发送下载到 Motrix，再按配对指南操作。已有 companion 安装需要更新时，请使用下文的升级命令。

配对说明

companion 目前只注册 Motrix 内置的官方扩展 ID。在 Motrix 中添加自定义或未打包扩展的 ID，不会同步修改 companion 的浏览器 manifest。

Firefox 首次配对时，扩展身份可能显示为未验证。这是因为 Flatpak companion 目前不提供 Native Messaging 身份凭证（nmTicket）。确认请求由自己发起后，输入 Motrix 显示的配对码即可继续。身份标签本身不代表连接失败。

扩展无法连接时

执行 flatpak info --user app.motrix.native 检查安装，再通过 flatpak run app.motrix.native 手动启动。完成首次启动流程，并确认浏览器集成已启用。
检查已安装的 companion：
```
"${XDG_DATA_HOME:-$HOME/.local/share}/motrix/native-messaging/motrix-flatpak-native-host" status
```
installed 表示 companion 的配置与 manifest 检查通过，不代表浏览器已经连接。命令不存在时，先安装 companion；若有报错，请根据输出检查安装路径或配置。
确认浏览器安装在宿主系统上，或其沙箱发行包支持相应的 Native Messaging proxy。重启浏览器后再次配对。
仍然失败时，使用扩展连接报错框中的**「诊断」**功能。反馈问题时附上诊断报告、发行版、浏览器安装来源、Motrix 版本和 companion 的 status 输出。

安装器会拒绝安装路径中的符号链接、异常的属主，以及允许组用户或其他用户写入的目录。请使用与浏览器相同的用户账户运行，并检查报错指向的路径，不要通过放宽写权限解决此类错误。

升级

退出 Motrix，下载相同架构、相同分支的新版本 .flatpak，覆盖安装：

flatpak install --user --or-update ./Motrix-VERSION-x86_64.flatpak

这些单文件包没有配置 Motrix 更新 remote。flatpak update --user 可以从 Flathub 更新 runtime，但不会在 GitHub 上查找新的 Motrix 单文件包。主程序需要逐次下载并安装新包，不要依赖 Motrix 内置的更新功能更新此安装。

如果使用浏览器集成，同时下载并解压新 Release 中的 companion，在新解压目录中执行：

./motrix-flatpak-native-host install --force
./motrix-flatpak-native-host status

--force 会替换现有 companion 安装与配置。使用非标准 Flatpak 路径时，需要再次传入 --flatpak-bin /absolute/path/to/flatpak。更新 .flatpak 不会更新宿主系统上的 companion。

卸载或切换安装包格式

如果安装过 companion，先删除其注册，再卸载主程序：

"${XDG_DATA_HOME:-$HOME/.local/share}/motrix/native-messaging/motrix-flatpak-native-host" uninstall
flatpak uninstall --user app.motrix.native

companion 的卸载命令会删除其可执行文件、配置和所管理的浏览器 manifest。Flatpak 默认保留应用数据；如果也要删除应用保存的数据，再为 Flatpak 卸载命令添加 --delete-data。

若要将浏览器集成切换到 DEB、RPM 或 Snap 版 Motrix，请先卸载 Flatpak companion。它在安装期间负责管理 Motrix 共用的浏览器 manifest，其他安装包格式的 Motrix 不会覆盖这些文件。

选择下载文件#

安装主程序#

文件与权限#

浏览器集成#

支持的浏览器#

安装 Native Messaging host#

配对说明#

扩展无法连接时#

升级#

卸载或切换安装包格式#