今天在 GitHub Trending 上看到一个值得关注的项目：agalwood/Motrix。这是一款经典的「干净又全能」的桌面下载管理器，而它正在进行一次彻底的架构重生——v2（Turbo）用现代前端技术栈从零重写，并把「下载核心」与「界面」彻底解耦。

一、项目概述

Motrix 是一款支持 HTTP、FTP、BitTorrent、磁力链接等多种协议的桌面下载管理器，主打「功能齐全但依然简洁好用」。它最早以 aria2 封装 + 清爽 UI 走红，如今 Star 项目 agalwood/Motrix 的 v2 版本（Turbo）正在 Beta 中（当前为 v2.0.0-beta.18）。

v2 最大的变化是架构重生：

  • 用 Electron 43 + React 19 + TypeScript（strict）+ Tailwind CSS 4 + shadcn/ui 重写桌面端；
  • 下载核心与 UI 完全分离，浏览器扩展、命令行工具通过 MDXP（Motrix Download eXchange Protocol） 这一基于 JSON-RPC 2.0 的开放协议与核心通信；
  • 插件运行在隔离的 QuickJS 沙箱中，拥有细粒度权限控制与内置应用市场；
  • 同一套核心可运行在两种形态：桌面 App（macOS / Windows / Linux）与无头服务器（Node.js 或 Docker，带 Web UI，适合 NAS / 家庭服务器）。

核心特性一览：清爽暗色界面、BT 单文件选择、内置 tracker 列表管理、UPnP / NAT-PMP 端口映射、上传/下载限速配置、SQLite 会话持久化（重启后恢复）、系统通知、Chrome / Firefox 一键接管下载、官方 @motrix/cli、Docker 无头服务器等。

二、技术原理

四层严格分层架构

Motrix 的代码被划分为四个严格分层，CI 会强制校验各层之间的依赖边界，保证核心可移植，并为未来的 Rust 重写留出清晰路径：

renderer (React UI)
   │  IPC via window.motrix
app core (tasks, settings, plugins, bridge)
   │
engine adapter
   │
aria2 (download engine)
  • renderer：React 渲染层，通过 window.motrix 与核心通信；
  • app core：任务、设置、插件、桥接逻辑，是真正的「大脑」；
  • engine adapter：适配层，屏蔽底层下载引擎差异；
  • aria2：下载引擎，使用 Motrix 维护的 aria2 fork，随应用打包。

MDXP：连接一切的核心协议

MDXP 是整个生态的「总线」。它定义了 JSON-RPC 2.0 的有线协议与 Zod 类型（@motrix/mdxp npm 包），并配套了：

  • @motrix/cli：命令行客户端，自动发现本地桌面 App，并能与远程实例配对；
  • 命令行工具 / AI Agent 客户端：通过设备码（device-code）流程配对远程或无头实例；
  • 浏览器扩展：通过原生消息（native messaging）与桌面 App 安全配对，一键接管下载。

技术栈一览

领域选型
桌面外壳Electron 43
UIReact 19 + Tailwind CSS 4 + shadcn/ui
语言严格模式 TypeScript
构建Vite 8，分 main / preload / worker / renderer 四个目标
校验Zod 4（设置、IPC 载荷、协议)
下载引擎Motrix 维护的 aria2 fork
持久化better-sqlite3（会话存储与恢复）
插件沙箱quickjs-emscripten
服务端运行时Node.js + Fastify + WebSocket
国际化i18next + react-i18next

Vite 多目标构建的取舍

v2 将构建拆成 main / preload / worker / renderer / server 多个 Vite 配置。例如 vite.main.config.ts 中对「必须打包进 cjs」的依赖做了精妙处理：

// 只能被打包进 cjs 的包（不可 externalize）两类原因：
// 1. exports 只暴露 import 条件，require() 解析直接抛错
//    → bittorrent-peerid、parse-torrent
// 2. electron-builder 26 + pnpm 提升布局会丢传递依赖
//    → pino（其孙依赖被 asar 剥离）
const BUNDLED_PACKAGES = ['bittorrent-peerid', 'parse-torrent', 'pino']

这类细节体现了 Electron 打包在真实工程中的「坑」，也是 v2 工程化成熟度的体现。

插件沙箱与权限模型

插件被打包为单个 ES2020 模块，运行在 QuickJS 沙箱中，没有 Node.js API，也无权直接访问文件与网络。插件在 motrix-plugin.json 中声明激活事件、所需能力与 URL 作用域权限，Motrix 在授予前会先向用户展示这些请求。插件可挂载到 beforeCreate、beforeFinalize、afterComplete、onError 等生命周期钩子，并通过 motrix:plugin-api 虚拟模块访问运行时。内置插件包括 Filename Template（模板重命名）、Page Scraper（从 HTML 提取直链）、URL Resolver（站点媒体解析基础）。

三、安装与快速开始

桌面端

前往 motrix.app 下载对应系统安装包。macOS 用户多数应选择 Apple Silicon（arm64）版本，旧款 Intel Mac 使用 x64 版本：

平台架构包 / 渠道建议
macOS 12+arm64 / x64.dmg / .zip选匹配芯片的 .dmg
Windowsx64.exe (NSIS) / .zip用 .exe 安装；.zip 可手动解压
Linuxx64 / arm64.deb / .rpmDebian/Ubuntu 用 .deb；Fedora/openSUSE 用 .rpm

当前 Beta 不发布 AppImage / Snap；Windows x64 包未签名，可能触发 SmartScreen 警告。

命令行客户端

npm install -g @motrix/cli    # 需要 Node.js 22+

motrix add https://example.com/file.iso --save-dir ~/Downloads
motrix list                   # 列出下载
motrix watch --stats          # 以 NDJSON 流式输出实时进度
motrix pair --name my-nas     # 与远程 / 无头实例配对

Docker 无头服务器

mkdir -p motrix-data downloads
sudo chown 1000:1000 motrix-data downloads
export MOTRIX_IMAGE='docker.io/motrixapp/motrix-server:2.0.0-beta.18'
export MOTRIX_PUBLIC_URL='http://nas.example.lan:8080'
docker compose pull server
docker compose up -d --wait

运行时为非 root，支持只读根文件系统，挂载前校验权限，并在容器替换时保留下载、会话与已装插件。默认 Web 服务在 8080 端口、MDXP 在 16801 端口。

四、使用方法与实战

浏览器一键接管下载

安装 Chrome / Firefox 扩展（Manifest V3）后，浏览器内的下载会被拦截并交给 Motrix，通过原生消息与桌面 App 安全配对——非常适合「种子 / 大文件走 Motrix，普通文件走浏览器」的混合场景。

用 CLI / Agent 驱动下载

@motrix/cli 既服务日常 shell，也面向 AI Agent。远程 CLI 与 Agent 通过 device-code 流程配对；若 Web 审批地址临时不可用，SSH 运维者可直接列出并批准客户端代码，而无需额外暴露端口：

docker compose exec server motrix-admin pairing pending
docker compose exec server motrix-admin pairing approve ABCD-EFGH

注意：直连 HTTP 仅适用于可信局域网；公网或不可信 LAN 需配合 TLS 反向代理与防火墙。

开发一个插件

使用官方 Plugin SDK 脚手架，几步即可创建、验证并打包插件：

pnpm create motrix-plugin my-plugin
cd my-plugin && pnpm install
pnpm dev                         # 监听构建并启动带插件的 Motrix
pnpm exec motrix-plugin validate # 校验 motrix-plugin.json
pnpm run pack                    # 产出 dist/<id>-<version>.moext
pnpm exec motrix-plugin lint     # 检查打包后的 bundle

默认脚手架从 beforeCreate URL 解析器起步；在名称后追加 post-action 可改为从 afterComplete 通知插件起步。

从源码开发

git clone https://github.com/agalwood/Motrix.git
cd Motrix
pnpm install     # 安装依赖、下载 aria2、重建原生模块
pnpm start       # 开发模式启动 Electron（renderer 带 Vite HMR）
pnpm test        # Vitest 单元测试
pnpm test:e2e    # Playwright E2E 测试

开发需 Node.js 22+ 与 pnpm（版本以 package.json 的 packageManager 字段为准）。macOS 上可在 MOTRIX_PREVIEW_MAC_MENU=1 pnpm start 预览应用内菜单布局。

五、常见问题与解决方案

1. Windows 安装时弹出 SmartScreen 警告 Beta 的 Windows x64 包未签名，属预期行为。确认来源可信后选择「仍要运行」即可；生产签名版本待正式发布。

2. v2 Beta 与 v1 数据迁移未经验证 官方明确不要用你唯一的 v1 数据去测试 Beta。先在测试前备份 v1 数据与下载；尽量在独立 OS 账户 / 机器 / Docker 数据目录中并行测试 v2。

3. Docker 部署权限问题 镜像默认以 node（uid 1000）非 root 运行，需提前 chown 1000:1000 motrix-data downloads，否则挂载权限校验会拒绝工作。运行时会校验挂载权限后才接受任务。

4. 远程客户端无法配对 / Web 审批地址不可达 设置 MOTRIX_PUBLIC_URL 为远程客户端真正可达的 Web 审批地址（Compose 不会用误导性的 localhost 替代）。若仍不可达，用 motrix-admin pairing 子命令在容器内直接批准。

5. pnpm / Node 版本不符导致构建失败 务必使用 package.json 中 packageManager 指定的 pnpm 版本（如 [email protected]），并升级到 Node.js 22+，否则原生模块（如 better-sqlite3）重建会失败。

6. 公网暴露端口的安全风险 标准直连 LAN 配置仅适合可信内网。公网或不可信 LAN 必须通过 TLS 反向代理并配置防火墙，围绕源端口（8080 / 16801）做访问控制。

六、总结

Motrix v2（Turbo）不是一次简单的换皮，而是一次彻底的架构升级：以 MDXP 开放协议为总线，把下载核心从 UI 中解放出来，再由此衍生出桌面端、无头服务器（Docker）、CLI、浏览器扩展与插件市场组成的完整生态。它在「功能齐全」与「简洁易用」之间保持了 v1 的初心，又用 Electron 43 / React 19 / Vite 8 / QuickJS 沙箱等现代工程实践把它推向了可扩展、可远程、可自动化的新阶段。

如果你需要一个既能日常抓种子、又能跑在 NAS 上做无头下载，还能被 AI Agent 通过 CLI 调用的全能下载器，Motrix v2 值得加入你的关注列表。当前 v2.0.0-beta.18 仍在 Beta，建议备份数据、并行测试，并留意其正式发布。

仓库地址：https://github.com/agalwood/Motrix