Files

史悦 89a28e1bc5 feat: 添加网易云音乐同步到Navidrome的功能

新增NetEase-sync模块，实现将网易云音乐歌单同步到Navidrome的功能
修复iOS设备自动播放问题，优化播放器体验

2026-01-12 17:59:31 +08:00

4.0 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

没事Music 是一个基于 Web 的音乐播放器应用,采用单文件 React 架构,支持多平台音乐搜索、播放和同步功能。

架构设计

前端架构 (index.html)

单文件应用模式:

所有前端代码集中在 index.html (~89KB)
使用 Babel Standalone 在浏览器端编译 JSX
React 18 + Tailwind CSS + Font Awesome (均通过 CDN 引入)

核心组件结构:

App (主容器)
├── SideDrawer (侧边栏设置)
├── MiniPlayer (迷你播放器)
├── FullPlayer (全屏播放器)
├── PlaylistDrawer (播放列表)
└── TopListPage (排行榜页面)

状态管理:

使用 React Hooks (useState, useEffect, useRef, useMemo, useCallback)
数据持久化: localStorage (前缀 th_)
关键状态: playlist, favorites, currentSong, syncToken, syncMode

数据规范化:

normalizeSongId(): 全局强制歌曲 ID 为字符串类型
normalizeSongList(): 批量规范化歌曲列表
getSongDurationSeconds(): 统一处理不同来源的时长字段 (duration/dt/time/interval/length/playTime)

后端架构 (sync-server/server.js)

KV 存储服务:

基于 Node.js 原生 HTTP 服务器
文件系统存储: data/{token}_{key}.json
API 端点: GET/POST /kv/:key?token=...
Token 用于用户隔离

后台下载管理器:

自动检测歌曲列表数据并触发下载
文件命名: {歌手} - {歌名} [{平台}_{ID}]
文件名清理: Unicode 规范化 (NFC) + 非法字符替换
存储路径: MUSIC_DIR (默认 ./music)

同步策略

两种同步模式:

私有云同步 (syncMode: 'server'):
- 基于 Token 的 KV 存储
- 增量同步: 计算本地与上次同步的差异 (added/removed)
- 自动同步: 每 15 分钟执行一次
网易云歌单同步 (syncMode: 'netease_playlist'):
- 通过 TuneHub API 获取歌单
- 导入即替换逻辑
- 自动同步: 每 15 分钟执行一次

同步流程:

拉取远程 → 计算差异 → 合并本地(非覆盖) → 推送至私有云

外部 API 集成

TuneHub API (https://music-dl.sayqz.com):

搜索: /api/?type=search&keyword=...&source=...
歌词: /api/?source=...&id=...&type=lrc
排行榜列表: /api/?source=...&type=toplists
排行榜歌曲: /api/?source=...&id=...&type=toplist
歌单详情: /api/?type=playlist&id=...&source=...

支持平台: netease, kuwo, qq, kugou

部署架构

Docker Compose

services:
  music-canvas:      # 前端静态网站
    ports: 7481:3000

  sync-service:      # 同步服务
    ports: 7482:3001
    volumes:
      - ./data:/app/data      # KV 数据存储
      - ./music:/app/music    # 音乐文件存储

Nginx 配置

前端: / → http://127.0.0.1:7481
同步 API: /api/ → http://127.0.0.1:7482/ (去掉 /api 前缀)

开发注意事项

代码修改原则

ID 类型一致性: 所有歌曲 ID 必须保持字符串类型,使用 normalizeSongId() 处理
文件名清理: 使用 Unicode NFC 规范化 + 非法字符替换,避免跨平台问题
状态同步: 修改 favorites/playlist 后,确保同步逻辑正确触发
API 调用: 所有外部 API 调用通过 TuneHub API,不要直接调用各平台 API

关键常量

API_BASE = "https://music-dl.sayqz.com"
SYNC_API_BASE = "/api"  // 相对路径,依赖 Nginx 代理
SOURCES = ['netease', 'kuwo', 'qq', 'kugou']

本地开发

前端无需构建,直接用浏览器打开 index.html 即可。如需测试同步功能:

cd sync-server
node server.js  # 默认端口 3001

环境变量 (sync-server)

DATA_DIR: KV 数据存储目录 (默认 ./data)
MUSIC_DIR: 音乐文件存储目录 (默认 ./music)
PORT: 服务端口 (默认 3001)

4.0 KiB Raw Blame History