所有常见的 aria2 问题都汇总在这里：安装、SSL、HTTP/FTP、BitTorrent、RPC/WebUI、网络与代理、磁盘与 I/O、断点续传与会话、性能、配置与安全。每个条目都包含症状、原因、具体的解决方法以及预期结果。aria2.org 是一个独立的社区资源。
症状： 终端提示 aria2c: command not found、'aria2c' is not recognized，或 yt-dlp 提示 “aria2c is not installed. please install it first.”
原因： 尚未安装 aria2，或者其所在目录不在 PATH 中。
解决方法： 安装 aria2，然后重新打开终端以刷新 PATH。
预期结果： aria2c --version 会输出类似 1.37.0 的版本号。
症状： 已经解压了 aria2，但每次打开新终端都提示命令未知。
原因： 存放 aria2c.exe 的目录从未加入 Path 环境变量。
解决方法： 将该目录加入 Path，并打开一个全新的终端（已打开的终端仍使用旧的环境变量）。
预期结果： 新打开的 CMD/PowerShell 可以找到 aria2c。
症状： aria2c 启动即退出，提示缺少某个共享库。
原因： 缺少必需的依赖库，或者二进制版本与当前系统不匹配。
解决方法： 安装发行版提供的依赖包。
预期结果： aria2c --version 不再报缺少库的错误，可正常运行。
症状： 打开 aria2c.exe 时弹出缺少 DLL 的错误。
原因： 把 aria2c.exe 单独移出了 ZIP 解压目录，与其配套的 DLL 分离了。
解决方法： 保持整个解压目录完整，并将该目录加入 Path。
预期结果： aria2c 正常启动并输出版本号。
症状： macOS（Gatekeeper）拒绝运行下载的二进制文件。
原因： 该二进制文件未经签名与公证，被标记为隔离文件。
解决方法： 优先使用 Homebrew 安装，或手动清除隔离属性。
预期结果： Gatekeeper 允许该二进制文件运行。
症状： 提示“Windows 已保护你的电脑”，或下载后不久文件就被删除。
原因： 未签名的命令行工具偶尔会被启发式查杀误报。
解决方法： 仅从官方 GitHub Releases 下载，核对校验和后放行；或使用 winget/scoop/choco 安装。
预期结果： aria2c 可以正常运行且不会被删除。
症状： 容器不断重启，或 6800 端口没有任何响应。
原因： 入口命令或启动命令错误、缺少配置文件，或容器内 RPC 只绑定了 localhost。
解决方法： 查看日志；确保启用了 --enable-rpc、rpc-listen-all=true，并已发布端口。
预期结果： curl http://localhost:6800/jsonrpc 返回 JSON-RPC 响应。
症状： HTTPS 下载因证书校验失败而中断。
原因： 根证书（CA）过旧，或遇到自签名、内网证书。
解决方法： 更新 CA 证书包，或让 aria2 指向正确的证书；内网站点请安装对应的 CA。
预期结果： 下载不再报证书警告，可正常开始。
症状： 连接在 TLS 握手阶段中断，没有传输任何数据。
原因： TLS 库过旧、代理或杀毒软件中间拦截，或不支持的协议版本。
解决方法： 更新 aria2 和操作系统；尝试关闭代理；换个网络测试。
预期结果： 握手成功，下载继续进行。
症状： 指定 --ca-certificate 没有任何效果。
原因： Windows（WinTLS）和 macOS（AppleTLS）后端不支持该选项，它们使用系统信任库。
解决方法： 将证书导入操作系统的信任库。
预期结果： 使用系统信任的证书，HTTPS 下载成功。
症状： 服务器返回 403，下载停止。
原因： 该文件需要会话 Cookie、Referer 或浏览器 User-Agent（防盗链保护）。
解决方法： 附带 Cookie 和请求头下载。
预期结果： 服务器返回 200 并开始传输。
症状： aria2 以退出码 3 退出，并反复提示“resource not found”。
原因： URL 错误、已过期，或文件已被删除（签名链接很常见）。
解决方法： 获取新的 URL，并设置重试上限以便快速失败。
预期结果： aria2 不会无限循环，而是快速停止，或用新 URL 下载成功。
症状： 短时间内大量请求后被服务器限流。
原因： 并行连接数或并发文件数过多。
解决方法： 降低连接数与并发数，并增加重试间隔。
预期结果： 请求保持在限流阈值以下，下载顺利完成。
症状： 服务器暂时过载或正在维护。
原因： 服务器端临时负载过高或被限流。
解决方法： 等待后重试；--retry-wait 可让 aria2 自动重试 503。
预期结果： aria2 等待并重试，直到服务器恢复。
症状： aria2 报告认证失败。
原因： 缺少凭据或凭据错误（包括 Basic 与 Bearer 认证）。
解决方法： 通过用户名与密码或 Authorization 请求头提供凭据。
预期结果： 服务器认证通过并开始发送数据。
症状： aria2 因“too many redirects”而中止。
原因： 重定向循环，或 CDN 要求携带 Cookie 与请求头。
解决方法： 直接使用最终 URL，或附带 Cookie 和 Referer。
预期结果： aria2 到达最终的 200 响应。
症状： aria2 无法解析服务器的响应。
原因： 损坏的或透明代理、杀毒软件的 TLS 过滤，或该端口上根本不是 HTTP 服务。
解决方法： 去掉中间拦截的代理或 TLS 过滤后重试；确认 URL 确实是 HTTP/HTTPS。
预期结果： 收到干净的 200 响应，可正常解析下载。
症状： 使用 -c 后 aria2 仍拒绝续传。
原因： 服务器忽略 Range（分段）请求，或文件已变化（大小或 ETag 不同）。
解决方法： 去掉 -c 重新完整下载，或换一个支持 Range 的镜像源。
预期结果： 完整下载顺利完成。
症状： aria2 因超时而放弃。
原因： 服务器慢或不稳定，或超时设置过短。
解决方法： 增大超时和重试次数；丢弃卡住的连接。
预期结果： aria2 会重试并续传，而不是直接中止。
症状： FTP 传输因认证或命令错误而失败。
原因： 凭据错误，或防火墙拦截了主动或被动 FTP。
解决方法： 设置正确的凭据，并尝试被动模式（默认）。
预期结果： FTP 会话登录成功并开始传输文件。
症状： .meta4/.metalink 下载失败。
原因： XML 格式损坏，或 URL 返回的是 HTML 错误页面而非 Metalink。
解决方法： 先把 Metalink 文件本身下载下来打开确认，并验证 URL 返回的确实是 XML。
预期结果： aria2 解析 Metalink 并下载其中列出的文件。
症状： 只得到一个很小的 .html 文件或“Access denied”页面。
原因： 该链接需要登录、令牌或经过确认页面。
解决方法： 使用真正的文件 URL（或从浏览器导出 Cookie）。
预期结果： 响应内容是真正的二进制或文件数据。
症状： 种子任务启动后始终找不到 peer。
原因： Tracker 失效、未启用 DHT 与 LPD，且没有开放入站端口。
解决方法： 添加可用的 Tracker，启用 DHT 与 LPD，并转发端口。
预期结果： 成功连上 peer，速度从 0 开始上涨。
症状： 能下载但速度很慢，其他 peer 无法主动连你。
原因： 没有入站端口（未做端口转发，或处于 CGNAT 与 VPN 之后）。
解决方法： 转发一个 TCP+UDP 端口并在 aria2 中设置；若在 CGNAT 之后，请使用支持端口转发的 VPN。
预期结果： 客户端变为可连接状态，速度明显提升。
症状： 种子里列出了 Tracker，但没有任何响应。
原因： Tracker 已下线，或当前网络拦截了 UDP。
解决方法： 替换为可用的 Tracker，并补充 HTTP(S) Tracker 作为备用。参见 Tracker 列表。
预期结果： 至少有一个 Tracker 上报成功并出现 peer。
症状： 粘贴磁力链接后命令被拆散报错。
原因： URI 中的 & 和 ? 被 Shell 解析了。
解决方法： 始终用双引号把磁力链接包起来。
预期结果： aria2 获取到元数据并开始下载。
症状： 磁力任务始终停留在获取元数据阶段，无法进入下载。
原因： 没有可用的 peer 或 DHT 来源来获取种子元数据（种子群已死）。
解决方法： 添加 Tracker 以便获取元数据，或直接使用 .torrent 文件。
预期结果： 元数据到达，保存为 .torrent 文件并开始下载。
症状： 私站种子连不上，或账号分享率受影响。
原因： 私站规则要求只用站内 Tracker，禁用 DHT 与 PEX，并要求保种。
解决方法： 禁用 DHT 与 PEX，并保种到要求的分享率。
预期结果： 私站接受该客户端，并持续做种。
症状： 任务到 100% 后一直处于活动状态。
原因： seed-ratio=0（无限做种）或分享率目标设得过高。
解决方法： 设置分享率或做种时长限制。
预期结果： 达到条件后做种自动停止。
症状： aria2 拒绝打开某个种子或磁力链接。
原因： .torrent 文件截断或损坏，或磁力链接格式错误。
解决方法： 从源站重新下载 .torrent，或复制完整的磁力链接。用 -S 检查。
预期结果： aria2 列出种子内容并完成下载。
症状： 同一种子在 aria2 中明显更慢。
原因： 默认配置偏保守（peer 数、peer 速度奖励、上传限制），且没有转发端口。
解决方法： 调优 swarm 参数并转发端口（参见 速度优化指南）。
预期结果： 速度接近其他客户端。
症状： 控制面板始终连不上后台进程。
原因： aria2 没有启用 RPC、主机或端口填错，或密钥不一致。
解决方法： 使用令牌启动 RPC，并在 WebUI 中填入相同的值。
预期结果： WebUI 显示“Connected”（已连接）。
症状： 启用 RPC 后 aria2 无法启动。
原因： 另一个 aria2 实例或其他程序占用了 6800 端口。
解决方法： 停止占用端口的进程，或换一个 RPC 端口。
预期结果： aria2 正常启动，RPC 在新端口上响应。
症状： 客户端能连上，但每次调用都返回错误。
原因： 客户端中的 rpc-secret 与后台进程不一致。
解决方法： 在 WebUI/AriaNg 和后台进程中使用完全相同的令牌。
预期结果： 调用成功，下载列表正常显示。
症状： 浏览器控制台拦截了 HTTPS 页面对 RPC 的调用。
原因： HTTPS 页面无法调用明文 http:///ws:// 接口。
解决方法： 通过反向代理（或 VPN）让 RPC 走 HTTPS/WSS，再使用该地址。
预期结果： HTTPS 版 WebUI 不再被混合内容策略拦截，可正常连接。
症状： 控制台显示 CORS 策略错误。
原因： 后台进程未允许该页面的来源。
解决方法： 启用 rpc-allow-origin-all=true（仅在端口不对外公开时使用）。
预期结果： 浏览器可以正常调用 RPC 接口。
症状： 关闭 Shell 后 aria2 被结束，WebUI 断开连接。
原因： aria2 是在前台启动的（没有以后台守护进程方式运行）。
解决方法： 以守护进程或系统服务方式运行。
预期结果： 关闭 Shell 后 aria2 依然在运行。
症状： localhost 可以访问，但局域网 IP 访问不了。
原因： 后台进程只绑定了 localhost，或防火墙拦截了该端口。
解决方法： 监听所有网卡，并放行防火墙端口（仅在可信网络中使用）。
预期结果： 远程客户端可通过局域网 IP 访问 RPC。
症状： 调用 aria2 的集成程序连自己的请求都解析失败。
原因： JSON-RPC 请求体格式错误，或方法与参数结构不对。
解决方法： 检查请求体；注意 params 必须把令牌放在第一位。
预期结果： RPC 接受该请求并返回结果。
症状： 所有下载都失败，提示 Exception: [AbstractCommand.cc:...] errorCode=1。
原因： 常见原因是设置了系统代理但代理未运行、防火墙或杀毒软件拦截，或 IPv6 问题。
解决方法： 清除失效的代理，或禁用 IPv6；检查 hosts 文件。
预期结果： aria2 恢复正常连接和下载。
症状： aria2 无法解析主机名。
原因： DNS 损坏、解析服务器不可达，或 hosts 条目错误。
解决方法： 测试 DNS，尝试指定解析服务器或关闭异步 DNS。
预期结果： 主机名解析成功并建立连接。
症状： 因代理配置错误、代理未运行或认证被拒绝而下载失败。
原因： 全局设置了代理但代理未运行，或凭据错误。
解决方法： 填写正确的带认证代理，或清空代理设置。aria2 只支持 HTTP 代理，填写 socks5:// 会报错“unrecognized proxy format”。
预期结果： 流量经代理正常转发，下载继续。
症状： 部分站点失败、其他站点正常，常伴随网络错误。
原因： IPv6 连接损坏；aria2 优先走了不通的 IPv6 路由。
解决方法： 在 aria2 中禁用 IPv6。
预期结果： aria2 走 IPv4，下载成功。
症状： 域名能解析，但连到了错误的地方（或 127.0.0.1）。
原因： 去臃肿或反遥测工具、杀毒软件添加了空路由。
解决方法： 检查 hosts 文件和防火墙，删除拦截条目。
预期结果： 域名连到真实 IP，下载正常。
症状： 下载因磁盘空间不足而中止。
原因： 目标磁盘已满，或预分配需要的空间超出剩余空间。
解决方法： 清理空间、换一个 --dir，或降低预分配方式。
预期结果： 文件正常写入，不再报空间不足。
症状： aria2 无法写入目标目录。
原因： 当前用户（或容器）没有写权限。
解决方法： 下载到自己有权限的目录，或修复权限与属主。
预期结果： 文件成功创建并写入。
症状： aria2 在创建或写入文件与目录时失败。
原因： 路径错误、文件名含非法字符、磁盘只读或被拔出，或磁盘故障。
解决方法： 使用简短、合法、可写的路径；检查磁盘状态。
预期结果： 目录和文件正常创建，无 I/O 错误。
症状： 大文件在 FAT32/exFAT U 盘上失败或损坏。
原因： FAT32 单文件上限 4 GB；部分 exFAT 驱动对超大稀疏文件支持不佳。
解决方法： 使用 NTFS/ext4，或先下载到内置硬盘。
预期结果： 大文件在合适的文件系统上正常写入。
症状： 写入网络共享速度很慢、卡死或失败。
原因： falloc/prealloc 和稀疏文件在网络共享上支持不好。
解决方法： 在网络共享上使用 none 分配方式，并设置较小的磁盘缓存。
预期结果： 在共享目录上可靠地完成写入。
症状： 续传时报分片长度不匹配而失败。
原因： 该 .aria2 文件属于另一个文件（或服务器配置已变）。
解决方法： 删除不匹配的控制文件后重新下载，或允许长度变化。
预期结果： 下载继续，控制文件匹配正常。
症状： 因同名文件已存在，aria2 拒绝写入。
原因： 覆盖保护开启，或自动重命名遇到了非法文件名。
解决方法： 允许覆盖或自动重命名。
预期结果： aria2 覆盖或重命名后继续下载。
症状： 大文件下载时整个系统变卡。
原因： 在 HDD 或慢速磁盘上预分配加大量小写入导致。
解决方法： 使用 falloc（或 trunc），增大磁盘缓存，减少连接数。
预期结果： 磁盘占用更平滑，系统保持流畅。
症状： 长的种子或文件名在 Windows 上失败。
原因： 经典的 260 字符 MAX_PATH 限制。
解决方法： 缩短 --dir，或在 Windows 中启用长路径支持。
预期结果： 文件在路径长度限制内成功创建。
症状： 重新运行下载任务时从头开始。
原因： 缺少 -c、文件被重命名或移动，或控制文件丢失。
解决方法： 保持 file.ext + file.ext.aria2 在一起，并用 -c 运行。
预期结果： aria2 从已有分片继续下载。
症状： 完成后 file.ext.aria2 仍然存在。
原因： BitTorrent 做种仍在进行，或完整性校验未通过。
解决方法： 停止做种或移除任务，或校验文件。
预期结果： 文件封存后 aria2 删除控制文件。参见 .aria2 文件指南。
症状： 播放器或解压软件拒绝打开未完成的文件。
原因： 文件根本还没下完（.aria2 文件还在）。
解决方法： 继续下载；不要删除控制文件。
预期结果： 下载完成后文件恢复正常。
症状： 重启 aria2 后队列与进度丢失。
原因： 没有配置会话持久化。
解决方法： 配置会话文件和保存间隔。
预期结果： aria2 启动时重新加载队列并续传。
症状： aria2 启动后立即退出并报 errorCode=1 Failed to open the file …/aria2.session；Docker 容器不断重启。
原因： input-file 指向一个尚不存在的会话文件。aria2 只在 save-session 时创建它，但缺少该文件时拒绝启动。另外 aria2 会展开路径中的 ${HOME}，但不会展开 ~。
解决方法： 先创建一次空文件，并在 aria2.conf 中使用绝对路径或 ${HOME}。
预期结果： aria2 以空队列启动，此后会自动保存和恢复队列。
症状： aria2 拒绝添加重复任务。
原因： 相同 URI 或种子已在队列中。
解决方法： 管理已有任务（或更换输出文件名）。
预期结果： 队列中只保留一个该任务。
症状： 速度远低于实际带宽。
原因： aria2 的 HTTP 默认是每服务器单连接。
解决方法： 增加连接数和分片数。
预期结果： 速度提升到接近带宽上限。参见 速度优化指南。
症状： 速度卡在一个整数值（例如正好 5 MB/s）。
原因： 设置了限速选项（0 表示不限速）。
解决方法： 清除下载与上传限速。
预期结果： 速度只受网络与磁盘限制。
症状： 下载时内存或 CPU 占用很高。
原因： disk-cache 设得过大、连接数上百，或 peer 数过大。
解决方法： 降低缓存和连接与 peer 上限。
预期结果： 资源占用下降，速度仍可接受。
症状： aria2 放弃了速度过慢的源。
原因： lowest-speed-limit 对该服务器设得过高。
解决方法： 调低或去掉该限制。
预期结果： 即使源速度慢，下载也会继续。
症状： aria2 因选项错误无法启动。
原因： 拼写错误、键名写错，或当前版本不支持该选项。
解决方法： 对照 选项参考检查键名，并更新 aria2。
预期结果： aria2 正常解析配置并启动。
症状： 文件中的设置没有任何效果。
原因： 文件放错位置、文件名错误，或命令行参数覆盖了它。
解决方法： 使用正确的路径，并记住命令行选项优先级更高。
预期结果： 启动时配置的选项正常生效。
症状： 通过 yt-dlp 传递的 aria2 参数没有生效。
原因： Shell 引号把 aria2c: 的值拆散了。
解决方法： 用双引号把整个值包起来；不要混用引号类型。
预期结果： 参数正常传给 aria2，速度提升。
症状： RPC 端口可以从公网访问。
原因： 设置了 rpc-listen-all=true，又做了路由器端口转发或有公网 IP。
解决方法： 永远不要把 6800 公开暴露。只保留在 localhost 或局域网，使用 VPN 或带认证的 HTTPS 反向代理。
预期结果： 只有可信网络能访问 RPC。
症状： 为 WebUI 开启了 CORS，有点担心安全性。
原因： CORS 放开后，只要能访问该端口，你打开的任意页面都能调用 RPC。
解决方法： 保持端口私有，使用强密钥，优先用本地页面或代理而非暴露端口。
预期结果： WebUI 正常可用，不可信站点无法访问 RPC。
症状： 正准备从不可信来源下载。
原因： 种子或 Metalink 可能指向恶意内容；外来的 .aria2 文件不可信。
解决方法： 优先使用官方来源，校验校验和与签名，绝不把 .aria2 文件复用于另一个文件。
预期结果： 文件哈希与官方公布的摘要一致。
没有找到匹配的问题。换个关键词试试，或查看文档。
aria2 返回它遇到的最后一个错误的错误码。用它可以快速判断失败类型。用 echo $?（Linux/macOS）或 echo %ERRORLEVEL%（Windows）查看上一个退出码。
| 代码 | 含义 | 相关选项 |
|---|---|---|
| 0 | 全部下载成功。 | |
| 1 | 未知错误。 | |
| 2 | 发生超时。 | --timeout |
| 3 | 未找到资源。 | |
| 4 | “resource not found”错误过多。 | --max-file-not-found |
| 5 | 由于速度太慢而中止下载。 | --lowest-speed-limit |
| 6 | 发生网络问题。 | |
| 7 | aria2 停止时还有未完成的下载。 | |
| 8 | 远程服务器不支持断点续传。 | --continue |
| 9 | 磁盘空间不足。 | |
| 10 | 分片长度与 .aria2 控制文件不一致。 | --allow-piece-length-change |
| 11 | 相同文件正在下载中。 | |
| 12 | 相同 info hash 的种子正在下载中。 | |
| 13 | 文件已存在。 | --allow-overwrite |
| 14 | 文件重命名失败。 | --auto-file-renaming |
| 15 | 无法打开已存在的文件。 | |
| 16 | 无法创建新文件 / 截断已有文件。 | |
| 17 | 文件 I/O 错误。 | |
| 18 | 无法创建目录。 | |
| 19 | 域名解析失败。 | |
| 20 | 无法解析 Metalink 文档。 | |
| 21 | FTP 命令失败。 | |
| 22 | HTTP 响应头错误或不符合预期。 | |
| 23 | 重定向过多。 | |
| 24 | HTTP 认证失败。 | |
| 25 | 无法解析 bencoded 文件（.torrent）。 | |
| 26 | .torrent 文件损坏或缺少 info。 | |
| 27 | 磁力链接格式错误。 | |
| 28 | 错误的或无法识别的选项或参数。 | |
| 29 | 远程服务器暂时无法处理请求。 | --retry-wait |
| 30 | 无法解析 JSON-RPC 请求。 | |
| 31 | 保留（未使用）。 | |
| 32 | 校验和验证失败。 | --check-integrity |
来源：aria2 官方手册。退出码只是诊断辅助，不能代表全部原因 — 详情请用日志（--log-level=debug）查看。
开启调试日志，复现一次，然后分享相关日志行。
aria2c --log-level=debug --log=aria2-debug.log URL # or to stdout: aria2c --log-level=debug URL
aria2c --version）、操作系统和完整命令。