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，例如：
bash
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://localhosthttps://localhosthttp://localhost/http://127.0.0.1的任意端口
独立部署时可用环境变量 SP_API_ALLOWED_ORIGINS 覆盖。
网络代理
在 设置 → 网络与连接 → 网络代理 中启用 HTTP / HTTPS 代理后，前端会以 proxy=protocol://server:port 查询参数附加到内置逆向 API 的网易云请求上，由 Enhanced API 消费。
独立部署服务
仓库 API/ 目录提供基于 Fastify 的同源服务，可用于电脑端调试或给局域网内其他设备提供 API。
运行
bash
# 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。若需指向外部服务：
- 进入 设置 → 网络与连接 → 网易云 API 地址；
- 填写形如
http://<你的电脑IP>:1145/api/netease的地址（需包含协议与/api/netease这一层）； - 点击 测试 API，会探测
/login/qr/key接口验证连通性。
地址层级
测试失败时请检查是否漏写了 /api/netease 后缀——地址需要填写到这一层，而不是服务根地址。
请求路由优先级
前端请求的 base URL 解析顺序：
- 用户设置的 网易云 API 地址（
apiBaseUrl）； - Android 环境回退到内置
http://127.0.0.1:1145/api/netease。
使用示例
cURL
bash
# 服务索引
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
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());注意事项
- 内置 API 仅在应用进程存活时可用，应用被系统杀死后需重新启动应用；
- 内置 API 只监听
127.0.0.1，不对外网暴露；独立部署默认监听0.0.0.0，请注意防火墙； - 部分接口（歌单、云盘、签到等）需要登录后才能使用；
- 请勿高频轮询播放状态接口，实时进度请监听应用内事件；
- 解锁 / 逆向接口仅供个人学习研究使用，请勿用于商业及非法用途。