API 接口文档

概述

SPlayer for Android 通过 nodejs-mobile-cordova 在设备内嵌了一个完整的云音乐 API 服务（基于 NeteaseCloudMusicApiEnhanced），无需外部服务器即可离线使用。同时仓库也提供可独立部署的同源服务，供局域网其他设备或调试使用。

内置 API（设备上）

基础信息

• 监听地址: http://127.0.0.1:1145
• API 前缀: /api/netease
• 响应格式: JSON（与上游 Enhanced API 一致）

启动与自愈机制

阶段	行为
启动	应用启动时等待 deviceready 与 window.nodejs（15s 超时），启动内嵌 Node 运行时
就绪	内嵌服务通过 cordova-bridge 发送 embedded-api-ready，与 500ms 间隔的健康轮询竞速（45s 上限）
健康检查	每 30s 请求 GET /api；连续 2 次失败即提示「内置 API 服务异常，正在自动恢复...」并自动重启
网络恢复	前端请求出现网络错误时也会触发内置 API 重启

路由

路由	方法	说明
GET /api	GET	服务索引，返回 { name: "SPlayer API", list: [...] }
GET /api/netease	GET	上游 Enhanced API 信息
`GET	POST /api/netease/*`	GET / POST
GET /api/netease/lyric/ttml?id=	GET	代理 AMLL TTML 歌词库（默认 https://amlldb.bikonoo.com/ncm-lyrics/%s.ttml）
其余路径	—	返回 404 { "error": "API not found" }

接口路径会自动转换为 kebab-case，例如：

GET /api/netease/login/cellphone?phone=xxx&password=xxx
GET /api/netease/user/playlist?uid=xxx
GET /api/netease/song/detail?ids=xxx
GET /api/netease/song/url/v1?id=xxx&level=exhigh

完整接口列表参考 NeteaseCloudMusicApi Enhanced 文档。

登录态传递

WebView 侧通过自定义请求头 X-SPlayer-Cookie 携带网易云登录 Cookie，仅接受来自白名单 Origin 的请求。原生播放层（PlaybackUrlResolver）也会直接调用内置 API 的 /song/url/v1 解析播放地址，因此 WebView 被系统冻结时后台仍能切歌。

CORS 白名单

默认允许：

• capacitor://localhost
• https://localhost
• http://localhost / http://127.0.0.1 的任意端口

独立部署时可用环境变量 SP_API_ALLOWED_ORIGINS 覆盖。

网络代理

在 设置 → 网络与连接 → 网络代理 中启用 HTTP / HTTPS 代理后，前端会以 proxy=protocol://server:port 查询参数附加到内置逆向 API 的网易云请求上，由 Enhanced API 消费。

独立部署服务

仓库 API/ 目录提供基于 Fastify 的同源服务，可用于电脑端调试或给局域网内其他设备提供 API。

运行

# Windows
API\start-api.bat

# 或任意平台
pnpm api:start

环境变量

变量	默认值	说明
SP_API_HOST	0.0.0.0	监听地址
SP_API_PORT	1145	监听端口（亦读取 VITE_SERVER_PORT）
SP_AMLL_DB_SERVER	官方 TTML 库	AMLL TTML 歌词库地址
SP_API_ALLOWED_ORIGINS	见上文	覆盖 CORS 白名单

在 Android 版中使用外部 API

默认情况下 Android 版使用内置 API。若需指向外部服务：

1. 进入 设置 → 网络与连接 → 网易云 API 地址；
2. 填写形如 http://<你的电脑IP>:1145/api/netease 的地址（需包含协议与 /api/netease 这一层）；
3. 点击 测试 API，会探测 /login/qr/key 接口验证连通性。

地址层级

测试失败时请检查是否漏写了 /api/netease 后缀——地址需要填写到这一层，而不是服务根地址。

请求路由优先级

前端请求的 base URL 解析顺序：

1. 用户设置的 网易云 API 地址（apiBaseUrl）；
2. Android 环境回退到内置 http://127.0.0.1:1145/api/netease。

使用示例

cURL

# 服务索引
curl http://127.0.0.1:1145/api

# 歌曲详情
curl "http://127.0.0.1:1145/api/netease/song/detail?ids=123456"

# 播放地址
curl "http://127.0.0.1:1145/api/netease/song/url/v1?id=123456&level=exhigh"

JavaScript

const res = await fetch("http://127.0.0.1:1145/api/netease/song/detail?ids=123456", {
  headers: { "X-SPlayer-Cookie": document.cookie },
});
console.log(await res.json());

注意事项

1. 内置 API 仅在应用进程存活时可用，应用被系统杀死后需重新启动应用；
2. 内置 API 只监听 127.0.0.1，不对外网暴露；独立部署默认监听 0.0.0.0，请注意防火墙；
3. 部分接口（歌单、云盘、签到等）需要登录后才能使用；
4. 请勿高频轮询播放状态接口，实时进度请监听应用内事件；
5. 解锁 / 逆向接口仅供个人学习研究使用，请勿用于商业及非法用途。