项目简介

本项目是 NeteaseCloudMusicApi Enhanced 的 Rust 原生实现。通过跨站请求伪造 (CSRF) 和伪造请求头，调用网易云音乐官方 API，提供与 Node.js 版本 1:1 对应的接口。

所有 API 方法统一使用 Query 对象传参，与 Node.js 版本保持一致的调用风格，同时充分利用 Rust 的类型安全和零成本抽象特性。

特点

• 纯 Rust 实现 - 无需 Node.js 运行时，独立编译部署
• 完整加密支持 - 完整实现 weapi / eapi / linuxapi 三种加密方式
• 极低内存占用 - ~5MB vs Node.js ~50-100MB
• 异步非阻塞 - 基于 tokio + reqwest 的异步请求
• 300+ 开箱即用的 API 接口 - 与 Node.js 版本 1:1 对应
• 模块化设计 - 每个 API 独立文件，易于扩展和维护
• 统一的参数模式 - 所有接口使用 Query 对象传参，用法简洁一致
• 代理支持 - 支持 HTTP / SOCKS5 代理
• IP 伪装 - 支持 realIP 和 randomCNIP 功能
• HTTP 服务模式 - 内置 Axum HTTP 服务器，可直接替代 Node.js 版提供 REST API

快速开始

安装

作为 Rust 库依赖

[dependencies]
ncm-api-rs = "0.1"
tokio = { version = "1", features = ["full"] }

或从 Git 安装最新版：

[dependencies]
ncm-api-rs = { git = "https://github.com/SPlayer-Dev/ncm-api-rs.git" }
tokio = { version = "1", features = ["full"] }

安装 HTTP 服务器

通过 cargo 安装：

cargo install ncm-api-rs --features server

或从 GitHub Releases 下载预编译二进制文件，支持以下平台：

下载后解压即可运行：

# Linux / macOS
tar xzf ncm-server-*.tar.gz
./ncm-server

# Windows
# 解压 zip 后双击 ncm-server.exe 或在终端运行
ncm-server.exe

基础使用

use ncm_api_rs::{create_client, Query};

#[tokio::main]
async fn main() {
    // 创建客户端（不带 cookie）
    let client = create_client(None);

    // 搜索歌曲
    let query = Query::new()
        .param("keywords", "晴天 周杰伦")
        .param("type", "1")       // 1=歌曲
        .param("limit", "10");
    let result = client.cloudsearch(&query).await.unwrap();
    println!("{}", result.body);

    // 获取歌曲详情
    let query = Query::new().param("ids", "186016");
    let detail = client.song_detail(&query).await.unwrap();
    println!("{}", detail.body);

    // 获取歌词
    let query = Query::new().param("id", "186016");
    let lyric = client.lyric(&query).await.unwrap();
    println!("{}", lyric.body["lrc"]["lyric"]);

    // 获取播放链接
    let query = Query::new()
        .param("id", "186016")
        .param("level", "standard");
    let url = client.song_url_v1(&query).await.unwrap();
    println!("{}", url.body);
}

带 Cookie 使用（登录后的接口）

use ncm_api_rs::{create_client, Query};

#[tokio::main]
async fn main() {
    // 方式一：创建客户端时传入 cookie
    let client = create_client(Some("MUSIC_U=xxx; __csrf=xxx".to_string()));

    let query = Query::new();
    let songs = client.recommend_songs(&query).await.unwrap();

    // 方式二：在 Query 中传入 cookie（覆盖客户端 cookie）
    let query = Query::new().cookie("MUSIC_U=xxx; __csrf=xxx");
    let fm = client.personal_fm(&query).await.unwrap();
}

Query 参数说明

Query 是所有 API 的统一参数载体，支持链式调用：

let mut query = Query::new()
    // 业务参数 - 对应 Node.js 版本中 req.query 传入的参数
    .param("id", "186016")
    .param("limit", "30")
    .param("offset", "0")
    // 可选：覆盖 cookie
    .cookie("MUSIC_U=xxx");

// 可选：设置代理
query.proxy = Some("socks5://127.0.0.1:1080".to_string());
// 可选：设置真实 IP（伪装 X-Real-IP 请求头）
query.real_ip = Some("116.25.146.177".to_string());
// 可选：使用随机中国 IP
query.random_cn_ip = true;

// 读取参数
query.get("id");              // Some("186016")
query.get_or("limit", "30");  // "30"

调用前须知

本项目仅供学习使用，请尊重版权，请勿利用此项目从事商业行为或进行破坏版权行为

不要频繁调用登录接口，不然可能会被风控，登录状态还存在就不要重复调用登录接口

部分接口如登录接口不能调用太频繁，否则可能会触发 503 错误或者 IP 高频错误，若需频繁调用，需要准备 IP 代理池

由于网易限制，此项目在国外服务器或部分国内云服务上使用会受到限制，如 460 cheating异常，如需解决，可使用 real_ip 参数，传进国内 IP 解决

301 错误基本都是没登录就调用了需要登录的接口，如果登录了还是提示 301，基本都是 cookie 问题

Cookie 说明

登录接口返回的 ApiResponse 中包含 cookie 字段（Vec<String>），可以保存到本地后在后续请求中使用：

// 登录
let query = Query::new()
    .param("phone", "13xxx")
    .param("password", "xxx");
let result = client.login_cellphone(&query).await?;

// 保存 cookie
let cookies = result.cookie.join("; ");

// 后续请求使用 cookie
let query = Query::new().cookie(&cookies);
let account = client.user_account(&query).await?;

也可以直接从浏览器中获取 cookie 值，只需要其中 key 为 MUSIC_U 的数据即可：

let query = Query::new().cookie("MUSIC_U=xxxx");

realIP 参数

在国外服务器或 Vercel 等云服务上使用时，需要设置 real_ip 参数传入国内 IP：

let mut query = Query::new().param("id", "1969519579");
query.real_ip = Some("116.25.146.177".to_string());
let result = client.song_url_v1(&query).await?;

randomCNIP 参数

也可以使用随机中国 IP 功能，无需手动指定 IP：

let mut query = Query::new().param("id", "1969519579");
query.random_cn_ip = true;
let result = client.song_url_v1(&query).await?;

代理支持

在 Query 参数中设置 proxy 即可让该次请求使用代理：

let mut query = Query::new().param("id", "33894312");
query.proxy = Some("http://121.196.226.246:84".to_string());
// 也支持 socks5 代理
// query.proxy = Some("socks5://127.0.0.1:1080".to_string());
let result = client.song_url(&query).await?;

HTTP 服务模式

除了作为 Rust 库直接调用，本项目还支持以 HTTP 服务器模式运行，提供与 Node.js 版本完全兼容的 REST API 接口，前端可以无缝切换。

启动服务器

# 编译并运行（默认监听 0.0.0.0:3000）
cargo run --features server --bin ncm-server

# 或先编译再运行
cargo build --release --features server --bin ncm-server
./target/release/ncm-server

环境变量配置

# 示例：自定义端口和 CORS
NCM_HOST=127.0.0.1 NCM_PORT=8080 CORS_ALLOW_ORIGIN=http://localhost:5173 cargo run --features server --bin ncm-server

# 示例：允许多个源
CORS_ALLOW_ORIGIN=https://a.com,https://b.com cargo run --features server --bin ncm-server

前端调用示例

接口路径与 Node.js 版完全一致，方法名中的下划线 _ 转换为斜杠 /：

// 搜索歌曲
const res = await axios.get('/cloudsearch', { params: { keywords: '海阔天空' } })

// 获取歌曲详情
const res = await axios.get('/song/detail', { params: { ids: '347230' } })

// POST 方式调用
const res = await axios.post('/login/cellphone', {
  phone: '138xxxx8000',
  password: 'xxx',
})

// 带 Cookie 调用需要登录的接口
const res = await axios.get('/user/playlist', {
  params: { uid: '32953014', cookie: 'MUSIC_U=xxx' },
})

路由映射规则

所有路由均支持 GET 和 POST 两种请求方式（上传接口仅 POST）。

作为库集成到你的项目

如果你已有 Axum 项目，可以直接集成路由：

use ncm_api_rs::{create_client, server::{build_app, build_app_with_config, ServerConfig}};

// 方式一：快速构建
let app = build_app(create_client(None));

// 方式二：自定义配置
let config = ServerConfig {
    host: "127.0.0.1".to_string(),
    port: 8080,
    cors_origin: Some("http://localhost:5173".to_string()),
};
let app = build_app_with_config(create_client(None), &config);

// 启动
let listener = tokio::net::TcpListener::bind("0.0.0.0:8080").await?;
axum::serve(listener, app).await?;

自动路由注册

新增 API 时无需手动注册路由。build.rs 会在编译期自动扫描 src/api/mod.rs 中的模块声明，生成对应的路由注册代码。只需：

1. 创建 src/api/xxx_yyy.rs 文件，实现 ApiClient 方法
2. 在 src/api/mod.rs 中添加 mod xxx_yyy;

路由 /xxx/yyy 会自动注册，无需其他操作。

API 文档

完整接口文档请查看 docs/API.md，涵盖全部接口的详细参数说明和调用示例。

接口速查表

扩展接口

在 src/api/ 中添加新文件即可，模式非常简单：

// src/api/your_new_api.rs
use crate::request::{ApiClient, ApiResponse, CryptoType};
use crate::error::Result;
use serde_json::json;
use super::Query;

impl ApiClient {
    pub async fn your_new_api(&self, query: &Query) -> Result<ApiResponse> {
        let data = json!({
            "id": query.get_or("id", ""),
        });
        self.request("/api/your/endpoint", data, query.to_option(CryptoType::Weapi)).await
    }
}

然后在 src/api/mod.rs 中注册：

mod your_new_api;

对应的 Node.js 接口参考 NeteaseCloudMusicApi Enhanced 的 module/ 目录。

致谢

• NeteaseCloudMusicApi Enhanced - 原始 Node.js 实现
• Binaryify/NeteaseCloudMusicApi - 原始项目

License

WTFPL - Do What The Fuck You Want To Public License