自建一套网易云音乐接口服务（api-enhanced）

给自己的歌单工具、桌面播放器或氛围电台取网易云的歌曲、歌词和评论数据，通常会卡在同一处：官方没有面向个人开发者的公开接口，能走的路径都要自己处理 eapi、weapi、xeapi 这几套加密参数。api-enhanced 把这一层封装成了可以直接调用的接口。

api-enhanced 是一套用 JavaScript 写的网易云音乐第三方 HTTP API 服务，输入接口路径和参数，输出 JSON 数据，面向需要自建音乐数据服务的开发者。

它可以用三种形态跑起来：本机 node app.js 起一个 HTTP 服务、用 Docker 镜像 moefurina/ncm-api 部署、或者在 Vercel 和腾讯云 Serverless 上托一份，同时也发布了 npm 包 @neteasecloudmusicapienhanced/api，可以在 Node.js 项目里直接引入调用，仓库里带了 TypeScript 类型定义。项目地址在 NeteaseCloudMusicApiEnhanced/api-enhanced，采用 MIT 许可证，主要语言是 JavaScript（占比 62.0%，其余 37.9% 是 HTML）。

五分钟先跑通

README 写明的环境要求是 Node.js 22 及以上，依赖管理推荐用 pnpm。安装三步：

git clone https://github.com/neteasecloudmusicapienhanced/api-enhanced.git
cd api-enhanced
pnpm i

装完依赖直接起服务，默认端口 3000：

# 默认端口 3000
node app.js

# 指定端口（如 4000）
PORT=4000 node app.js  # Mac/Linux
set PORT=4000 && node app.js  # Windows

不想装 Node.js，用 Docker 镜像一步到位：

docker pull moefurina/ncm-api:latest

docker run -d -p 3000:3000 --name ncm-api moefurina/ncm-api:latest

README 对 Docker 场景有一条专门提醒：容器里发请求会检查 http_proxy、https_proxy、HTTP_PROXY、HTTPS_PROXY、no_proxy、NO_PROXY 这几个环境变量，如果它们指向的代理不可用就会报错，可以在 docker run 时加 -e http_proxy= 这类参数把它们置空。

最短的接口调用示例是 npm 包的用法，README 里给的是手机号登录加云盘查询：

const {
  login_cellphone,
  user_cloud,
} = require('@neteasecloudmusicapienhanced/api')
async function main() {
  const result = await login_cellphone({ phone: '手机号', password: '密码' })
  console.log(result)
  const result2 = await user_cloud({ cookie: result.body.cookie })
  console.log(result2.body)
}
main()

走服务方式的话，用浏览器或 curl 访问 http://localhost:3000/login/cellphone?phone=手机号&password=密码 这一类路径就能拿到 JSON。README 建议把 cookie 这类敏感信息放到部署平台的环境变量里，不要写死在代码中。

跑通之后你会得到什么

终端里会看到服务监听的输出，3000 端口上跑着一个 Express 服务。每个请求返回一段 JSON，里面通常带 code 和 body 两个字段。登录类接口返回的 body.cookie 是后续调用的凭证，把它带上就能查到用户歌单、播放记录、云盘这些需要登录态的数据。

用 npm 包引入时拿到的是 Promise，res.body 里是同一份数据形态，不需要起 HTTP 服务。日志和报错都落在终端里，README 没有说明有独立的结果文件或报告目录。

接口列表与参数说明在在线文档站 http://docs-neteasecloudmusicapi.focalors.ltd/ 和 https://neteasecloudmusicapienhanced.js.org/ 上，调用前 README 要求先读文档里的「调用前须知」部分。要往项目里补新接口，README 指向了一篇讲贡献流程的文章。

主要功能

• 登录与账号：手机号密码登录、验证码登录、扫码登录、注册。调用 /login/cellphone 时把 phone 和 password 作为参数传进去，返回体里的 cookie 供其余需要登录的接口复用。
• 用户数据：用户信息、歌单、动态、播放记录、粉丝列表。粉丝列表走 /user/followeds，上游只返回最近 30 条，这一点在 Issue 里被确认过。
• 内容接口：歌曲、专辑、歌手、MV、歌词、评论、排行榜，覆盖播放类应用最常调用的那批数据。
• 搜索与推荐：搜索、推荐、私人 FM、私人漫游模式。v4.41.1（2026-10-05）新增了日推风格相关接口。
• 音频地址：/song/url/v1 和 /song/download/url/v1 用来拿播放链接，v4.40.1 起这两个接口支持臻音全景声。
• 签到、云盘与活动：云贝签到走 /yunbei/sign，另有云盘、v4.39.0 新增的云小编抽奖接口、v4.41.0 新增的乐迷团相关接口。
• 歌曲解锁（解灰）：环境变量 ENABLE_GENERAL_UNBLOCK 默认为 true，开启后所有歌曲都会尝试自动解锁。ENABLE_FLAC 默认为 true，用来启用无损音质。
• TypeScript 支持：仓库里带了 64.7 KB 的 interface.d.ts，可以用 import { banner } from '@neteasecloudmusicapienhanced/api' 这种方式调用并拿到类型提示。

常用参数与配置

服务端行为主要靠环境变量控制，README 列了八项：

• CORS_ALLOW_ORIGIN：默认 *，允许跨域请求的域名。可以填单个源，也可以写成逗号分隔的多个源，例如 https://a.com,https://b.com。
• ENABLE_PROXY：默认 false，是否启用反向代理功能。
• PROXY_URL：代理服务地址，默认值形如 https://your-proxy-url.com/?proxy=，只在 ENABLE_PROXY=true 时生效。
• ENABLE_RANDOM_CN_IP：默认 false。启用后所有请求默认走随机中国 IP，除非请求里用 randomCNIP 参数显式关掉。
• ENABLE_GENERAL_UNBLOCK：默认 true，是否启用全局解灰。
• ENABLE_FLAC：默认 true，是否启用无损音质。
• SELECT_MAX_BR：默认 false。启用无损音质时，是否选择最高码率。
• FOLLOW_SOURCE_ORDER：默认 true。是否严格按照音源列表顺序进行匹配。

端口用 PORT 指定，不设就是 3000。请求级别还有一个 proxy 参数，README 说明它会覆盖上面那几个代理相关的环境变量。腾讯云 Serverless 部署时，启动文件里要写 export PORT=9000 再执行 /var/lang/node16/bin/node app.js。

结果在哪里看

HTTP 方式下结果就是接口返回的 JSON，浏览器或 curl 直接能看到；Node.js 方式下结果落在 console.log(result) 打印的终端输出里。服务本身的运行日志、报错、启动信息也都在终端。仓库里没有说明有结果文件或报告目录这一类落盘输出。

完整的接口清单和参数说明在在线文档站上。npm 包版本与下载量可以在 npmjs 的包页面上看，Docker 镜像的版本与拉取量在 Docker Hub 的 moefurina/ncm-api 页面上看。

实际使用中的坑

登录态是最常出问题的一环。有用户反馈拿到验证码或密码登录都提示 8810 登录态失效，扫码则提示登录存在风险已被拦截；也有部署在 Vercel 上的实例调用 /login/cellphone 时，密码登录和验证码登录都触发 -462 人机验证。这两个 Issue 目前都标记为已解决，社区给出的可行路径是先用官方网页完成登录，再从网页读取 cookie 交给接口使用。

粉丝数据拿不全。/user/followeds 只能从网易云取到最近 30 条粉丝，提问者想知道有没有办法突破这个限制。这个 Issue 已解决，结论是上限来自上游。

音频链接不稳定。有用户做氛围歌单生成器时发现，搜索和歌曲详情接口能 100% 拿到歌曲信息和专辑封面，但音频提取不稳定，hasAudio 字段时真时假。这条 Issue 也已解决。另外有人直接按文档调用 /song/url/v1 拿不到结果，去掉 v1 之后就能访问，同样归入已解决。

云贝签到一度失效，调用 /yunbei/sign 后 App 端没有反应，这条已解决。目前仍挂在开放列表里的是多人一起听相关接口的补充请求，状态为待解决。仓库当前开放 Issue 共 10 个。

选型参考

表格里的 YesPlayMusic 是播放器方向，和本项目要解决的「对外提供接口」不是同一件事，放在这里只是给同类选型的读者一个参照。真正该比较的是原版 NeteaseCloudMusicApi：它的 GitHub 仓库已不再更新，新接口跟进慢，但被大量第三方 SDK 当作接口路径基准，生态和示例更多。如果你的代码里已经绑定了原版的接口约定，且不追新功能，换到 api-enhanced 反而要承担一轮迁移和联调成本；本项目这边则要自己处理登录态失效、cookie 维护这些上游风控带来的问题。

合规红线

这类项目做的是对第三方平台接口的封装与转发，还带「解灰」和音质相关的开关，使用边界必须自己守住。它只适合用在你自己拥有或已获得明确授权的账号与数据上，用于个人学习、自用工具或已授权的系统集成。绕开版权限制拿取音频地址、把接口用于公开分发或商业播放服务、对平台做大规模自动化请求，都可能违反平台服务条款并触及著作权相关的法律风险，账号被封或接口被限流是常见后果。相关法律与平台规则请以官方条款为准，使用前自己确认清楚。

什么情况下别用它

只想听歌、不打算写一行代码的人，直接用成品播放器更省事。拿不到稳定 cookie、又没法接受登录态随时可能失效的人，这套服务会一直需要你手动维护。需要明确 SLA 和商业级可用性保证的场景也不适合，项目本身声明是自由项目、不带任何担保。不接受接口随上游变动而失效、不愿意跟版本的团队，同样应该绕开。此外，如果你的用途本身就落在平台条款的灰区之外，无论自建还是调用线上服务都不该做。

焚评：这个项目的量化评分

本项目的选题来自 焚.com（一个按公开公式给 GitHub 项目打分的站）。焚评当前总分 9.4 分（满分 10）。下表是各维度的得分：

评分口径、权重与计算方式见焚.com 的评分方法页；数据随 GitHub 指标刷新，具体数值以焚.com 当前页面为准。本文正文为诀.com 独立撰写，评分数据由焚.com 授权引用。