简介这是一套面向开发者与计算机专业学生的开源网易云音乐API资源版本为4.13.8能够以编程方式调用搜索歌曲、获取歌单、播放管理、评论信息等接口常被用作音乐类应用的后端服务也适合作为毕业设计或课程项目的技术基底。资源包共417个文件、约12.09MB内部以337个JavaScript源文件为核心完整实现了API的主要业务逻辑同时包含30张图片、13个HTML文件、8个Markdown文档和6个JSON配置文件分别用于界面展示、交互示例、使用说明与数据配置另有Dockerfile、环境配置文件等便于部署与二次开发。当前已有395人浏览学习具备一定的参考热度。借助源码和附带文档读者可以系统地学习Node.js生态下的API工程组织、网络请求处理、JSON解析、异步流程控制及模块化设计等关键技术通过本地搭建与接口调用还能进一步将其应用到音乐推荐、播放器、音乐数据分析等真实场景兼顾教学、研究与工程实践。整体来看这份资源既有较高的代码研究价值也是快速搭建音乐服务的不错选择。1. NeteaseCloudMusicApi v4.13.8 是什么一个让个人项目直接拿到网易云数据接口的落地包拿到NeteaseCloudMusicApi v4.13.8.zip这个压缩包的时候我第一反应是这下终于不用自己逆向网易云的网页加密了。它本质上是一个用 Node.js 写好的本地 HTTP 服务解压后启动起来你的应用只需要请求http://localhost:3000/search?keywordsxxx就能拿到结构清晰的 JSON 数据。它不是官方 SDK而是把网易云音乐网页端接口封装成了“本地化 API”能解决搜索、歌单、歌词、播放地址这些高频需求。适合做个人播放器、自动签到脚本、歌单统计工具以及不想碰前端签名逻辑的后端开发者。2. 把 NeteaseCloudMusicApi v4.13.8 跑起来环境准备与最小启动命令2.1 准备环境Node 版本与目录解压检查先确认本机 Node 环境。这个项目是标准 Node.js 应用我在 Node 14、16、18 上都跑过 v4.13.8基本都能正常启动。但如果你的node -v输出版本低于 14安装依赖的时候大概率会报错后面章节会专门讲这个问题。建议直接装一个 Node 16 LTS兼容性最稳。检查版本node -v npm -v然后找个干净的目录把压缩包放进去执行解压unzip NeteaseCloudMusicApi.v4.13.8.zip cd NeteaseCloudMusicApi这里有一个容易翻车的小点压缩包解压后可能不是直接进入项目根目录而是多了一层以版本号命名的文件夹比如NeteaseCloudMusicApi-v4.13.8/。所以我习惯性地先执行ls -la确认当前目录下能看到package.json和app.js这两个关键文件。如果没看到就再cd进去一层否则后续所有命令都会在错误目录里执行依赖装了一堆启动还是不认账。2.2 安装依赖并启动服务npm install 与 node app.js进入正确目录后先安装依赖。这个项目在package.json里声明了express、aes-js、request之类的依赖安装过程会自动拉取npm install如果这一步特别慢或者报网络超时可以把 npm 源切到国内镜像再试。命令是npm config set registry https://registry.npmmirror.com安装完成后直接启动node app.js启动日志会显示类似Server running at http://localhost:3000。注意这里默认是 3000 端口如果你的机器上已经有别的服务占用比如 Vue 开发服务器就会看到EADDRINUSE错误。为了少踩坑我平时启动时习惯直接换端口PORT4000 node app.js在 Windows PowerShell 里设置环境变量的语法不同$env:PORT4000; node app.js启动之后不要关掉终端这个进程会一直前台运行。看到日志输出就算启动成功如果日志立刻退出大概率是端口占用或依赖缺失。端口占用用lsof -i:3000查依赖缺失就重新npm install。2.3 用 curl 验证第一个接口搜索请求返回了什么服务起来后开一个新的终端先拿最简单的搜索接口做验证curl http://localhost:3000/search?keywords%E5%91%A8%E6%9D%B0%E4%BC%A6limit3注意这里的keywords参数被我手动做了 URL 编码“周杰伦”三个字的 UTF-8 编码是%E5%91%A8%E6%9D%B0%E4%BC%A6。如果你直接用中文拼在 URL 里有些终端会发送非法字符导致接口返回 400。更省事的做法是用curl --data-urlencode keywords周杰伦 http://localhost:3000/search?limit3让 curl 帮你编码。返回的是一段 JSON建议先存成文件再看curl -s http://localhost:3000/search?keywords周杰伦limit3 | jq .result.songs[0]如果没装 jq就把 JSON 复制到格式化工具里。你会看到歌曲对象包含name、artists、album、id等字段。这里的id是最关键的后面拉播放地址和歌词都要靠它。验证到这个说明服务和接口已经通了可以开始做业务。有时候curl在 PowerShell 里是Invoke-WebRequest的别名行为会很奇怪。建议用curl.exe指定真正的 curl或者在脚本里用 Node 的http模块。这个阶段的主要目标是确认“启动到请求”这条链路通了只要返回 JSON环境准备工作就算全部结束。3. 从请求到响应NeteaseCloudMusicApi v4.13.8 的接口路由与加密逻辑3.1 路由到接口名搜索接口的参数是怎么拼出来的这个包的路由设计非常直白基本就是路径名 功能名。我经常用的几个路由功能关键参数/search搜索歌曲keywords、limit、offset/song/url获取播放地址id、br/lyric获取歌词id/playlist/detail获取歌单信息id/comment/music获取歌曲评论id、pageNo、pageSize每一个路由的查询参数基本都对齐了网页端的参数名。例如搜索接口的offset控制分页偏移默认从 0 开始limit控制返回条数。我建议limit不要设太大20 条已经足够大多数场景。拿搜索接口举一个实际请求curl http://localhost:3000/search?keywords%E9%99%B6%E5%99%A9limit3offset10解释一下参数offset10表示跳过前面 10 条limit3表示这次只返回 3 条相当于翻到第 4 页。接口内部拿到这个请求后会把keywords、limit、offset组装成一个对象然后转交给网易云的搜索接口。注意这里的s参数是网易云网页端搜索接口的通用字段名但这个包对外仍然叫keywords方便记忆。如果你在浏览器里直接打开这个地址也能看到 JSON但浏览器会把中文编码处理掉。实际写代码时不要手动拼 URL用URLSearchParams更不容易出错const params new URLSearchParams({ keywords: 陶喆, limit: 3 }); const url http://127.0.0.1:4000/search?${params.toString()};这样中文、空格、特殊符号都会被自动编码不用操心转义问题。3.2 网页端请求的 AES 加密与签名是怎么被这个包简化掉的网易云网页端的搜索或歌单请求不是普通 POST浏览器 Network 面板里能看到请求体里有两个固定字段params和encSecKey。刚开始接触的人会一脸黑匣子明明就是搜个歌为什么要把参数包这么多层。它内部逻辑大致是这样的真实参数先被拼成一个 JSON 字符串然后用 AES-128-ECB 加密加密后 base64 编码放进params字段同时encSecKey是由一个固定 RSA 公钥对 AES 密钥加密得到的。服务器端拿到这两个字段后先用私钥解出 AES 密钥再用它解密params。所以只要params里的内容对不上或者encSecKey的位数不对接口直接拒绝。v4.13.8 这个包做的事情就是替你完成了这一整套加解密。它把关键逻辑封装在一个内部模块里外部调用方只需要提交普通的 JSON 参数。我举个例子理解内部流程// 描述性的伪代码实际实现集中在 lib 目录里 const payload { s: keywords, limit: limit, offset: offset }; const params aesEncrypt(JSON.stringify(payload), secretKey); const encSecKey rsaEncrypt(secretKey, publicKey); post(/api/cloudsearch/pc, { params, encSecKey });注意这个例子是概念性的实际代码里secretKey和publicKey都写在核心配置里不要自己去改。这也是为什么我推荐用打包好的版本而不是从零复现。因为网易云一旦调整密钥长度或加密顺序整个包都需要同步升级。v4.13.8 能稳定跑说明它对应的加密参数是匹配当时的网页端版本的。所以当你遇到“所有接口都报 400”的时候别再查自己代码了大概率是加密逻辑失效。先试着升级到该项目的更新版本或者把请求切回/search?keywordstest看是不是同样失败用来区分是业务问题还是加密层问题。3.3 Cookie 与登录态什么时候必须带什么时候可以裸跑这个包对 Cookie 的处理比较自由。匿名状态下搜索、歌单详情、歌词都能正常返回因为这些接口本身不要求登录。但到了播放地址/song/url情况就复杂了。VIP 歌曲、部分新歌或者指定高音质br320000时匿名请求可能会返回url: null。这时候就需要把登录态的 Cookie 带进去。带 Cookie 的方式是在请求参数里加一个与顶级参数名一样的字段curl http://localhost:3000/song/url?id186016br320000cookieMUSIC_Uxxx;__csrfyyy这里的MUSIC_U是登录后的核心凭证浏览器登录网易云音乐后 F12 找到 Cookie 里的MUSIC_U和__csrf复制出来就能用。注意 Cookie 里有分号如果在 URL 里直接拼分号会被当成普通字符建议在代码里放入请求头而不是查询参数。比如用http.get时设置headers: { Cookie: MUSIC_Uxxx }。我一般的经验是能匿名跑的接口尽量匿名跑。因为带登录态请求虽然能拿到 VIP 播放地址也意味着这个服务一旦暴露在公网别人可以借用你的账号权限。更稳妥的做法是把 Cookie 放到环境变量里业务启动时再注入MUSIC_Uxxxx node app.js然后在脚本里通过process.env.MUSIC_U读取而不是写死到代码中。这样可以保证代码仓库里不会出现敏感登录凭证。4. 按需调整 v4.13.8端口、主机与常用参数设置4.1 环境变量改端口与绑定地址跑通之后首先要解决的就是端口问题。默认 3000 太容易被占而且很多时候同一个服务器上要跑多个 Node 服务。这个包支持从环境变量读取PORT和HOSTPORT4000 HOST127.0.0.1 node app.jsHOST的设置值得展开说。如果是本机开发绑定127.0.0.1就够其他设备无法访问安全性好如果希望手机或者局域网内其他机器也能调用才需要改成0.0.0.0。改成0.0.0.0之后访问地址要换成你电脑的局域网 IP比如http://192.168.1.20:4000/search不能再用localhost。如果你在服务器上跑我会建议只监听内网地址用 Nginx 做一层location /api/的反向代理把访问控制放到上层。直接对公网开放 4000 端口不是不行但容易被人扫到接口后滥用搜索和播放地址。4.2 登录后处理设置 Cookie 和匿名调用的边界有些接口比如“每日推荐”、“私人 FM”必须要登录态另外/song/url带不带 Cookie 直接决定返回的url是否为 null。在这个包里登录态是通过请求参数里的cookie字段传入的。放在查询串里容易暴露放在请求头里更安全const options { hostname: 127.0.0.1, port: 4000, path: /song/url?id186016, headers: { Cookie: process.env.MUSIC_U } };如果你只是做公开歌单的抓取完全不用带 Cookie。但要注意不带 Cookie 时搜索和歌单详情返回的数据结构里某些字段可能是缺省的需要做空值判断。比如歌曲对象里的fee字段表示收费状态1代表 VIP匿名接口可能不返回完整播放地址。写脚本时先判断fee如果是 1就不要继续请求/song/url了省得白等。4.3 把服务常驻pm2 的简单配置 vs systemd 服务文件开发时直接node app.js没有问题但部署到服务器上终端一关服务就没了。最省心的方案是用 pm2。npm install -g pm2 pm2 start app.js --name netease-api pm2 save pm2 startup这几条命令的含义分别是安装 pm2、启动服务并命名为netease-api、保存当前进程列表、生成开机启动脚本。之后要查日志就用pm2 logs netease-api要看内存就用pm2 monit。pm2 的缺点是它自己是 Node 生态里的工具如果你想让整个系统用 systemd 统一管理可以写一个 service 文件[Unit] DescriptionNeteaseCloudMusicApi Afternetwork.target [Service] Typesimple Userneteasemusic ExecStart/usr/bin/node /opt/netease-api/app.js EnvironmentPORT4000 EnvironmentHOST127.0.0.1 Restartalways RestartSec5 [Install] WantedBymulti-user.target写好后执行sudo systemctl daemon-reload sudo systemctl enable --now netease-api注意ExecStart里的node要写成绝对路径可以用which node查。如果环境变量很多不建议堆在Environment里改用一个环境文件EnvironmentFile/etc/netease-api.env维护起来清爽得多。这两个方案选哪个没有定论。我的习惯是个人服务器用 pm2因为更新代码后pm2 restart netease-api --update-env一行就能重新加载环境变量在客户服务器上我倾向 systemd因为系统本身就靠 systemd 管理交给运维不增加额外学习成本。5. 避坑部署和调用 NeteaseCloudMusicApi 时最常见的 5 个问题5.1 依赖安装失败npm ERR! code EINVALIDTAGNAME是 Node 版本太旧现象执行npm install时控制台抛出一串npm ERR! code EINVALIDTAGNAME后面紧跟着依赖名和 tag 的提示安装直接终止。原因项目里某些依赖的package.json要求 Node 版本高于 14而你本机的 Node 还停留在 10.x 或 12.x。npm 在解析依赖时发现版本不满足就会用这种方式拒绝继续。解决先用nvm install 16装一个新版 Node再nvm use 16切过去。然后删除已经装到一半的旧依赖rm -rf node_modules package-lock.json npm install如果不想用 nvm也可以直接去 Node 官网下一个 LTS 安装包。这里有个经验不要只升级 npm 版本EINVALIDTAGNAME的本质是 Node 的语法支持不够不是 npm 包管理器的问题。5.2 接口返回 404路由前面少补一个/现象请求地址写成http://localhost:3000search?keywords晴天结果返回一个 HTML 的 404 页面但服务明明在运行。原因URL 的协议和路径之间漏了斜杠比如在拼接字符串时把 baseURL 最后写的3000和 path 的/search拼成了3000search。浏览器或 HTTP 客户端会把整个字符串当成一个普通路径去请求自然找不到路由。解决统一用new URL(/search, http://localhost:4000).toString()这种拼接方式确保 path 以/开头。另外如果你是把它放在 Nginx 后面要检查 Nginx 的proxy_pass是否带尾斜杠因为带不带斜杠转发路径会完全不同。拿一个请求先验证curl -v http://localhost:4000/search?keywordstest-v能看到实际请求行如果方法路径里多了一个search或少了/一眼就能看出来。5.3 搜索接口突然全挂风控临时封了你的访问频率现象脚本跑了一段时间后/search接口突然开始返回 400 或 403重启服务和重启机器都解决不了。原因短时间内对网易云的网页接口请求次数太多触发了对方安全策略把你当前 IP 临时限制。这个包本身不附带限流它只是忠实地转发请求因此限制是作用在网易云那层的。解决在业务侧加限流。我自己的脚本会在两次搜索请求之间至少 sleep 300 毫秒并且对相同关键词做缓存一分钟内重复请求直接读本地结果。如果请求需要循环遍历歌单那么用setTimeout做队列不要用Promise.all并发发请求。提醒一句不要在夜深人静的时候做高频测试那个时点风控反而更敏感。5.4 歌曲播放地址失效Cookie 过期导致需重新登录现象昨天还能正常返回播放地址的/song/url接口今天返回的 JSON 里url字段是null或者直接 404。原因播放地址接口对 VIP 歌曲和新歌非常依赖 Cookie 中的登录态Cookie 里MUSIC_U过期后匿名请求拿不到高音质权限。解决更新 Cookie 后重启服务。如果项目支持自动登录就调用包里的/login/refresh接口刷新凭证如果不支持就手动从浏览器复制新的MUSIC_U并更新到环境变量。这里要特别强调带完整 Cookie 的服务不要直接绑定到公网最好限制为内网访问否则你的账号会被别人无感知地当成代理资源使用容易被封禁。5.5 端口被占用默认 3000 不够用现象执行node app.js后终端显示EADDRINUSE服务立刻退出。原因3000 点是前端开发服务器的默认端口React、Vue 的 dev server 和这个项目冲突的概率非常大。我之前就在一台测试机上遇到过端口被两个服务抢来抢去。解决换一个不常用的端口同时检查占用lsof -i:3000如果确实有别的开发服务器占用杀进程不现实直接用PORT5000 node app.js。我的默认习惯是统一用 4000避开常见开发端口。如果将来发现 4000 也可能被占就把端口号写进配置文件而不是命令行这样换端口不用改启动脚本。6. 做一个小工具基于 v4.13.8 写一个能搜歌并输出播放地址的 CLI6.1 设计 CLI 需要的最小依赖这个工具只需要 Node 内置模块不需要额外安装依赖。命令行传入一个关键词工具请求已经启动的 v4.13.8 服务把搜索结果里前 5 首歌的名称、歌手和播放地址打出来。这里的底层逻辑分两步先搜歌曲拿到id再拿id请求播放地址接口。6.2 用 node 脚本请求接口并打印可播放列表const http require(http); const keywords process.argv[2] || 晴天; function get(path) { return new Promise((resolve, reject) { http.get(http://127.0.0.1:4000 path, res { let data ; res.on(data, chunk data chunk); res.on(end, () resolve(JSON.parse(data))); }).on(error, reject); }); } async function main() { const search await get(/search?keywords${encodeURIComponent(keywords)}limit5); const songs search.result.songs || []; for (const song of songs) { const detail await get(/song/url?id${song.id}); const url detail.data detail.data[0] ? detail.data[0].url : null; console.log(${song.name} - ${song.artists.map(a a.name).join(/)}); console.log(url || ... 播放地址为空可能需要 Cookie); } } main();逻辑说明get函数把http.get的响应解析成 Promise便于await串行调用。这里刻意没有并发拉取播放地址因为对刚从风控恢复的服务来说并发请求容易再次触发限制。encodeURIComponent处理中文关键词保证 URL 合法。打印结果时判断url是否为空如果为空就提示可能需要 Cookie。6.3 三个验证点接口返回、字段非空、URL 可访问工具写完之后我一般会验证三个点。第一终端输出里至少有歌曲名称说明/search路由正常第二播放地址不为空说明/song/url在当前网络环境下没有被风控第三拿到url后单独执行curl -I url看是否能收到200响应这能确认播放地址本身真实有效。node cli.js 林俊杰如果输出正常这套小工具就能一直用。我最后保留这个脚本的另一个原因是部署任何新环境时先用它触发一次搜索和播放地址请求比看启动日志更能确认整个链路是通的。这个习惯帮我排掉过不少“日志正常但接口请求异常”的坑希望也能帮到你。本文还有配套的精品资源点击获取