纯 PHP 音乐工具箱部署教程：网易云/QQ/汽水音乐三源解析与下载

作者: Mr.Xuan 分类: 我的作品发布时间: 2026-08-06 20:15

如果你正在寻找一个纯 PHP 实现、零框架依赖、开箱即用的多源音乐解析下载工具，那么「音乐工具箱 PHP 版」或许正是你需要的方案。本文将带你从零开始部署这套支持网易云音乐、QQ音乐、汽水音乐三源的解析与下载服务。

📑 文章目录

一、项目介绍
二、功能详解
三、部署教程
四、使用指南
五、API 接口概览
六、配置文件详解
七、技术实现亮点
八、注意事项
九、常见问题 FAQ
十、CLI 工具
十一、支持的链接格式
十二、致谢与许可
总结
下载代码

一、项目介绍

1.1 项目背景

「音乐工具箱 (PHP)」是基于 Suxiaoqinx/Netease_url Python 项目的 PHP 移植与扩展版本。它将网易云音乐、QQ音乐、汽水音乐三个主流音乐源整合在一个统一的服务中，提供完整的搜索、解析、下载、扫码登录、CENC 解密等能力。

整个项目纯 PHP 实现，无任何框架依赖，支持 PHP 内置服务器、Apache、Nginx 三种部署方式，对虚拟主机和自有服务器都极其友好。

1.2 核心特性一览

三源支持：网易云音乐、QQ音乐、汽水音乐统一界面切换
完整功能链：搜索 → 解析 → 试听 → 下载（含元数据/封面/歌词）
批量打包：支持歌单/专辑/榜单批量打包 ZIP 下载（最多 200 首）
双源扫码登录：网易云 APP 扫码 + QQ音乐三方式扫码（手机QQ / 微信 / QQ音乐APP）
CENC 自动解密：汽水音乐 PC 完整版音源 AES-CTR 自动解密
元数据自动写入：MP3 写 ID3v2.3，FLAC 写 VorbisComment，自动嵌入封面与 LRC 歌词
管理员后台：远程管理三源 Cookie/凭证 + 实时状态检测
双模式元数据引擎：ffmpeg 优先，自动降级到纯 PHP 的 getID3 库

1.3 三源功能对照表

功能	网易云音乐	QQ音乐	汽水音乐
歌曲搜索	✅	✅	✅
单曲解析（详情+播放链接+歌词）	✅	✅	✅（含 CENC 解密）
歌单解析	✅	✅	✅（Node 代理绕风控）
专辑解析	✅	✅	–
官方榜单	✅	✅	–
单曲下载（含元数据/封面/歌词）	✅	✅	✅（自动解密）
批量打包下载 ZIP	✅	✅	✅
扫码登录	✅ 网易云APP	✅ 手机QQ / 微信 / QQ音乐APP	–
歌手信息	–	✅	–
MV 解析	–	✅	–
Cookie 状态检测	✅	✅（多账号 + VIP 标识）	✅（VIP 状态）
管理员后台	✅	✅	✅
musickey 自动刷新	–	✅	–

二、功能详解

2.1 核心功能模块

功能	说明
歌曲搜索	关键词搜索，支持设置返回数量（最多 100）
单曲解析	解析详细信息、播放链接、歌词，APlayer 在线试听
歌单解析	批量解析歌单全部曲目，支持批量打包
专辑解析	批量解析专辑全部曲目，支持批量打包
官方榜单	网易云/QQ音乐官方排行榜，点击榜单直接解析
音乐下载	多音质下载，自动写入元数据 + 封面 + 歌词
批量打包	勾选多首歌曲打包为 ZIP 下载（最多 200 首）
扫码登录	网易云 / QQ音乐双源扫码，QQ音乐支持三种方式
歌词写入	MP3 写 USLT 帧，FLAC 写 LYRICS/UNSYNCEDLYRICS 字段
自定义文件名	模板变量 {artist}/{name}/{album}/{level}，localStorage 持久化
下载进度	百分比 + 已下载/总大小 + 实时速度，双策略估算总大小
CENC 解密	汽水音乐 PC 完整版音源 AES-CTR 自动解密
管理员后台	远程管理三源 Cookie/凭证 + 实时状态检测

2.2 音质支持矩阵

网易云音乐 / QQ音乐

参数	说明	码率/规格	权限
`standard`	标准音质	128 kbps	普通
`exhigh`	极高音质	320 kbps	黑胶 VIP
`lossless`	无损音质	FLAC	黑胶 VIP
`hires`	Hi-Res 音质	24bit / 96kHz	黑胶 VIP
`jyeffect`	高清环绕声	–	黑胶 VIP
`sky`	沉浸环绕声	–	黑胶 SVIP
`jymaster`	超清母带	–	黑胶 SVIP
`dolby`	杜比全景声	EAC3	黑胶 SVIP

汽水音乐

quality 值	中文名称	码率	格式
`hi_res`	Hi-Res 无损音质	319 kbps	m4a/aac
`spatial`	空间音频	321 kbps	m4a/aac
`highest`	HD 超高音质	260 kbps	m4a/aac
`higher`	高音质	132 kbps	m4a/aac
`medium`	标准音质	68 kbps	m4a/aac

汽水音乐音质优先级: hi_res > spatial > highest > higher > medium

2.3 元数据与歌词写入

下载时自动写入以下信息（无需手动操作）：

字段	MP3 (ID3v2.3)	FLAC (VorbisComment)
标题	`TIT2`	`TITLE`
艺术家	`TPE1` / `TPE2`	`ARTIST` / `ALBUMARTIST`
专辑	`TALB`	`ALBUM`
音轨号	`TRCK`	`TRACKNUMBER`
备注	`COMM`	`COMMENT`
封面	`APIC`	`PICTURE` 块
歌词（原文）	`USLT` (UTF-16)	`LYRICS` + `UNSYNCEDLYRICS`
歌词（翻译）	`USLT` (description=翻译)	`TRANSLATEDLYRICS`

歌词为 LRC 格式文本，包含时间戳，可同步显示。

三、部署教程

3.1 环境要求

PHP ≥ 7.4（推荐 PHP 8.0+）
必需扩展：curl、openssl、zip、fileinfo
可选依赖：ffmpeg（提供更好的格式兼容性，未安装时自动降级到 getID3 纯 PHP 库）

环境检查命令：

# 检查 PHP 版本
php -v

# 检查必需扩展
php -r "foreach(['curl','openssl','zip','fileinfo'] as \$e) echo \$e.': '.(extension_loaded(\$e)?'OK':'MISSING').PHP_EOL;"

3.2 获取代码

底部下载，暂未分享到github

三源各有独立的 Cookie/凭证文件，可全部扫码登录获取，或手动填入。

网易云音乐：cookie.txt

MUSIC_U=your_music_u_value; __csrf=your_csrf; NMTID=your_nmtid;

获取方式：登录网易云音乐网页版 → F12 开发者工具 → Network → 复制任意请求的 Cookie 值，粘贴到 cookie.txt。也可直接用 Web 界面的扫码登录功能（推荐）。

QQ音乐：qq_cookie.txt

JSON 多账号格式，每行一个账号：

{"musicid":12345678,"str_musicid":"12345678","musickey":"XXXXXXXX","login_type":2,"uin":"12345678","qm_keyst":"XXXXXXXX","login_method":"qq_qr"}

login_method 字段标识扫码方式：

qq_qr – QQ 扫码用户
wx_qr – 微信扫码用户
mobile_qr – 客户端扫码用户（QQ音乐APP MQTT 协议）
留空 – 老格式 Cookie，回退到 login_type 推断（1=微信，2=QQ）

获取方式：推荐用 Web 界面扫码登录（自动写入 login_method 字段）。musickey 约 7 天过期，程序会自动检测并在可能时刷新。

汽水音乐：qishui_pc_creds.json

JSON 数组格式，支持多凭证轮询：

[
  {
    "id": "cred_1",
    "label": "凭证 #1",
    "device_id": "xxxxxxxxxxxx",
    "cookie": "sessionid=xxx; sid_tt=xxx; ttwid=xxx;",
    "iid": "1234567890",
    "enabled": true,
    "created_at": 1720000000,
    "note": "可选备注"
  }
]

获取方式（任选其一）：

Reqable 抓包（推荐）：打开汽水音乐电脑版，任意播放一首歌触发请求，找到 POST https://api.qishui.com/luna/pc/track_v2，提取 device_id（URL 查询参数）和 Cookie（请求头）
进程内存扫描：使用项目自带的 qishui_creds_extractor/ 工具扫描 SodaMusic.exe 进程内存，提取 sessionid/sid_tt/ttwid 等字段
管理员后台：在 Web 界面登录管理员后台 → 汽水音乐 Tab → 添加凭证

关键提示：track_v2 接口仅需 Cookie 认证即可返回完整版音源 URL，不需要 x-helios/x-medusa/bdticket 签名头。Cookie 会过期（sessionid 默认 30 天，ttwid 1 年），失效后需重新抓包。

3.4 启动服务

方式 A：PHP 内置服务器（开发环境推荐）

php -d extension=curl -d extension=openssl -d extension=zip -S 0.0.0.0:5000 index.php

优点：零配置，开箱即用。适用：本地开发、测试。

方式 B：Apache（生产环境）

# 1. 将项目放入 Apache Web 目录（如 /var/www/Netease_php_url）
# 2. 启用 mod_rewrite
sudo a2enmod rewrite
sudo systemctl restart apache2
# 3. 项目根目录的 .htaccess 会自动生效

方式 C：Nginx + php-fpm（生产环境）

# 1. 复用项目提供的配置模板
sudo cp Nginx_Rewrite.txt /etc/nginx/sites-available/music
sudo ln -s /etc/nginx/sites-available/music /etc/nginx/sites-enabled/

# 2. 修改配置文件中的 root 路径和 server_name
# 3. 测试并重载
sudo nginx -t && sudo nginx -s reload

⚠️ 生产环境务必配置可信代理 IP（在 config.php 中）：

// Nginx 反向代理部署时必须配置，否则限流和封禁将基于 Nginx IP 失效
define('TRUSTED_PROXY_IPS', ['127.0.0.1']);

方式 D：Docker 部署

FROM php:8.2-apache
RUN apt-get update && apt-get install -y ffmpeg libcurl4-openssl-dev libssl-dev libzip-dev
RUN docker-php-ext-install curl openssl fileinfo zip
RUN a2enmod rewrite
COPY . /var/www/html/
RUN chown -R www-data:www-data /var/www/html
EXPOSE 80

docker build -t music-php .
docker run -d -p 5000:80 --name music music-php

方式 E：汽水音乐 Node.js 代理（可选，绕过 IP 风控）

部分服务器因 cURL/OpenSSL 版本过旧或 IP 风控，无法获取汽水音乐歌单完整曲目（远程只返回 151 首，本地返回 312 首）。Node.js 代理使用不同网络栈和 TLS 指纹绕过风控。

# 安装依赖
cd qishui_proxy && npm install

# 启动代理服务（生产模式）
node server.js --prod
# 或使用 pm2 守护进程
pm2 start server.js --name qishui-proxy

# 在 config.php 中配置代理 URL
# define('QISHUI_PROXY_URL', 'http://127.0.0.1:5200');

3.5 访问服务

打开浏览器访问 http://localhost:5000/

页面顶部可一键切换网易云音乐 / QQ音乐 / 汽水音乐三源，Cookie 状态栏实时显示登录情况。

四、使用指南

4.1 三源切换

页面顶部的源切换单选按钮会触发以下动作：

Cookie 状态栏自动刷新
扫码登录提示文字更新
QQ音乐源显示三种扫码方式选择器（手机QQ / 微信 / QQ音乐APP）
汽水音乐源隐藏音质选择（由 API 返回可选音质）和扫码方式选择器
各功能区清空旧结果

4.2 双源扫码登录

网易云音乐

项目	说明
二维码协议	`interface3.music.163.com` unikey
扫码 APP	网易云音乐 APP
保存位置	`cookie.txt`

QQ音乐（三种方式）

方式	参数	二维码来源	扫码 APP	状态检测	适用账号
手机QQ	`type=qq`	`ssl.ptlogin2.qq.com/ptqrshow`	手机 QQ	后端 HTTP 轮询 `ptqrlogin`	QQ 账号
微信	`type=wx`	`open.weixin.qq.com/connect/qrconnect`	微信	后端 HTTP 轮询 `longpolling`	微信账号
QQ音乐APP	`type=mobile`	QQMusicAPI `CreateQRCode`	QQ音乐 APP	前端 MQTT 5.0 over WebSocket	QQ/微信账号

MOBILE 方式技术细节：

前端 JS 直连 wss://mu.y.qq.com/ws/handshake 建立 MQTT 5.0 连接
订阅 topic management.qrcode_login/{qrcodeID} 接收登录凭据
无需后端轮询，登录凭据直接在前端接收并通过 /qq/qr/exchange 换取 Cookie

使用流程：

切换到 QQ音乐源
功能选择：扫码登录
选择扫码方式（手机QQ / 微信 / QQ音乐APP）
点击生成二维码
用对应 APP 扫码并手机确认
Cookie 自动保存到 qq_cookie.txt，并写入 login_method 字段标识扫码方式

4.3 自定义文件名模板

在单曲解析和音乐下载区域折叠展开”下载文件名模板”：

变量	含义
`{artist}`	歌手
`{name}`	歌名
`{album}`	专辑
`{level}`	音质

默认模板：{artist}_{name}_{level}
非法字符自动替换为 _
模板保存在 localStorage，跨会话生效

4.4 管理员后台

访问 /admin/ 进入管理员后台，可远程管理三源 Cookie/凭证。

默认账户：

URL:      /admin/
密码:     admin123   ⚠️ 部署后必须修改 config.php 中的 ADMIN_PASSWORD

功能模块：

Tab	功能
概览	显示三源配置状态、服务版本、元数据引擎
网易云音乐	Cookie 列表（实时状态）/ 添加 / 删除 / 清空
QQ音乐	Cookie 列表（实时状态 + VIP 标识 + 登录方式）/ 添加 / 删除 / 清空
汽水音乐	PC 凭证列表（实时状态 + VIP 状态）/ 添加 / 更新 / 删除 / 启用停用

五、API 接口概览

5.1 基础信息

项目	值
Base URL	`http://localhost:5000`
请求方式	GET / POST
响应格式	JSON

统一响应格式：

{
  "status": 200,
  "success": true,
  "message": "操作描述",
  "data": { ... }
}

路由约定：

网易云接口：直接路径，如 /search、/song、/download
QQ音乐接口：路径加 /qq/ 前缀，如 /qq/search、/qq/song
汽水音乐接口：路径加 /qishui/ 前缀，如 /qishui/parse、/qishui/playlist
管理员接口：路径加 /admin/ 前缀

5.2 核心端点速查表

网易云音乐

端点	方法	说明
`/`	GET	Web 界面
`/health`	GET	健康检查（含元数据引擎状态）
`/cookie/status`	GET	Cookie 状态检测
`/search`	GET/POST	歌曲搜索
`/song`	GET/POST	单曲解析
`/playlist`	GET/POST	歌单解析
`/album`	GET/POST	专辑解析
`/toplist`	GET	官方榜单（无 id=列表，有 id=详情）
`/download`	GET/POST	音乐下载
`/download/batch`	POST	批量打包下载 ZIP
`/qr/key`	GET	生成二维码
`/qr/status`	GET	检查扫码状态

QQ音乐

端点	方法	说明
`/qq/search`	POST	歌曲搜索
`/qq/song`	POST	单曲解析
`/qq/lyric`	GET	获取歌词
`/qq/album`	GET	专辑解析
`/qq/playlist`	GET	歌单解析
`/qq/toplist`	GET	官方榜单（需登录）
`/qq/singer`	GET	歌手信息
`/qq/mv`	GET	MV 解析
`/qq/download`	POST	音乐下载
`/qq/download/batch`	POST	批量打包下载 ZIP
`/qq/cookie/status`	GET	Cookie 状态（多账号 + VIP 标识）
`/qq/qr/create`	POST	生成扫码二维码（3/min）
`/qq/qr/check`	GET	查询扫码状态（60/min）
`/qq/qr/exchange`	POST	MOBILE 方式换取 Cookie（10/min）
`/qq/qr/cancel`	POST	取消扫码登录

汽水音乐

端点	方法	说明
`/qishui/search`	GET/POST	搜索歌曲（需 PC 凭证）
`/qishui/parse`	POST	单曲解析（含 CENC 解密）
`/qishui/playlist`	GET/POST	歌单解析（支持完整分享文本）
`/qishui/download`	POST	单曲下载（自动解密）
`/qishui/download/batch`	POST	批量打包下载 ZIP
`/qishui/stream`	GET/POST	流式播放（含解密版）
`/qishui/debug-pc`	GET	调试 PC 凭证

5.3 调用示例

# 健康检查
curl http://localhost:5000/health

# 网易云搜索
curl -X POST http://localhost:5000/search \
  -d "keyword=周杰伦 稻香&limit=10"

# 网易云单曲解析
curl -X POST http://localhost:5000/song \
  -d "id=185668&level=lossless&type=json"

# 直接下载文件
curl -X POST http://localhost:5000/download \
  -d "id=185668&quality=lossless" \
  -o "song.flac"

# 汽水音乐单曲解析（支持完整分享文本）
curl -X POST http://localhost:5000/qishui/parse \
  -H "Content-Type: application/json" \
  -d '{"input":"歌单｜我喜欢 https://qishui.douyin.com/s/iQgxdHx2/ @汽水音乐"}'

六、配置文件详解

主配置文件 config.php 主要配置项：

基础配置

常量	默认值	说明
`NETEASE_PORT`	`5000`	服务监听端口
`DOWNLOADS_DIR`	`./downloads`	下载目录
`COOKIE_FILE`	`./cookie.txt`	网易云 Cookie 文件
`QQ_COOKIE_FILE`	`./qq_cookie.txt`	QQ音乐 Cookie 文件（多账号 JSON）
`MAX_FILE_SIZE`	`500MB`	最大文件大小限制
`DOWNLOAD_RETENTION_DAYS`	`0`	下载文件保留天数（0 = 不清理）
`CORS_ORIGINS`	`*`	CORS 跨域来源
`FFMPEG_PATH`	环境变量	ffmpeg 路径，留空自动检测

管理员安全配置

常量	默认值	说明
`ADMIN_PASSWORD`	`admin123`	管理员密码（部署后必须修改）
`ADMIN_TOKEN_TTL`	`86400`	Token 有效期（秒，默认 24 小时）
`ADMIN_LOGIN_MAX_FAILS`	`5`	连续密码错误次数上限
`ADMIN_LOGIN_BAN_DURATION`	`7200`	封禁时长（秒）
`ADMIN_CAPTCHA_TTL`	`300`	验证码有效期（秒）
`TRUSTED_PROXY_IPS`	`[]`	可信反向代理 IP（Nginx 部署必须配置）

汽水音乐配置

常量	默认值	说明
`QISHUI_ENABLED`	`true`	启用汽水音乐
`QISHUI_PC_DEVICE_ID`	`''`	兜底 PC device_id
`QISHUI_PC_COOKIE`	`''`	兜底 PC Cookie
`QISHUI_PC_IID`	`''`	兜底 PC iid
`QISHUI_PC_CREDS_FILE`	`./qishui_pc_creds.json`	PC 凭证文件（多凭证轮询）
`QISHUI_PROXY_URL`	`''`	Node.js 代理 URL（绕过 IP 风控）

七、技术实现亮点

双模式元数据写入架构

项目采用双模式架构写入音频元数据/封面/歌词，确保在各种环境都能正常工作：

模式	引擎	说明	支持格式
主模式	ffmpeg	命令行工具，支持全格式	MP3/FLAC/M4A/MP4/OGG/Opus
降级模式	getID3	纯 PHP 库，无需外部依赖	MP3/FLAC/OGG/Opus

工作流程：

启动时检测 ffmpeg（优先 FFMPEG_PATH 常量/环境变量，其次 PATH 查找）
下载完成后优先调用 ffmpeg 写入元数据
ffmpeg 不可用或写入失败时，自动降级到 getID3 纯 PHP 库
前端在单曲解析和音乐下载界面实时显示当前使用的引擎

汽水音乐 CENC 解密

汽水音乐 PC 完整版音源使用 CENC (Common Encryption) AES-CTR 加密。解密流程（qishui_decryptor.php 实现）：

从 spade_a (playAuth) 提取 16 字节 AES-128 密钥（SpadeDecryptor 算法）
解析 MP4 atom 结构，定位 moov/trak/mdia/minf/stbl/senc/stsz/mdat
读取每个 sample 的 IV（8 字节，后补 8 字节 0 得到 16 字节 IV）
用 AES-128-CTR 解密每个 sample
将 stsd box 中的 enca 替换为 mp4a（让播放器识别为普通音频）

仅这两步是必要的。删除 sinf/senc/saio/saiz 等加密元数据是多余操作，会破坏文件结构。

网易云 EAPI 加密算法

URL 路径 /eapi/ 替换为 /api/
计算摘要 MD5("nobody{path}use{payload}md5forencrypt")
拼接参数 {path}-36cd479b6b5-{payload}-36cd479b6b5-{digest}
AES-128-ECB 加密（PKCS7 填充）
转换为十六进制字符串

PHP 实现使用 openssl_encrypt() + AES-128-ECB。

QQ音乐签名算法

QQ音乐 musicu.fcg / musics.fcg 接口请求签名（zzc_sign）：

SHA1(payload) 得到 40 位十六进制大写
part1 / part2：按固定索引从 hash 取字符
part3：20 字节，每字节 = 预置 scramble 值 XOR hash 的对应字节
base64(part3) 去除 \/+=
返回 zzc + part1 + b64 + part2（小写）

g_tk 参数使用 hash33(musickey, 5381) & 0x7FFFFFFF 算法计算。

三层敏感文件防护

以下文件禁止通过 Web 直接访问（返回 403）：

Web 服务器	实现方式
PHP 内置服务器	`index.php` 中正则匹配拦截
Apache	`.htaccess` 的 `<FilesMatch>` 规则
Nginx	`Nginx_Rewrite.txt` 的 `location` 规则

受保护文件包括：cookie.txt、qq_cookie.txt、qishui_pc_creds.json、config.php、所有 API 类文件、管理员运行时文件、.env、.htaccess、downloads/ 目录等。

八、注意事项

8.1 安全注意事项

必须修改管理员密码：默认 admin123 是公开信息，部署后第一时间在 config.php 修改 ADMIN_PASSWORD
生产环境限制 CORS：默认 * 允许所有来源跨域，建议改为特定域名
```
define('CORS_ORIGINS', 'https://yourdomain.com');
```
Nginx 反向代理必须配置可信代理 IP：否则限流和封禁将基于 Nginx IP 失效
Token 文件权限：管理员 token 文件使用 chmod 0600 严格权限，确保仅文件所有者可读写
不要将 Cookie 文件提交到版本库：cookie.txt、qq_cookie.txt、qishui_pc_creds.json 等包含敏感信息

8.2 合规使用注意事项

本项目仅供学习和个人使用，请遵守各音乐平台的用户协议
下载的音乐文件版权归原作者所有，不得用于商业用途
大规模批量下载可能触发平台风控，请适度使用
建议优先使用各平台官方客户端

8.3 部署注意事项

PHP 版本：必须 ≥ 7.4，推荐 8.0+，老旧 PHP 版本可能存在兼容性问题
必需扩展：curl、openssl、zip、fileinfo 缺一不可，缺失会直接报错
虚拟主机限制：若 shell_exec/exec 被禁用，ffmpeg 不可用，程序会自动降级到 getID3
下载目录权限：downloads/ 目录必须可写，否则下载会失败
汽水音乐 IP 风控：海外服务器或机房 IP 容易被风控，建议使用国内服务器或部署 Node.js 代理

8.4 性能注意事项

批量下载限制：单次最多 200 首，避免内存和时间耗尽
ZIP 压缩策略：采用 CM_STORE（不压缩），节省 CPU
下载文件清理：通过 DOWNLOAD_RETENTION_DAYS 配置自动清理，避免磁盘占满
扫码登录限流：
- /qq/qr/create 3 次/分钟（与 QQ 音乐 IP 风控阈值一致）
- /qq/qr/check 60 次/分钟
- /qq/qr/exchange 10 次/分钟（防止 token 暴力枚举）

九、常见问题 FAQ

Q1：获取播放链接返回 `url: null` 或 `size: 0`？

原因：

Cookie 未配置或已失效 → 网页扫码登录或执行 php qr_login.php login
音质需要更高 VIP 等级 → 尝试降低音质（如 exhigh）
歌曲版权限制 → 换其他歌曲

空 cookie.txt 会导致网易云 API 返回 null URL 和 0 size，下载文件会显示 0B。

Q2：QQ音乐接口返回 401 或提示”需要登录凭证”？

QQ音乐部分接口（榜单、歌单详情等）需要登录凭证：

在 Web 界面切换到 QQ音乐源
功能选择：扫码登录 → 选择方式（手机QQ / 微信 / QQ音乐APP）→ 生成二维码 → 扫码
登录成功后 Cookie 自动保存到 qq_cookie.txt（含 login_method 字段）
重新访问受限接口

musickey 约 7 天过期，程序会自动检测并在可能时刷新。如刷新失败，重新扫码登录。

Q3：QQ音乐扫码提示”腾讯风控拦截”？

腾讯对当前服务器 IP 做了风控限制（主要影响 QQ 方式）。解决方案：

改用微信或 QQ音乐APP 方式扫码（不同协议，风控策略不同）
稍后重试（风控通常几小时后解除）
更换网络环境（如切换到家庭宽带）
部署到国内服务器
手动复制 Cookie 到 qq_cookie.txt

Q4：三种扫码方式如何选择？

方式	优势	限制
手机QQ	最通用，支持所有 QQ 账号	可能被腾讯 IP 风控
微信	支持微信账号，风控较少	需微信扫码
QQ音乐APP	官方协议，无 IP 风控	需安装QQ音乐 APP

推荐优先级：QQ音乐APP > 微信 > 手机QQ

Q5：汽水音乐解析返回 60 秒预览版？

原因：PC 凭证未配置或调用失败，降级使用 H5 SEO 预览版接口。

解决方案：

通过管理员后台（/admin/）添加有效 PC 凭证
或在 config.php 配置 QISHUI_PC_DEVICE_ID / QISHUI_PC_COOKIE 兜底凭证
获取凭证步骤见本文配置 Cookie（关键步骤）章节

前端会显示对应徽章：

no_cred – 未配置凭证
pc_failed – 凭证调用失败

Q6：汽水音乐歌单只显示 151 首（实际有 312 首）？

原因：远程服务器 IP 被汽水音乐风控，本地能获取 312 首但远程只返回 151 首。

解决方案：部署 Node.js 代理服务绕过风控：

cd qishui_proxy && npm install
node server.js --prod
# 在 config.php 中配置: define('QISHUI_PROXY_URL', 'http://127.0.0.1:5200');

Q7：下载的汽水音乐 m4a 文件无法播放？

原因：CENC 加密的 m4a 未正确解密。

正确解密流程（已内置实现）：

逐 sample AES-CTR 解密 mdat
enca → mp4a 替换

⚠️ 删除 sinf/senc/saio/saiz 等加密元数据是多余操作，会破坏文件结构。当前实现仅做必要的两步解密。

Q8：提示 `Call to undefined function curl_init()`？

PHP 未启用必需扩展（curl / openssl / zip）：

# 方式 1：修改 php.ini，取消注释
extension=curl
extension=openssl
extension=zip

# 方式 2：启动时临时加载
php -d extension=curl -d extension=openssl -d extension=zip -S 0.0.0.0:5000 index.php

Q9：下载的文件没有封面/元数据/歌词？

程序采用双模式写入元数据：优先使用 ffmpeg，不可用时降级到内置的 getID3 纯 PHP 库。

前端提示检查：单曲解析和音乐下载界面顶部会显示当前元数据引擎状态

安装 ffmpeg（推荐，支持全格式含 M4A/MP4）：

# Linux
sudo apt install ffmpeg

# macOS
brew install ffmpeg

# Windows: 下载 https://ffmpeg.org/download.html 并添加到 PATH

或确保 getID3 库完整（纯 PHP，无需安装，支持 MP3/FLAC/OGG/Opus）
虚拟主机注意：若 shell_exec/exec 被禁用，ffmpeg 不可用，程序会自动降级到 getID3
文件已存在跳过元数据写入：默认情况下已存在的文件会直接返回。使用 force=1 参数强制重新下载并写入元数据。

Q10：Nginx 反向代理部署后，管理员封禁/限流失效？

原因：未配置可信代理 IP，导致 getClientIp() 取到的是 Nginx 的 IP 而非真实客户端 IP。

解决方案：在 config.php 中配置：

// 填入你的 Nginx 服务器 IP
define('TRUSTED_PROXY_IPS', ['127.0.0.1']);

仅当请求来自此处列出的 IP 时，才会信任 X-Forwarded-For 头。

Q11：如何修改监听端口？

# 方式 1：启动时指定
php -S 0.0.0.0:8080 index.php

# 方式 2：修改 config.php
define('NETEASE_PORT', 8080);

Q12：服务重启后 Cookie 丢失？

不会丢失。扫码登录后 Cookie 写入文件持久保存（网易云 cookie.txt / QQ音乐 qq_cookie.txt / 汽水音乐 qishui_pc_creds.json），重启服务不影响。若 Cookie 失效，重新扫码登录即可。

Q13：批量下载最多能下多少首？

单次批量下载限制为 200 首（downloadBatchAsZip 方法内置限制），防止内存和时间耗尽。ZIP 采用 CM_STORE 压缩（音频文件不压缩），节省 CPU。

Q14：下载目录会自动清理吗？

会。配置 DOWNLOAD_RETENTION_DAYS（默认 0 = 不清理）：

设为 7 则自动删除超过 7 天的下载音频文件
清理在 MusicDownloader 初始化时触发（懒清理）
仅清理音频文件（mp3/flac/m4a/mp4/ogg/opus/eac3）

十、CLI 工具

qr_login.php 提供网易云命令行扫码登录功能：

# 扫码登录（推荐）
php qr_login.php login

# 查看登录状态
php qr_login.php status

# 登出（清除 Cookie，自动备份）
php qr_login.php logout

QQ音乐和汽水音乐扫码登录仅支持 Web 界面操作。

十一、支持的链接格式

# 网易云歌曲链接
https://music.163.com/song?id=1234567890
https://music.163.com/#/song?id=1234567890

# 网易云歌单链接
https://music.163.com/playlist?id=1234567890

# 网易云专辑链接
https://music.163.com/album?id=1234567890

# 网易云短链接（自动解析重定向）
https://163cn.tv/xxxxx

# 直接使用 ID
1234567890

# QQ音乐支持歌曲 MID（字符串）或数字 ID
001Bbywq2gicae

# 汽水音乐分享链接（支持完整分享文本）
https://qishui.douyin.com/s/iQgxdHx2/
歌单｜我喜欢 https://qishui.douyin.com/s/iQgxdHx2/ @汽水音乐
https://fanqier.com/...

# 汽水音乐 track_id（纯数字）
7456789012345

十二、致谢与许可

致谢

原项目作者：Suxiaoqinx – Netease_url
QQ音乐 API 参考与移植：l-1124 – QQMusicApi
汽水音乐 CENC 解密参考：520Qiuyu – qishuiMusicAnalysis
Ravizhan
getID3 – 纯 PHP 元数据读写库

许可证

MIT License

本项目旨在为开源社区做贡献，鼓励用户在遵守开源精神的前提下使用和分享代码。虽然 MIT 许可证允许商业使用，但希望用户能尊重开源精神，合理使用本项目。

总结

「音乐工具箱 PHP 版」是一个功能完备、部署简单的多源音乐解析下载工具。其核心优势在于：

零框架依赖：纯 PHP 实现，对运行环境要求极低
三源合一：网易云、QQ音乐、汽水音乐统一界面管理
完整功能链：从搜索到下载，元数据/封面/歌词一步到位
企业级安全：多 token 模型、可信代理白名单、限流防护
跨平台部署：内置服务器、Apache、Nginx、Docker 全支持
灵活降级策略：ffmpeg 不可用时自动降级到 getID3，汽水音乐无凭证时降级到预览版

如果你在部署过程中遇到任何问题，欢迎查阅本文的常见问题 FAQ 章节。祝你部署顺利！

下载

下载 “Music_php_url” Music_php_url.rar – 已下载1次 –

What’s your Reaction?