Mac 安装和使用 aria2

前言

aria2是一款轻量级、多协议、多来源的命令行下载工具，支持 HTTP/HTTPS、FTP、SFTP、BitTorrent、Metalink 等协议。相比 curl 或 wget，aria2 在多线程分段下载和断点续传方面更强大，非常适合大文件下载。
本文记录如何在 macOS 上通过 Homebrew 安装、配置 aria2c，并实现 后台运行、开机自启，以及通过 Web GUI 或浏览器插件进行可视化管理。
如果不想折腾，推荐使用Motrix。
PT 用户请使用站点白名单软件。

什么是 aria2 和 aria2c

aria2
是整个项目的名字，指这个多协议下载工具本身。特点是轻量、快速，支持多线程和断点续传。
aria2c
是 aria2 的命令行客户端程序，通常在终端中执行 aria2c 来下载文件或管理下载任务。

安装并配置aria2

# 使用 Homebrew 安装 aria2
brew install aria2

# 创建配置目录与文件
mkdir -p ~/.aria2
touch ~/.aria2/aria2.conf
touch ~/.aria2/aria2.session

编辑 ~/.aria2/aria2.conf，示例：

# 下载目录
dir=${HOME}/Downloads

# 开启断点续传
continue=true

# 磁盘缓存
disk-cache=32M

# 最大同时下载任务数
max-concurrent-downloads=5

# 每个任务的最大连接数
split=16
max-connection-per-server=16

# 出错重试次数
max-tries=0

# 每次重试之间的等待时间
retry-wait=10

# 最小文件分片大小
min-split-size=1M

# 文件未完成时保存为 .aria2 后缀，下载完成自动去除
allow-overwrite=true
auto-file-renaming=true

# RPC 设置
enable-rpc=true
rpc-listen-port=6800
rpc-listen-all=true
rpc-allow-origin-all=true
# rpc-secret=你的密钥

# 会话文件
input-file=${HOME}/.aria2/aria2.session
save-session=${HOME}/.aria2/aria2.session
save-session-interval=60

# 使用 UTF-8 处理 Content-Disposition
content-disposition-default-utf8=true

# 客户端伪装
# > 自定义 User Agent
user-agent=Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/139.0.0.0 Safari/537.36
# > BT 客户端伪装
peer-id-prefix=-TR2940-
peer-agent=Transmission/2.94

# BT 下载设置
enable-dht=true
enable-dht6=true
dht-file-path=${HOME}/.aria2/dht.dat
dht-file-path6=${HOME}/.aria2/dht6.dat
bt-enable-lpd=true
enable-peer-exchange=true
seed-ratio=1.0
# seed-time=0
# > BT 下载最大连接数（单任务）
bt-max-peers=128
# > BT 下载期望速度值（单任务）
bt-request-peer-speed-limit=10M
# > 保存磁力链接元数据为种子文件
bt-save-metadata=true
# > 加载已保存的元数据文件
bt-load-saved-metadata=true
# > 删除 BT 下载任务中未选择文件
bt-remove-unselected-file=true
# > 分离仅做种任务
bt-detach-seed-only=true
# > 继续之前的BT任务时, 无需再次校验
bt-seed-unverified=true
# > BT 服务器地址
# bt-tracker=

⚠️注意替换你的RPC密钥

后台运行 aria2

在 macOS 上可以使用-D 或 --daemon启用守护进程模式

1	aria2c --conf-path=$HOME/.aria2/aria2.conf -D

查看后台进程：

1	ps aux \| grep aria2

停止后台运行：

1	pkill aria2

解除 Mac 的 limit maxfiles 限制

如果经常使用 aria2 下载 bt，很容易会触发too many open files错误，可以使用以下方法解除限制：

1	sudo vim /Library/LaunchDaemons/limit.maxfiles.plist

写入以下内容：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>limit.maxfiles</string>
    <key>ProgramArguments</key>
    <array>
        <string>launchctl</string>
        <string>limit</string>
        <string>maxfiles</string>
        <string>65536</string>
        <string>200000</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>ServiceIPC</key>
    <false/>
</dict>
</plist>

使用

# 安装
sudo launchctl bootstrap system /Library/LaunchDaemons/limit.maxfiles.plist
# 卸载
sudo launchctl bootout system /Library/LaunchDaemons/limit.maxfiles.plist
# 验证
launchctl limit maxfiles

开机自启 aria2

macOS 可以使用 LaunchAgent 来设置开机自启。

创建 LaunchAgent 文件：

1 2	mkdir -p ~/Library/LaunchAgents vim ~/Library/LaunchAgents/aria2.plist

粘贴以下内容：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>aria2</string>

  <key>ProgramArguments</key>
  <array>
    <string>/opt/homebrew/bin/aria2c</string>
    <string>--conf-path=/Users/你的用户名/.aria2/aria2.conf</string>
  </array>

  <key>RunAtLoad</key>
  <true/>

  <key>KeepAlive</key>
  <true/>

  <key>LimitLoadToSessionType</key>
  <array>
    <string>Aqua</string>
  </array>

  <!-- 确保 aria2 在 limit.maxfiles 之后启动 -->
  <key>LaunchEvents</key>
  <dict>
    <key>com.apple.launchd.job.limit.maxfiles</key>
    <true/>
  </dict>

</dict>
</plist>

⚠️注意替换你的用户名，以及检查目录是否正确。plist 里好像只能使用绝对路径，不能用环境变量（比如 ${HOME}、~）

添加并启用自启动项:

# 检查plist语法是否正确
plutil ~/Library/LaunchAgents/aria2.plist

# 修改文件权限
chmod 644 ~/Library/LaunchAgents/aria2.plist

# 添加自启动项
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/aria2.plist

# 删除自启动项
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/aria2.plist

⚠️如果提示诸如 Load failed: 5: Input/output error Try running launchctl bootstrap as root for richer errors .此类的错误，请先检查 aria2c 路径或者尝试更新全部 brew 依赖，若没有解决请尝试先删除启动项再进行 load 。

Aria2 Web GUI

前提：使用 Aria2 Web GUI 都需要根据 aria2.conf 配置文件中的 PRC 相关设置项进行设置，下面推荐两个 Aria2 Web GUI 项目。

AriaNg

这是一款基于网页的 aria2 前端管理工具，它无需安装，只要打开官方托管网页即可使用，通过连接 aria2 的 RPC 接口来实现可视化管理。当然你也可以将它下载到本地用浏览器打开或者自行部署到服务器。

Aria2 Explorer

这是一个浏览器插件，其实普通用户更推荐使用这个。
它能够自动拦截浏览器下载任务并通过JSON-RPC接口导出到Aria2进行高速下载并内置AriaNG作为管理前端。
插件本身具备通知功能。
插件整合了右键下载菜单。

自动更新bt-tracker

创建一个脚本

1	vim ~/.aria2/update-tracker.sh

写入以下内容，可以根据喜好自行替换 TRACKER_URL：

#!/bin/bash

CONF="${HOME}/.aria2/aria2.conf"
TRACKER_URL="https://cf.trackerslist.com/best_aria2.txt"

echo -e "\033[34m==> 获取最新 bt-tracker 列表......\033[0m"
list=$(curl -fsSL "$TRACKER_URL" | tr '\n' ',' | sed 's/,$//')

if [ -z "$list" ]; then
    echo -e "\033[31m❌ 获取 tracker 失败，请检查网络或 URL\033[0m"
    exit 1
fi

tracker_count=$(echo "$list" | tr ',' '\n' | wc -l | tr -d ' ')

# 更新配置文件
if grep -q "^bt-tracker=" "$CONF"; then
    echo -e "\033[34m==> 更新 ${CONF} 中的 bt-tracker 信息......\033[0m"
    sed -i '' "s@^bt-tracker=.*@bt-tracker=${list}@g" "$CONF"
else
    echo -e "\033[34m==> 添加 bt-tracker 信息到 ${CONF}......\033[0m"
    echo -e "\nbt-tracker=${list}" >> "$CONF"
fi

# 重启 aria2
echo -e "\033[34m==> 重启 aria2 服务......\033[0m"
pkill aria2c
aria2c --conf-path=$CONF -D
echo -e "\033[32m✅ 更新完成，已应用 ${tracker_count} 个 tracker 并重启 aria2\033[0m"

使用方法

赋权：

1	chmod +x ~/.aria2/update-tracker.sh

测试运行：

1	~/.aria2/update-tracker.sh

设置定时更新：

1	crontab -e

写入以下内容：

1	0 18 * * * $HOME/.aria2/update-tracker.sh >/dev/null 2>&1

这样，每天18点会自动更新 bt-tracker。

Mac编译aria2突破线程限制