网易云音乐下载器

一个基于 Node.js 的网易云音乐命令行下载工具，支持单曲、歌单、专辑及批量下载，并可同步保存歌词、封面和歌曲标签。

项目采用 CommonJS 模块化结构，核心功能仅依赖 Node.js 内置模块。node-id3、ffmpeg 和本地音频播放器均为可选依赖。

功能特性

• 按关键词、歌曲 ID、歌手、歌单或专辑下载音乐
• 支持多个歌曲 ID 及文件列表批量下载
• 支持标准、极高、无损、Hi-Res、超清母带、空间音频和高清臻品音质
• 下载原文歌词，并按时间轴合并翻译歌词
• 下载封面，写入歌曲信息、歌词和封面标签
• 查看歌曲详情、歌词、歌单内容和本地下载列表
• 试听歌曲，导出下载历史，生成 M3U 播放列表
• 自动识别文件名并补全已有音频文件的标签
• 支持失败重试、下载暂停、历史统计、缓存清理和回收站

环境要求

• Node.js（建议使用当前维护中的 LTS 版本）
• 可访问脚本所配置的音乐接口和网易云音乐

可选依赖：

• node-id3：为 MP3 写入封面、歌词和 ID3 标签
• ffmpeg：为 FLAC 等格式写入封面和标签，也可作为 MP3 标签写入的后备方案
• mpv、ffplay、play、cvlc 或 aplay：用于试听歌曲

安装可选的 MP3 标签依赖：

npm install node-id3

快速开始

克隆仓库后进入项目目录：

git clone https://git.draws.qzz.io/jocay/163-music-dl.git
cd 163-music-dl
node 163_music_downloader.js

不带参数运行时会进入中文交互菜单，可搜索、下载和管理歌曲。

项目结构

163_music_downloader.js  # 命令行入口与交互菜单
lib/
  catalog.js             # 搜索与歌单接口
  config.js              # 应用配置、路径和默认值
  downloader.js          # 单曲下载主流程与重试
  history.js             # 下载历史读写
  lyrics.js              # 歌词获取、合并和制作信息解析
  metadata.js            # 网易云歌曲/专辑元数据与专辑目录
  network.js             # HTTP 请求和文件下载
  pause.js               # 批量任务暂停状态
  quality.js             # 音质解析与交互选择
  tagging.js             # 封面及音频标签写入
  utils.js               # 文件名、目录大小等通用工具

命令行模式

直接下载一个或多个歌曲 ID：

node 163_music_downloader.js 347230 1859245776

下载完整歌单或专辑：

node 163_music_downloader.js --playlist=歌单ID
node 163_music_downloader.js --album=专辑ID

可选参数：

参数	说明
--level=<音质>	指定下载音质
--retries=<次数>	指定失败重试次数，默认 3
--no-lyric	不下载歌词文件
--no-cover	不下载封面，也不执行封面和标签嵌入

示例：

node 163_music_downloader.js --playlist=歌单ID --level=lossless --retries=5
node 163_music_downloader.js 347230 --level=hires --no-cover

音质等级

参数值	音质
standard	标准
exhigh	极高
lossless	无损
hires	Hi-Res
jymaster	超清母带（默认）
sky	空间音频
jyeffect	高清臻品

实际可用音质取决于接口返回结果，接口可能返回低于请求等级的音源。

配置

程序启动时读取项目根目录的 config.json。配置项包括接口地址、下载目录、历史记录路径、运行时配置路径、默认音质和重试次数。

{
  "api": {
    "music": "https://api.chksz.top/api/163_music",
    "lyric": "https://api.chksz.top/api/163_lyric",
    "search": "https://api.chksz.top/api/163_search",
    "playlist": "https://api.chksz.top/api/163_playlist",
    "neteaseBaseUrl": "https://music.163.com"
  },
  "paths": {
    "downloadDir": "downloads",
    "historyFile": "download_history.json",
    "runtimeConfigFile": "downloader_config.json",
    "trashDir": ".trash",
    "tempZipDir": ".tmp_zip"
  },
  "defaults": {
    "quality": "jymaster",
    "retries": 3,
    "historyLimit": 500
  }
}

相对路径以脚本所在目录为基准，绝对路径会直接使用。仓库中的 config.json 可能配置了特定运行环境的下载路径，首次运行前请按本机环境调整 paths.downloadDir。

输出文件

• 音频和 .lrc 歌词保存在 paths.downloadDir 指定的目录
• 下载专辑时，专辑图片会保存为对应专辑目录下的 cover.jpg
• 下载历史保存在 paths.historyFile 指定的 JSON 文件中，默认最多保留 500 条
• 交互菜单修改的音质设置保存在 paths.runtimeConfigFile 指定的文件中
• 删除操作会先将文件移动到 paths.trashDir，而不是永久删除
• ZIP 打包过程使用 paths.tempZipDir 作为临时目录

下载文件名采用 歌手 - 歌名 格式，并自动移除文件系统不允许的字符。

注意事项

• 下载能力依赖第三方 api.chksz.top 接口，其可用性、音源和返回质量不由本项目保证。
• 歌曲详情和专辑元数据会直接请求网易云音乐。
• 请遵守当地法律法规、平台条款和音乐版权要求，仅将本工具用于合法用途。
• 音频文件和压缩包已通过 .gitignore 排除，不会被提交到仓库。