AList 直链播放失败排查

更新于 2026 年 8 月 31 日 · 适用于 AList 与 OpenList

先做一次分诊

（还没接上、在找怎么填地址的，先看AList 用什么播放器。）AList 的报错有个共同特点：字面意思往往指向错误的方向。403 的字面意思是「没权限」，但九成情况下跟权限无关；「密码错误」的提示背后可能压根不是密码的事。所以别按报错文字去猜，按下面这张表对症状：

还有一个通用手法能省掉一半排查时间：用手机浏览器打开 AList 网页版，在同一个 Wi-Fi 下点开同一个文件。网页版能播 = 服务端和网络都没问题，锅在客户端；网页版也播不了 = 服务端配置或网盘的问题，换客户端没用。

症状一：地址变成了 127.0.0.1

现象。目录列得出来，海报也刮得到，一点播放就失败。如果客户端会把失败地址显示出来，你会看到里面赫然写着 http://127.0.0.1:5244/p/…。有些客户端不显示地址，症状就退化成一句没头没脑的「无法连接」或者一直转圈。

原因。这是整个 AList 生态里最常见的一个部署失误：给 AList 套了反向代理（Nginx、Caddy、宝塔、frp 都算），却没有在后台把「站点 URL」（site_url）改成实际访问地址。AList 在拼接 /p 代理地址时用的就是这个配置项——它拼出来的是「AList 自己怎么看自己」，而不是「你的手机怎么访问它」。默认值指向本机，于是手机拿到一个指向自己的地址，当然连不上。

为什么网页版不受影响？因为浏览器打开的页面里，很多资源是相对路径，而视频播放那一步偏偏用到了这个拼出来的绝对地址。所以典型症状是「电脑上网页看着一切正常，手机客户端就是播不了」。

修法有两种。第一种是治本：在 AList 后台把站点 URL 改成你实际访问的地址（例如 https://alist.example.com，或者内网的 http://192.168.1.5:5244），改完所有客户端一起受益，也不用再想这件事。第二种是客户端侧兜底：把返回地址里 /p、/d 这类代理路径的主机名，替换成用户填写的那个服务器地址。Vela Player 做的就是这一层——但只换代理路径，网盘 CDN 直链原样保留、一个字节都不动。这个边界很要紧：CDN 直链的域名是网盘自己签发的，签名和域名绑在一起，改掉主机名等于把一条本来能用的链改废。

还有一个隐蔽后果：站点 URL 填的是外网域名、而手机此刻就在家里的局域网内时，流量会绕出公网再回来，白白多一跳。

症状二：403

403 是最容易误判的一个，因为它至少对应三件完全不同的事。按可能性从高到低排：

分支 A：直链过期了

现象。刚扫完媒体库的那天一切正常，第二天点进去全是 403；或者一部片子暂停了一两个小时再回来接着看，就播不动了，退出重进又好了。

原因。网盘的直链是带时效签名的。阿里云盘的签名约 4 小时过期，夸克、115 更短。这个时间由网盘服务端决定，AList 改不了，客户端也改不了。

修法。这条其实无须「修」，需要的是客户端行为正确：直链绝对不能入库，每次播放前必须现取一次。扫描时顺手把地址存进数据库、下次直接拿来用，第二天必然 403——这是个很典型的实现偷懒。现取还有个附带好处：下载中途断流时能自动续上，因为每一轮重试都会重新要一条新链。如果你遇到的是「重启 App 就好了」这种规律，基本可以确认客户端缓存了直链。

分支 B：客户端把直链传给了别的程序

现象。在 AList 客户端里能播，复制链接丢给外部播放器就 403；或者用了「用其他应用打开」之类的功能后失败。

原因。部分网盘的直链签名绑着取链那一刻的请求头（Cookie、Referer、User-Agent），不是光有地址就能用。夸克是最典型的：带全 Cookie + Referer + User-Agent 时服务端回 206 正常吐流，什么头都不带或者只带 UA 就回 412 Precondition Failed。头带了但格式发畸形，回的是 400 Bad Request——这两个码要分清：412 是头没带全，400 是头带了但发错了。

修法。不要跨程序传直链，让同一个客户端从取链到播放一条龙走完。Vela Player 内部把播放要带的头统一成一份，AVPlayer、软解引擎、转码桥、探针四条路都带同一套——只在其中一条上带的话，症状会诡异成「系统播放器能放，一切软解就 403」。

分支 C：真的是权限问题

现象。某个特定目录一直 403，别的目录都正常；或者换成游客登录之后到处 403。

原因与修法。这一档才是 403 的字面意思。检查这个账号在 AList 里对该路径有没有读取权限；用游客身份连的话，检查后台有没有开放游客访问、开放到了哪些路径。开了两步验证的实例还有一层：账号密码那条路走不通，得改用令牌，见 AList 开了两步验证怎么登录第三方客户端。

症状三：500 storage not found

现象。根目录列得出来，各个挂载点的名字也都在，一点进某个挂载点就报 500 storage not found。有时是全部挂载点都进不去，有时只有某几个。

原因。AList 的文件列表里有个 path 字段，它是驱动内的物理路径——比如某个存储的网盘内根目录设成了 /media，那么虚拟路径 /lab/Anime 这一项返回的 path 是 /media/Anime。客户端如果直接拿这个字段回问 fs/list，服务端在虚拟目录树里找不到 /media/Anime 这个挂载点，就回 500 storage not found。

为什么有的挂载点没事？因为当挂载路径和网盘内根目录恰好相同时（都填 /），两个路径正好重合，bug 被掩盖了。所以这个坑的典型表现是「有的存储能进，有的不能进」，看起来像是某个网盘出了问题，其实跟网盘无关。

修法。这是客户端实现问题，服务端改不了。正确做法是客户端按用户实际浏览的层级自己拼虚拟路径，不信 path 字段。（新版本加了 virtual_path，但老实例上没有，客户端不能依赖它。）遇到这个报错，换一个客户端试一下就能确认是不是这个原因。想绕过去的话还有个临时办法：给这个存储的挂载路径和网盘内根目录填成一样的，让两个路径重合。

症状四：密码明明是对的，却提示失败

现象。报错语焉不详——「连接失败」「解析错误」「未知错误」，甚至是一句空指针。但你确信地址能通、密码没错，浏览器登进去也一切正常。

原因。AList 有个很容易踩的特性：请求失败时它照样返回 HTTP 200，真正的错误码藏在响应体的 code 字段里。只看 HTTP 状态码的客户端会把密码错误、令牌过期、路径不存在统统判成「成功」，一路往下走到解析数据那一步才炸——而那时候抛出来的是解析层的错误，跟真实原因已经隔了十万八千里。所以你看到的报错文本，很可能只是「JSON 里没有我要的字段」换了个说法。

修法。遇到语焉不详的失败，优先怀疑认证，而不是网络。按顺序排一遍：用户名和密码有没有多敲空格（从密码管理器粘贴时常带尾随空格）；实例是不是开了两步验证（那就必须改用令牌）；令牌是不是在后台被刷新过；游客模式下该路径是否开放。把这几条排掉之后再去怀疑网络。

其他常见问题

能播，但一直缓冲

先判断这条流走的是直发还是代理。raw_url 回的是网盘 CDN 时，播放器直接从网盘拉流，速度取决于网盘本身和你的宽带；回的是 /p 代理时，所有字节都要穿过 AList 那台机器，上限就是它的上行带宽——中转机放在软路由或低配小主机上时，这一层几乎必然是瓶颈。夸克视频与本地存储在服务端就是硬编码走代理的，这一档绕不开。原理见 WebDAV 还是原生 API。

换成 https 之后就连不上了

先确认证书。自签证书、证书过期、证书域名和访问域名不一致，都会被系统的网络策略拦下，而报错常常只是一句「无法建立安全连接」。反过来，只开明文 HTTP 也可能被系统策略拦住。Vela Player 会把这类错误码译成人话（证书自签 / 明文 HTTP 被系统拦 / 凭据过期），照着提示改就行。

目录能进、播放却提示格式不支持

这跟 AList 无关了，是解码那一侧的事。系统硬解覆盖 H.264、HEVC 8/10bit，冷门编码（RMVB / RealVideo、VC-1、MPEG-2、MXF、OGM 等）会自动切到内置软解引擎接管，界面上还是同一个播放器。如果某个客户端在这类片源上直接报「格式不支持」，说明它没有软解兜底。

怎么快速确认是客户端的锅还是服务端的锅

三步：① 手机浏览器打开 AList 网页版，同一个文件能不能播；② 换一个客户端连同一个地址；③ 把 AList 的日志翻出来看这次请求到底进没进来。第一步就失败的，不用再折腾客户端了。