Motrix 全平台下载管理器

项目概述

Motrix 是一款界面简洁、功能完整的桌面下载管理器，支持 HTTP、FTP、BitTorrent、磁力链接等多种协议。Motrix Turbo 即 v2 版本，使用 Electron、React 和 TypeScript 从零重构，同时保留了 v1 干净直观的体验。下载核心与 UI 相互独立，浏览器扩展与命令行工具通过 MDXP（Motrix Download eXchange Protocol，基于 JSON-RPC 2.0 的开放协议）与应用通信，插件则运行在独立的沙箱中。

同一核心提供两种运行形态：桌面应用（支持 macOS、Windows、Linux）与无头服务器（可直接运行在 Node.js 或 Docker 中，附带 Web UI，适用于 NAS 与家用服务器）。

Beta 测试说明

Motrix Turbo v2 当前处于 beta 阶段，可从 GitHub Releases 下载 v2.0.0-beta.19，安装前请阅读完整的发布说明。测试前务必备份现有数据；v1 数据迁移尚未完成验证，请勿将唯一的 v1 数据副本用于此 beta。建议在独立系统账户、机器或 Docker 数据目录中并行测试。

主要特性

• 简洁直观的界面，支持深色模式
• BitTorrent 下载，逐文件选择，支持磁力链接
• 内置 Tracker 列表管理，自动更新与健康检查
• UPnP 与 NAT-PMP 端口映射
• 上下行限速，支持多套限速配置
• 基于 SQLite 的会话持久化，重启后可恢复下载
• 可自定义的 Dashboard，展示传输统计、实时活动与任务卡片
• 系统通知与内置通知中心
• 基于 QuickJS 的插件沙箱，权限细粒度控制，配备应用内插件市场
• Chrome 与 Firefox 扩展，一键接管浏览器下载
• 官方 @motrix/cli 命令行客户端
• Docker 化的无头服务器，远程客户端通过设备码配对
• 可扩展的 URL 解析器插件，用于从特定站点提取媒体资源
• 系统托盘集成、开机自启
• 简体中文与英文界面，更多语言计划中
• 支持 motrix://、magnet: 链接以及 .torrent 文件关联

生态系统

项目	发行形式	功能
@motrix/mdxp	npm 包	定义 MDXP 共享的 JSON-RPC 2.0 线协议与 Zod 类型
@motrix/cli	npm 包	提供 motrix 命令，自动发现本地桌面应用并与远程实例配对
Motrix 浏览器扩展	浏览器扩展	在 Chrome 与 Firefox（Manifest V3）中拦截下载并移交 Motrix
Motrix Plugin SDK	四个 npm 包	提供清单 schema、运行时 API、CLI 与脚手架工具
Builtin Plugins	已签名的 .moext 包	内置三款官方插件：Filename Template、Page Scraper、URL Resolver
Plugin Registry	公共 JSON feed	发布插件清单与安装元数据

CLI 快速上手

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     # 与远程或无头实例配对

插件开发

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     # 检查打包产物

默认脚手架生成 beforeCreate URL 解析器；若传入 post-action 参数则生成 afterComplete 通知插件。插件可挂钩 beforeCreate、beforeFinalize、afterComplete、onError 等钩子，通过 motrix:plugin-api 虚拟模块访问运行时。插件以单一 ES2020 模块形式打包，运行在 QuickJS 沙箱中，权限请求会在授予前向用户展示。

安装方式

桌面应用

从 motrix.app 下载对应操作系统的安装包。Apple Silicon 用户选择对应 .dmg；旧款 Intel Mac 选择 x64 版本。Windows 推荐 .exe 安装程序，Linux 用户按发行版选择 .deb 或 .rpm。当前 beta 不发布 AppImage、Snap 或 Windows arm64 包；Windows x64 包未签名，可能触发 SmartScreen 警告。

无头服务器（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.19'
export MOTRIX_PUBLIC_URL='http://nas.example.lan:8080'
docker compose pull server
docker compose up -d --wait

运行时以非 root 用户运行，支持只读根文件系统。Web 服务默认发布在 8080 端口，MDXP 在 16801 端口。若 Web 审批 URL 临时不可用，可通过 SSH 执行 motrix-admin pairing pending 与 motrix-admin pairing approve ABCD-EFGH 完成审批。远程 CLI 与代理客户端通过设备码流程配对；互联网访问需配置 TLS 反向代理。

开发指南

开发环境需要 Node.js 22+ 与 pnpm。

git clone https://github.com/agalwood/Motrix.git
cd Motrix
pnpm install     # 安装依赖、下载 aria2、重新构建原生模块
pnpm start       # 以 Vite HMR 启动 Electron 应用
pnpm test        # 运行 Vitest 单元测试
pnpm test:e2e    # 运行 Playwright 端到端测试
pnpm run lint    # 运行 Biome 检查
pnpm build       # 拉取签名内置插件并构建四个 Vite 目标

在 macOS 上预览窗口内应用菜单：MOTRIX_PREVIEW_MAC_MENU=1 pnpm start。原生角色项（如 Window → Minimize）需在 Windows 或 Linux 上验证。

技术栈

• 桌面外壳：Electron 43
• UI：React 19 + Tailwind CSS 4 + shadcn/ui
• 语言：TypeScript 严格模式
• 构建：Vite 8，分主进程、preload、worker、renderer 四个目标
• 校验：Zod 4，用于设置、IPC 负载与线协议
• 下载引擎：Motrix 维护的 aria2 分支
• 持久化：better-sqlite3，用于下载会话存储与恢复
• 插件沙箱：quickjs-emscripten
• 服务端运行时：Node.js + Fastify + WebSocket
• 国际化：i18next + react-i18next
• 质量工具：Biome、Vitest、Playwright

代码库分为四个严格层级，CI 强制约束依赖边界，保持核心可移植：

renderer (React UI)
   │  IPC via window.motrix
app core (tasks, settings, plugins, bridge)
   │
engine adapter
   │
aria2 (download engine)

Electron 桌面应用与 Node.js 无头服务器共用同一核心；平台特定能力（通知、密钥存储）有各自的实现但保持行为一致。

许可证

项目基于 MIT 许可证发布，详见 LICENSE 文件。第三方许可证信息见 THIRD_PARTY_NOTICES.md，发布包在 legal/ 目录下附带生成的依赖清单、合并后的许可证文本以及 SPDX 2.3 SBOM。