简介百度网盘下载链接有时效性限制配合aria2下载时任务常因链接过期而中断这一问题困扰着众多重度用户。这套BaiduAria2Resume工具采用Python编写可在后台持续运行自动检测并修复Aria2中失效的百度云链接无需人工干预即可保持下载任务稳定进行。资源共6个文件包括3个Python脚本分别负责主流程控制、任务管理、登录验证、1份说明文档、1张效果截图及1个配置文件压缩包仅103KB非常轻量。脚本支持通过命令行灵活配置用户名、密码、端口等参数登录部分参考了pan-baidu-download项目可靠性有保障配合BaiduExporter将百度云任务导入aria2再通过webui-aria2进行管理可让百度网盘下载接近满速。对于使用aria2下载百度云资源并深受链接时效问题困扰的Python用户而言这份工具提供了直接有效的解决方案目前已有1252人学习下载。 真正让我决定写 BaiduAria2Resume 这个脚本的是一次下载一个 30GB 压缩包的体验。Aria2 已经跑到 87%突然一口气报了403 Forbidden任务整整齐齐全部停在原地。我一开始以为是网络波动重启 Aria2、清空重试都不见好最后才发现问题出在百度网盘的分发链接上——链接本身是有时效的过期之后就算任务还在队列里服务器也不可能再给你数据了。当时我手动干了一件特别机械的事打开浏览器重新请求一遍下载链接复制新地址再用 Aria2 的 RPC 接口把旧链接换掉任务才断点续传成功。整个过程重复五六次之后我决定把这个流程脚本化于是就有了 BaiduAria2Resume。这篇文章把我实际写的脚本思路、核心模块、配置方式和踩坑过程都整理出来适合那些用 Aria2 下载百度网盘文件、又经常遇到“任务挂了但文件还能续传”的朋友参考。1. 先弄清楚百度网盘链接过期到底废掉了哪一段流程1.1 百度网盘的“有效链接”并不是永久地址百度网盘对外分发的下载直链本质上是一条带签名和时效参数的临时地址。服务器在生成链接时会把文件 ID、账号标识、过期时间等信息混入 URL并附上签名参数。CDN 节点收到请求后会先校验签名再检查时间戳任何一项不满足就直接返回 403。有效时长通常只有几十分钟而且不同账号、不同文件、不同分发节点之间可能都有差异不是我们能手动控制的。大多数人第一次遇到这个问题时会误以为是 Aria2 配置坏了。其实把那条失败的 URL 复制到浏览器里用同样的 Cookie 请求一次大概率能看到明显的错误响应比如403 Forbidden、404 Not Found、link expired之类的关键词。这个时候问题不在 Aria2而在上游的链接本身。换一条新链接Aria2 依然能正常工作。1.2 Aria2 面对失效链接时的典型反应Aria2 是个纯粹的下载工具它不关心链接是永久地址还是临时地址只管按照预设的重试策略去请求。链接失效后它的表现大致有三种任务状态变成error错误码通常为22代表 HTTP 返回了非 2xx 状态。任务还显示active但下载进度长时间不再增长日志里出现 TLS 握手中断或EOF异常。开了max-tries的任务会反复重试同一批失效 URL直到重试次数耗尽才停下来。这里有一个关键的好消息Aria2 会把未完成的下载状态写入.aria2控制文件里面记录了文件长度、已下载的块、分块校验信息等。只要你用相同的文件名和相同的保存目录重新添加任务Aria2 会自动读取这个控制文件从已下载的位置继续而不是重新开始。这一条是整个修复方案能成立的基石也是“只换链接不重下”思路的基础。2. BaiduAria2Resume 的设计思路不重下只换链2.1 脚本的整体职责最初我的想法很直接找失败任务把旧链接删掉塞进新链接继续下载。后来实际写代码才发现Aria2 的changeUri接口一次只能替换一个文件索引下的 URI而且旧 URI 列表必须精确匹配稍微差一个字符就会静默失败。对单个文件还好说一批任务几十个文件的时候这种处理方式太脆弱。所以最终脚本的核心流程被我改成了四条线扫描 Aria2 的任务列表找出error、removed或长时间无进度的任务。从任务元信息中解析出文件名和保存目录。用当前账号的登录凭证调用百度网盘下载接口换取新的有效直链。停止旧任务并清理记录再用新链接重新添加任务指定相同的目录和文件名让 Aria2 自动复用.aria2控制文件实现续传。这个思路总结起来就是八个字换链不换任务身份。Aria2 判断是否续传靠的是输出文件的路径和大小只要这两个信息不变化它就会把新任务当成旧任务的延续来看待。2.2 为什么不修原链接非要重新拿一条有些朋友会想URL 过期了那把时间戳参数改长一点不就行了这种做法在大多数场景下是行不通的。下载链接里的签名参数是服务端根据密钥和算法生成的参数之间有关联校验客户端任意修改字段都会让签名失效。与其逆向签名逻辑不如直接再调用一次官方下载接口换取一条全新且有效的链接。这个思路最简单也最接近“官方推荐”的使用方式稳定性要远高于伪造参数。2.3 一个必须说明的前提这里要讲清楚一个边界换取新链接必须要登录态。脚本不是公开链接解析器也不是破解工具而是用你自己账号下有效的 Cookie 去请求合法文件下载信息。换句话说你能下什么文件完全取决于账号本身的权限。如果文件因为分享限制、文件违规等原因被平台禁止下载脚本换多少次链接都没用这点后面也会讲。3. 开工前先配好的环境依赖、登录态和配置文件3.1 运行环境与依赖选择这个脚本我选了 Python 3.8 以上版本第三方库只用了requests其他全部用标准库完成。为什么不用 Shell因为要处理 JSON 数组、URL 编码、状态映射和多任务并发Python 写起来清晰得多后续扩展规则也方便。建议先创建虚拟环境然后安装依赖python3 -m venv baiduresume source baiduresume/bin/activate pip install requestsAria2 侧的启动参数也有要求RPC 必须开启断点续传参数必须保留。贴一下我常用的启动命令aria2c --enable-rpc --rpc-listen-allfalse --rpc-listen-port6800 \ --rpc-secretyour_token \ --save-session/home/user/aria2/aria2.session \ --input-file/home/user/aria2/aria2.session \ --continuetrue--continuetrue是续传的前提--save-session和--input-file可以保证 Aria2 重启后任务列表不丢这两个参数最好都开。3.2 拿到能代表账号身份的 BDUSS百度网盘网页端的登录态用一个叫BDUSS的 Cookie 字段来标识。获取方法是登录百度网盘网页版按 F12 打开开发者工具在任意网络请求的 Cookie 头里找到BDUSS复制到配置文件保存。这个值很长包含账号会话凭证有效期内可以用来请求文件列表和下载信息。BDUSS 本身也有过期时间可能几天也可能几个月取决于你的登录环境和是否开启“保持登录”选项。所以我在脚本里把 Cookie 独立放在一个cookies.txt文件里过期后只改这一处就行不需要动主逻辑。需要特别提醒的是BDUSS 的敏感程度等同于账号密码不要填进仓库不要提交到任何公开平台也不要发给别人。我之前为图方便把它写进了 git 仓库管理的配置文件里后来想想都后怕最后专门用.gitignore把它挡在了版本控制之外。3.3 配置文件结构我给脚本准备了一个config.json放在脚本同目录{ rpc_url: http://127.0.0.1:6800/jsonrpc, rpc_token: your_token, download_dir: /data/downloads, cookies_file: cookies.txt, check_interval: 300, min_file_size: 1048576, exclude_suffix: [tmp, !down, aria2] }几个关键参数说明一下rpc_urlAria2 RPC 地址默认本机 6800 端口。download_dir用于校验任务里的保存目录避免误处理其他下载器创建的任务。check_interval脚本轮询间隔单位秒。我平时用 300也就是五分钟检查一次。min_file_size小于这个字节数的文件不处理比如 1MB 以内的文件直接重新下载也很快没必要再去交换链接。exclude_suffix后缀名黑名单防止把临时下载文件也当成正式任务。3.4 任务过滤规则脚本里有一个判断函数专门决定“哪些任务值得修复”。我总结了三个条件符合任意一个就进入处理流程任务状态是error错误信息里包含403、404、Forbidden、timeout这类关键词。任务状态是waiting但关联的下载链接已经明显过期连续几次轮询都没有产生流量变化。任务状态是active但completedLength长时间没有增长例如 10 分钟以上停滞。过滤规则不能太激进。比如用户主动暂停的任务脚本默认不去动它避免把你手动暂停的大下载任务又给悄悄启动了。4. 核心模块拆解解析任务、拿新链接、替换链接4.1 从 RPC 拉取任务列表脚本通过 JSON-RPC 与 Aria2 通信核心请求就是一个 POST。我封装了一个通用的 RPC 调用函数def rpc_call(rpc_url, token, method, paramsNone): payload { jsonrpc: 2.0, id: baiduresume, method: method, params: [token:{}.format(token)] (params or []) } resp requests.post(rpc_url, jsonpayload, timeout15) resp.raise_for_status() data resp.json() if error in data: raise RuntimeError(data[error]) return data.get(result)获取任务列表时我用aria2.tellWaiting(0, 200)加上aria2.tellActive()的组合分别拿到排队中和活跃中的任务。每个任务里的files[0].uris数组保留了原始链接这段信息后面换链时需要用来做匹配和回显。4.2 解析文件名处理那些特殊字符Aria2 返回的任务信息里有dir字段和files[0].path字段把path减去dir前缀剩下的就是文件名。这个文件名很关键因为它会和百度网盘接口里的文件路径做对应。以下是一个简单解析逻辑import os def extract_name(task): downloads task.get(files, []) if not downloads: return None, None path downloads[0].get(path, ) task_dir task.get(dir, ) if path.startswith(task_dir): name path[len(task_dir):].lstrip(/) else: name os.path.basename(path) return task_dir, name这里容易踩坑的是文件名里带空格、#、等特殊字符。RPC 返回的一般是解码后的原始字符而百度接口要求文件路径重新做 URL 编码。我统一用urllib.parse.quote(name, safe/)编码但注意只编码文件名路径不编码分隔符/。4.3 换取新直链的请求流程百度网盘下载接口的调用逻辑大致分三步提交文件路径拿到下载信息跟随重定向取最终 CDN 地址。我封装成了一个函数from urllib.parse import quote def fetch_dlink(file_path, bduss): url https://pan.baidu.com/api/download params {path: quote(file_path, safe/)} headers { Cookie: BDUSS{}.format(bduss), Referer: https://pan.baidu.com/, User-Agent: Mozilla/5.0 } r requests.get(url, paramsparams, headersheaders, timeout20) data r.json() dlink data.get(dlink) if not dlink: raise RuntimeError(dlink empty: {}.format(data)) follow requests.head(dlink, headersheaders, allow_redirectsTrue, timeout20) return follow.url需要说明的是真实接口在不同账号状态、不同文件类型下返回结构会有差异有些情况还需要先请求一个预检接口拿sign参数。这里给出的是一个简化但能反应核心流程的框架实际对接时按返回内容做兼容就好。判断鉴权失败和单个文件失败很重要我让脚本在返回明确错误码时直接报错并跳过不拖累整批任务。4.4 用 RPC 把新链接替换进任务拿到新链接后脚本根据任务状态选择不同路径。如果任务还处于active优先用aria2.changeUri替换当前 URI如果任务已经报错或已被删除就直接删掉旧任务用aria2.addUri重新添加。重新添加时至少要带上这几个选项options { dir: task_dir, out: file_name, continue: true, allow-overwrite: false, auto-file-renaming: false }这里auto-file-renamingfalse非常关键否则 Aria2 发现目录里有同名文件时会自动把新任务的文件名改成file(1).rar那就不是续传而是新开下载了。删除旧任务时也要注意aria2.remove只针对active/waiting状态对已经error的任务需要用aria2.removeDownloadResult清理否则旧 GID 一直存在下次扫描还会匹配到。4.5 状态与操作映射表我整理了一张表基本就是脚本策略的浓缩版Aria2 状态错误关键词推荐操作注意点active 但进度不动无changeUri 替换当前 URI需要任务里已有旧 URIwaiting无remove addUri先删再添加避免资源占用error403/404/ForbiddenremoveDownloadResult addUri保留 .aria2 文件才能续传paused无不处理或按配置处理暂停可能是用户主动操作每次脚本对任务执行什么操作都会写进操作日志方便后续排查。日志格式包含时间、GID、文件名、旧状态、新状态和操作结果一句话就能看出发生了什么。5. 实际跑起来踩到的坑和排查链路5.1 这个坑叫“BDUSS 有效但个别文件报文件不存在”这个现象是最迷惑人的。同一个 Cookie目录下大部分文件都能正常换到链接偏偏个别文件报“文件不存在”。一开始我以为是文件被删了后来去网盘页面确认文件明明就在那里。排查后发现问题出在path参数里的中文和特殊字符。百度对路径参数比较挑剔部分接口要求 UTF-8 编码部分又要求保留原样。最后的解决方案是统一用quote(path, safe/)并在请求头里固定加Referer: https://pan.baidu.com/所有文件就都正常了。这个问题排查过程中我浪费了整整一下午最后靠手动 curl 一步一请求比对才发现是编码和 Referer 的问题。5.2 changeUri 返回[1, 0]才算成功Aria2 的changeUri会返回一个数组第一个元素是成功删除的 URI 数量第二个是成功添加的 URI 数量。如果你看到[0, 0]说明旧 URI 列表完全没匹配上。这里有一个容易忽略的细节RPC 返回的 URI 字符串和实际保存的可能有细微差异比如末尾多了个/或者某些参数顺序不一致。我的处理是先对所有 URI 做一次strip()再去重最后才传到changeUri。做了这个预处理之后成功率明显提升。如果你发现单个任务换了链但没生效建议先打印出旧 URI 列表肉眼确认一下匹配情况。5.3 丢失的 .aria2 控制文件有一次我删除任务重新添加发现 Aria2 从 0% 开始下载而不是继续 87% 的进度。查了半天才发现之前我手动清理下载目录时把隐藏的.文件名.aria2文件给删了。这个控制文件一旦丢失Aria2 就无法知道哪些块已经下载完成断点续传自然失效。所以在脚本里我加了一个保护逻辑添加新任务前先检查目标目录下是否存在同名.aria2文件如果不存在就写一条 warning 日志提醒用户当前操作可能不是续传而是重下。这个动作只花了十几行代码却避免了好几次误判。5.4 并发换链触发了接口限流最初版本我用线程池并发换取链接一次性把十几个失败任务的链接全部处理。结果处理到第五六个接口开始返回错误码连续失败几次后整个脚本就崩了。后来我把并发数压到 1每处理一个任务后 sleep 2 到 3 秒就再也没触发过限流。如果你要处理几百个文件建议在脚本里加上一个--interval参数默认 2 秒做一次请求间隔。这个频率不会显著拖慢总体流程但能稳定避免被临时限流。5.5 排查异常时的固定链路整个调试过程中我习惯按固定顺序去排查问题遇到任何异常都先从这四步走看 Aria2 日志确认任务的具体错误码和时间点。手动把任务里的旧 URL 复制出来用 curl 带 Cookie 请求一次确认链接是否真的失效。手动调用一次换取新链接的接口观察返回内容确定是 Cookie 问题还是路径问题。如果新链接能正常下载问题就出在 RPC 替换逻辑如果新链接也不能下载问题大概率在 Cookie 或文件路径上。这个顺序能覆盖绝大多数异常场景。如果你在自己实现类似功能时遇到问题我建议也按这个链路来别一上来就改代码。6. 我的固定使用方式以及这个脚本的边界现在我的用法基本固定成了两个场景。第一个场景是手动救急。满队列失败的时候直接执行python baidu_aria2_resume.py --fix-error脚本会把失败任务挑出来换链恢复整个过程十几秒完成。这个操作适合下载过程中临时出错、不想等待自动轮询的情况。第二个场景是后台定时检查。我把它挂到系统定时任务里每 5 分钟检查一次只处理满足最小文件大小且确实失败的任务。这样睡觉前挂一批任务半夜有链接过期脚本会自动换链续传早上下载还是完整跑完的体验上确实省心很多。但要说清楚这个脚本不是万能的。它绕不开的核心限制是你账号本身有没有权限下载该文件。如果文件已经被限制下载脚本会明确报错而不是死循环重试。另外下载速度受账号状态、网络环境和 Aria2 参数影响换链只能解决“链接过期”这一个环节不能解决所有下载异常。最后分享一个我自己很受用的小习惯脚本日志和 Aria2 日志输出到同一个目录文件名加上日期。排查问题时两个日志对着看很快就能定位是脚本问题还是下载工具问题。如果你打算长期用这类自动换链方案这个习惯建议从一开始就建立起来。本文还有配套的精品资源点击获取
Aria2下载百度网盘链接过期？自动换链续传脚本实战
简介百度网盘下载链接有时效性限制配合aria2下载时任务常因链接过期而中断这一问题困扰着众多重度用户。这套BaiduAria2Resume工具采用Python编写可在后台持续运行自动检测并修复Aria2中失效的百度云链接无需人工干预即可保持下载任务稳定进行。资源共6个文件包括3个Python脚本分别负责主流程控制、任务管理、登录验证、1份说明文档、1张效果截图及1个配置文件压缩包仅103KB非常轻量。脚本支持通过命令行灵活配置用户名、密码、端口等参数登录部分参考了pan-baidu-download项目可靠性有保障配合BaiduExporter将百度云任务导入aria2再通过webui-aria2进行管理可让百度网盘下载接近满速。对于使用aria2下载百度云资源并深受链接时效问题困扰的Python用户而言这份工具提供了直接有效的解决方案目前已有1252人学习下载。 真正让我决定写 BaiduAria2Resume 这个脚本的是一次下载一个 30GB 压缩包的体验。Aria2 已经跑到 87%突然一口气报了403 Forbidden任务整整齐齐全部停在原地。我一开始以为是网络波动重启 Aria2、清空重试都不见好最后才发现问题出在百度网盘的分发链接上——链接本身是有时效的过期之后就算任务还在队列里服务器也不可能再给你数据了。当时我手动干了一件特别机械的事打开浏览器重新请求一遍下载链接复制新地址再用 Aria2 的 RPC 接口把旧链接换掉任务才断点续传成功。整个过程重复五六次之后我决定把这个流程脚本化于是就有了 BaiduAria2Resume。这篇文章把我实际写的脚本思路、核心模块、配置方式和踩坑过程都整理出来适合那些用 Aria2 下载百度网盘文件、又经常遇到“任务挂了但文件还能续传”的朋友参考。1. 先弄清楚百度网盘链接过期到底废掉了哪一段流程1.1 百度网盘的“有效链接”并不是永久地址百度网盘对外分发的下载直链本质上是一条带签名和时效参数的临时地址。服务器在生成链接时会把文件 ID、账号标识、过期时间等信息混入 URL并附上签名参数。CDN 节点收到请求后会先校验签名再检查时间戳任何一项不满足就直接返回 403。有效时长通常只有几十分钟而且不同账号、不同文件、不同分发节点之间可能都有差异不是我们能手动控制的。大多数人第一次遇到这个问题时会误以为是 Aria2 配置坏了。其实把那条失败的 URL 复制到浏览器里用同样的 Cookie 请求一次大概率能看到明显的错误响应比如403 Forbidden、404 Not Found、link expired之类的关键词。这个时候问题不在 Aria2而在上游的链接本身。换一条新链接Aria2 依然能正常工作。1.2 Aria2 面对失效链接时的典型反应Aria2 是个纯粹的下载工具它不关心链接是永久地址还是临时地址只管按照预设的重试策略去请求。链接失效后它的表现大致有三种任务状态变成error错误码通常为22代表 HTTP 返回了非 2xx 状态。任务还显示active但下载进度长时间不再增长日志里出现 TLS 握手中断或EOF异常。开了max-tries的任务会反复重试同一批失效 URL直到重试次数耗尽才停下来。这里有一个关键的好消息Aria2 会把未完成的下载状态写入.aria2控制文件里面记录了文件长度、已下载的块、分块校验信息等。只要你用相同的文件名和相同的保存目录重新添加任务Aria2 会自动读取这个控制文件从已下载的位置继续而不是重新开始。这一条是整个修复方案能成立的基石也是“只换链接不重下”思路的基础。2. BaiduAria2Resume 的设计思路不重下只换链2.1 脚本的整体职责最初我的想法很直接找失败任务把旧链接删掉塞进新链接继续下载。后来实际写代码才发现Aria2 的changeUri接口一次只能替换一个文件索引下的 URI而且旧 URI 列表必须精确匹配稍微差一个字符就会静默失败。对单个文件还好说一批任务几十个文件的时候这种处理方式太脆弱。所以最终脚本的核心流程被我改成了四条线扫描 Aria2 的任务列表找出error、removed或长时间无进度的任务。从任务元信息中解析出文件名和保存目录。用当前账号的登录凭证调用百度网盘下载接口换取新的有效直链。停止旧任务并清理记录再用新链接重新添加任务指定相同的目录和文件名让 Aria2 自动复用.aria2控制文件实现续传。这个思路总结起来就是八个字换链不换任务身份。Aria2 判断是否续传靠的是输出文件的路径和大小只要这两个信息不变化它就会把新任务当成旧任务的延续来看待。2.2 为什么不修原链接非要重新拿一条有些朋友会想URL 过期了那把时间戳参数改长一点不就行了这种做法在大多数场景下是行不通的。下载链接里的签名参数是服务端根据密钥和算法生成的参数之间有关联校验客户端任意修改字段都会让签名失效。与其逆向签名逻辑不如直接再调用一次官方下载接口换取一条全新且有效的链接。这个思路最简单也最接近“官方推荐”的使用方式稳定性要远高于伪造参数。2.3 一个必须说明的前提这里要讲清楚一个边界换取新链接必须要登录态。脚本不是公开链接解析器也不是破解工具而是用你自己账号下有效的 Cookie 去请求合法文件下载信息。换句话说你能下什么文件完全取决于账号本身的权限。如果文件因为分享限制、文件违规等原因被平台禁止下载脚本换多少次链接都没用这点后面也会讲。3. 开工前先配好的环境依赖、登录态和配置文件3.1 运行环境与依赖选择这个脚本我选了 Python 3.8 以上版本第三方库只用了requests其他全部用标准库完成。为什么不用 Shell因为要处理 JSON 数组、URL 编码、状态映射和多任务并发Python 写起来清晰得多后续扩展规则也方便。建议先创建虚拟环境然后安装依赖python3 -m venv baiduresume source baiduresume/bin/activate pip install requestsAria2 侧的启动参数也有要求RPC 必须开启断点续传参数必须保留。贴一下我常用的启动命令aria2c --enable-rpc --rpc-listen-allfalse --rpc-listen-port6800 \ --rpc-secretyour_token \ --save-session/home/user/aria2/aria2.session \ --input-file/home/user/aria2/aria2.session \ --continuetrue--continuetrue是续传的前提--save-session和--input-file可以保证 Aria2 重启后任务列表不丢这两个参数最好都开。3.2 拿到能代表账号身份的 BDUSS百度网盘网页端的登录态用一个叫BDUSS的 Cookie 字段来标识。获取方法是登录百度网盘网页版按 F12 打开开发者工具在任意网络请求的 Cookie 头里找到BDUSS复制到配置文件保存。这个值很长包含账号会话凭证有效期内可以用来请求文件列表和下载信息。BDUSS 本身也有过期时间可能几天也可能几个月取决于你的登录环境和是否开启“保持登录”选项。所以我在脚本里把 Cookie 独立放在一个cookies.txt文件里过期后只改这一处就行不需要动主逻辑。需要特别提醒的是BDUSS 的敏感程度等同于账号密码不要填进仓库不要提交到任何公开平台也不要发给别人。我之前为图方便把它写进了 git 仓库管理的配置文件里后来想想都后怕最后专门用.gitignore把它挡在了版本控制之外。3.3 配置文件结构我给脚本准备了一个config.json放在脚本同目录{ rpc_url: http://127.0.0.1:6800/jsonrpc, rpc_token: your_token, download_dir: /data/downloads, cookies_file: cookies.txt, check_interval: 300, min_file_size: 1048576, exclude_suffix: [tmp, !down, aria2] }几个关键参数说明一下rpc_urlAria2 RPC 地址默认本机 6800 端口。download_dir用于校验任务里的保存目录避免误处理其他下载器创建的任务。check_interval脚本轮询间隔单位秒。我平时用 300也就是五分钟检查一次。min_file_size小于这个字节数的文件不处理比如 1MB 以内的文件直接重新下载也很快没必要再去交换链接。exclude_suffix后缀名黑名单防止把临时下载文件也当成正式任务。3.4 任务过滤规则脚本里有一个判断函数专门决定“哪些任务值得修复”。我总结了三个条件符合任意一个就进入处理流程任务状态是error错误信息里包含403、404、Forbidden、timeout这类关键词。任务状态是waiting但关联的下载链接已经明显过期连续几次轮询都没有产生流量变化。任务状态是active但completedLength长时间没有增长例如 10 分钟以上停滞。过滤规则不能太激进。比如用户主动暂停的任务脚本默认不去动它避免把你手动暂停的大下载任务又给悄悄启动了。4. 核心模块拆解解析任务、拿新链接、替换链接4.1 从 RPC 拉取任务列表脚本通过 JSON-RPC 与 Aria2 通信核心请求就是一个 POST。我封装了一个通用的 RPC 调用函数def rpc_call(rpc_url, token, method, paramsNone): payload { jsonrpc: 2.0, id: baiduresume, method: method, params: [token:{}.format(token)] (params or []) } resp requests.post(rpc_url, jsonpayload, timeout15) resp.raise_for_status() data resp.json() if error in data: raise RuntimeError(data[error]) return data.get(result)获取任务列表时我用aria2.tellWaiting(0, 200)加上aria2.tellActive()的组合分别拿到排队中和活跃中的任务。每个任务里的files[0].uris数组保留了原始链接这段信息后面换链时需要用来做匹配和回显。4.2 解析文件名处理那些特殊字符Aria2 返回的任务信息里有dir字段和files[0].path字段把path减去dir前缀剩下的就是文件名。这个文件名很关键因为它会和百度网盘接口里的文件路径做对应。以下是一个简单解析逻辑import os def extract_name(task): downloads task.get(files, []) if not downloads: return None, None path downloads[0].get(path, ) task_dir task.get(dir, ) if path.startswith(task_dir): name path[len(task_dir):].lstrip(/) else: name os.path.basename(path) return task_dir, name这里容易踩坑的是文件名里带空格、#、等特殊字符。RPC 返回的一般是解码后的原始字符而百度接口要求文件路径重新做 URL 编码。我统一用urllib.parse.quote(name, safe/)编码但注意只编码文件名路径不编码分隔符/。4.3 换取新直链的请求流程百度网盘下载接口的调用逻辑大致分三步提交文件路径拿到下载信息跟随重定向取最终 CDN 地址。我封装成了一个函数from urllib.parse import quote def fetch_dlink(file_path, bduss): url https://pan.baidu.com/api/download params {path: quote(file_path, safe/)} headers { Cookie: BDUSS{}.format(bduss), Referer: https://pan.baidu.com/, User-Agent: Mozilla/5.0 } r requests.get(url, paramsparams, headersheaders, timeout20) data r.json() dlink data.get(dlink) if not dlink: raise RuntimeError(dlink empty: {}.format(data)) follow requests.head(dlink, headersheaders, allow_redirectsTrue, timeout20) return follow.url需要说明的是真实接口在不同账号状态、不同文件类型下返回结构会有差异有些情况还需要先请求一个预检接口拿sign参数。这里给出的是一个简化但能反应核心流程的框架实际对接时按返回内容做兼容就好。判断鉴权失败和单个文件失败很重要我让脚本在返回明确错误码时直接报错并跳过不拖累整批任务。4.4 用 RPC 把新链接替换进任务拿到新链接后脚本根据任务状态选择不同路径。如果任务还处于active优先用aria2.changeUri替换当前 URI如果任务已经报错或已被删除就直接删掉旧任务用aria2.addUri重新添加。重新添加时至少要带上这几个选项options { dir: task_dir, out: file_name, continue: true, allow-overwrite: false, auto-file-renaming: false }这里auto-file-renamingfalse非常关键否则 Aria2 发现目录里有同名文件时会自动把新任务的文件名改成file(1).rar那就不是续传而是新开下载了。删除旧任务时也要注意aria2.remove只针对active/waiting状态对已经error的任务需要用aria2.removeDownloadResult清理否则旧 GID 一直存在下次扫描还会匹配到。4.5 状态与操作映射表我整理了一张表基本就是脚本策略的浓缩版Aria2 状态错误关键词推荐操作注意点active 但进度不动无changeUri 替换当前 URI需要任务里已有旧 URIwaiting无remove addUri先删再添加避免资源占用error403/404/ForbiddenremoveDownloadResult addUri保留 .aria2 文件才能续传paused无不处理或按配置处理暂停可能是用户主动操作每次脚本对任务执行什么操作都会写进操作日志方便后续排查。日志格式包含时间、GID、文件名、旧状态、新状态和操作结果一句话就能看出发生了什么。5. 实际跑起来踩到的坑和排查链路5.1 这个坑叫“BDUSS 有效但个别文件报文件不存在”这个现象是最迷惑人的。同一个 Cookie目录下大部分文件都能正常换到链接偏偏个别文件报“文件不存在”。一开始我以为是文件被删了后来去网盘页面确认文件明明就在那里。排查后发现问题出在path参数里的中文和特殊字符。百度对路径参数比较挑剔部分接口要求 UTF-8 编码部分又要求保留原样。最后的解决方案是统一用quote(path, safe/)并在请求头里固定加Referer: https://pan.baidu.com/所有文件就都正常了。这个问题排查过程中我浪费了整整一下午最后靠手动 curl 一步一请求比对才发现是编码和 Referer 的问题。5.2 changeUri 返回[1, 0]才算成功Aria2 的changeUri会返回一个数组第一个元素是成功删除的 URI 数量第二个是成功添加的 URI 数量。如果你看到[0, 0]说明旧 URI 列表完全没匹配上。这里有一个容易忽略的细节RPC 返回的 URI 字符串和实际保存的可能有细微差异比如末尾多了个/或者某些参数顺序不一致。我的处理是先对所有 URI 做一次strip()再去重最后才传到changeUri。做了这个预处理之后成功率明显提升。如果你发现单个任务换了链但没生效建议先打印出旧 URI 列表肉眼确认一下匹配情况。5.3 丢失的 .aria2 控制文件有一次我删除任务重新添加发现 Aria2 从 0% 开始下载而不是继续 87% 的进度。查了半天才发现之前我手动清理下载目录时把隐藏的.文件名.aria2文件给删了。这个控制文件一旦丢失Aria2 就无法知道哪些块已经下载完成断点续传自然失效。所以在脚本里我加了一个保护逻辑添加新任务前先检查目标目录下是否存在同名.aria2文件如果不存在就写一条 warning 日志提醒用户当前操作可能不是续传而是重下。这个动作只花了十几行代码却避免了好几次误判。5.4 并发换链触发了接口限流最初版本我用线程池并发换取链接一次性把十几个失败任务的链接全部处理。结果处理到第五六个接口开始返回错误码连续失败几次后整个脚本就崩了。后来我把并发数压到 1每处理一个任务后 sleep 2 到 3 秒就再也没触发过限流。如果你要处理几百个文件建议在脚本里加上一个--interval参数默认 2 秒做一次请求间隔。这个频率不会显著拖慢总体流程但能稳定避免被临时限流。5.5 排查异常时的固定链路整个调试过程中我习惯按固定顺序去排查问题遇到任何异常都先从这四步走看 Aria2 日志确认任务的具体错误码和时间点。手动把任务里的旧 URL 复制出来用 curl 带 Cookie 请求一次确认链接是否真的失效。手动调用一次换取新链接的接口观察返回内容确定是 Cookie 问题还是路径问题。如果新链接能正常下载问题就出在 RPC 替换逻辑如果新链接也不能下载问题大概率在 Cookie 或文件路径上。这个顺序能覆盖绝大多数异常场景。如果你在自己实现类似功能时遇到问题我建议也按这个链路来别一上来就改代码。6. 我的固定使用方式以及这个脚本的边界现在我的用法基本固定成了两个场景。第一个场景是手动救急。满队列失败的时候直接执行python baidu_aria2_resume.py --fix-error脚本会把失败任务挑出来换链恢复整个过程十几秒完成。这个操作适合下载过程中临时出错、不想等待自动轮询的情况。第二个场景是后台定时检查。我把它挂到系统定时任务里每 5 分钟检查一次只处理满足最小文件大小且确实失败的任务。这样睡觉前挂一批任务半夜有链接过期脚本会自动换链续传早上下载还是完整跑完的体验上确实省心很多。但要说清楚这个脚本不是万能的。它绕不开的核心限制是你账号本身有没有权限下载该文件。如果文件已经被限制下载脚本会明确报错而不是死循环重试。另外下载速度受账号状态、网络环境和 Aria2 参数影响换链只能解决“链接过期”这一个环节不能解决所有下载异常。最后分享一个我自己很受用的小习惯脚本日志和 Aria2 日志输出到同一个目录文件名加上日期。排查问题时两个日志对着看很快就能定位是脚本问题还是下载工具问题。如果你打算长期用这类自动换链方案这个习惯建议从一开始就建立起来。本文还有配套的精品资源点击获取
