docs: improve README

2026-07-22 16:51:56 +08:00
parent 7fc8fdaa8f
commit ab7c9ee272
1 changed files with 137 additions and 0 deletions
@@ -1 +1,138 @@
+# 网易云音乐下载器

+一个基于 Node.js 的网易云音乐命令行下载工具，支持单曲、歌单、专辑及批量下载，并可同步保存歌词、封面和歌曲标签。
+
+项目采用单文件实现，核心功能仅依赖 Node.js 内置模块。`node-id3`、`ffmpeg` 和本地音频播放器均为可选依赖。
+
+## 功能特性
+
+- 按关键词、歌曲 ID、歌手、歌单或专辑下载音乐
+- 支持多个歌曲 ID 及文件列表批量下载
+- 支持标准、极高、无损、Hi-Res、超清母带、空间音频和高清臻品音质
+- 下载原文歌词，并按时间轴合并翻译歌词
+- 下载封面，写入歌曲信息、歌词和封面标签
+- 查看歌曲详情、歌词、歌单内容和本地下载列表
+- 试听歌曲，导出下载历史，生成 M3U 播放列表
+- 自动识别文件名并补全已有音频文件的标签
+- 支持失败重试、下载暂停、历史统计、缓存清理和回收站
+
+## 环境要求
+
+- Node.js（建议使用当前维护中的 LTS 版本）
+- 可访问脚本所配置的音乐接口和网易云音乐
+
+可选依赖：
+
+- [`node-id3`](https://www.npmjs.com/package/node-id3)：为 MP3 写入封面、歌词和 ID3 标签
+- [`ffmpeg`](https://ffmpeg.org/)：为 FLAC 等格式写入封面和标签，也可作为 MP3 标签写入的后备方案
+- `mpv`、`ffplay`、`play`、`cvlc` 或 `aplay`：用于试听歌曲
+
+安装可选的 MP3 标签依赖：
+
+```bash
+npm install node-id3
+```
+
+## 快速开始
+
+克隆仓库后进入项目目录：
+
+```bash
+git clone https://git.draws.qzz.io/jocay/163-music-dl.git
+cd 163-music-dl
+node 163_music_downloader.js
+```
+
+不带参数运行时会进入中文交互菜单，可搜索、下载和管理歌曲。
+
+## 命令行模式
+
+直接下载一个或多个歌曲 ID：
+
+```bash
+node 163_music_downloader.js 347230 1859245776
+```
+
+下载完整歌单或专辑：
+
+```bash
+node 163_music_downloader.js --playlist=歌单ID
+node 163_music_downloader.js --album=专辑ID
+```
+
+可选参数：
+
+| 参数 | 说明 |
+| --- | --- |
+| `--level=<音质>` | 指定下载音质 |
+| `--retries=<次数>` | 指定失败重试次数，默认 `3` |
+| `--no-lyric` | 不下载歌词文件 |
+| `--no-cover` | 不下载封面，也不执行封面和标签嵌入 |
+
+示例：
+
+```bash
+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`。配置项包括接口地址、下载目录、历史记录路径、运行时配置路径、默认音质和重试次数。
+
+```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` 指定的目录
+- 下载历史保存在 `paths.historyFile` 指定的 JSON 文件中，默认最多保留 500 条
+- 交互菜单修改的音质设置保存在 `paths.runtimeConfigFile` 指定的文件中
+- 删除操作会先将文件移动到 `paths.trashDir`，而不是永久删除
+- ZIP 打包过程使用 `paths.tempZipDir` 作为临时目录
+
+下载文件名采用 `歌手 - 歌名` 格式，并自动移除文件系统不允许的字符。
+
+## 注意事项
+
+- 下载能力依赖第三方 `api.chksz.top` 接口，其可用性、音源和返回质量不由本项目保证。
+- 歌曲详情和专辑元数据会直接请求网易云音乐。
+- 请遵守当地法律法规、平台条款和音乐版权要求，仅将本工具用于合法用途。
+- 音频文件和压缩包已通过 `.gitignore` 排除，不会被提交到仓库。