NeteaseMiniPlayer v2 贡献指南

欢迎贡献

欢迎为 NeteaseMiniPlayer v2 项目做出贡献！NeteaseMiniPlayer v2 是一个基于原生 JavaScript 开发的轻量级网易云音乐播放器，采用纯静态架构，无需复杂的构建工具和依赖管理。

📖 项目概述

项目特点

核心优势

🎯 轻量级设计：仅使用原生 JavaScript、CSS3 和 HTML5，无第三方依赖
🎨 美观界面：现代化 UI 设计，支持亮色/暗色主题自动切换
📱 响应式布局：完美适配桌面端和移动端设备
⚡ 高性能：优化的代码结构，快速加载和流畅播放
🔧 易于集成：简单的 API 设计，可轻松嵌入任何网站

技术栈

技术详情

前端技术：JavaScript ES6+、CSS3、HTML5 Audio API
网络请求：Fetch API
音乐数据：NeteaseCloudMusicApi 4.x
构建工具：无需构建工具，直接使用原生代码
文档系统：VitePress

项目结构

NeteaseMiniPlayer/
├── netease-mini-player.js    # 核心播放器 JavaScript 代码
└─  netease-mini-player.css   # 播放器样式文件

🤝 如何贡献

贡献方式

贡献指南

请在开始贡献前仔细阅读以下指南，确保您的贡献符合项目标准。

🐛 报告 Bug：发现播放器问题请提交 Issue
💡 功能建议：提出新功能想法和改进建议
📝 文档改进：完善使用文档、API 文档或示例
🔧 代码贡献：修复 Bug、优化性能或添加新功能
🎨 UI/UX 改进：改善界面设计和用户体验
🌐 兼容性测试：在不同浏览器和设备上测试

开发环境准备

简单环境

由于本项目是纯静态项目，开发环境非常简单：

基础要求
- 现代浏览器（Chrome 88+、Firefox 85+、Safari 14+、Edge 88+）
- 文本编辑器或 IDE（推荐 VS Code）
- 本地 HTTP 服务器（用于测试，避免 CORS 问题），或者直接访问你的.html文件

获取项目代码

bash

# Fork 项目后克隆到本地
git clone https://github.com/your-username/NeteaseMiniPlayer.git
cd NeteaseMiniPlayer

启动本地服务器

bash

# 使用 Python（如果已安装）
python -m http.server 8000

# 或使用 Node.js（如果已安装）
npx serve .

# 或使用 VS Code Live Server 扩展

参与流程

Fork 项目
- 在 GitHub 上 Fork NeteaseMiniPlayer v2 到你的账户

创建分支

bash

git checkout -b feature/your-feature-name
# 或
git checkout -b fix/your-bug-fix

开发和测试
- 修改 netease-mini-player-v2.js 或 netease-mini-player-v2.css
- 在浏览器中测试功能
- 确保在不同设备和浏览器上正常工作

提交更改

bash

git add .
git commit -m "feat: 添加新功能描述"
# 或
git commit -m "fix: 修复某个问题"

推送分支

bash

git push origin feature/your-feature-name

创建 Pull Request
- 在 GitHub 上创建 PR
- 详细描述你的更改和测试情况
- 等待代码审查

📋 开发规范

代码风格

JavaScript 规范

遵循项目现有的代码风格，参考 netease-mini-player-v2.js 中的实现：

javascript

// ✅ 推荐的代码风格（基于项目实际代码）
class NeteaseMiniPlayer {
  constructor(config = {}) {
    // 使用对象解构和默认值
    this.config = this.parseConfig(config);
    this.isPlaying = false;
    this.currentSong = null;
    this.playlist = [];
    
    // 初始化
    this.init();
  }

  /**
   * 解析配置参数
   * @param {Object} config - 用户配置
   * @returns {Object} 解析后的配置
   */
  parseConfig(config) {
    const defaultConfig = {
      theme: 'auto',
      position: 'bottom-right',
      autoplay: false,
      volume: 0.8
    };
    
    return { ...defaultConfig, ...config };
  }

  /**
   * 异步获取歌曲信息
   * @param {string} songId - 歌曲ID
   * @returns {Promise<Object>} 歌曲信息
   */
  async fetchSongInfo(songId) {
    try {
      const response = await fetch(`https://api.hypcvgm.top/NeteaseMiniPlayer/nmp.php/song/detail?ids=${songId}`);
      const data = await response.json();
      return data;
    } catch (error) {
      console.error('获取歌曲信息失败:', error);
      throw error;
    }
  }

  // 私有方法使用下划线前缀
  _createPlayerElement() {
    const player = document.createElement('div');
    player.className = 'netease-mini-player';
    return player;
  }
}

// 常量定义
// api 基础 url 可以选择自己部署的 api 或者使用其他部署的 api
// 注意：使用其他部署的 api 时，需要确保 api 支持 CORS 跨域请求
// 默认使用 https://api.hypcvgm.top/NeteaseMiniPlayer/nmp.php 作为 api 基础 url
const API_BASE_URL = 'https://api.hypcvgm.top/NeteaseMiniPlayer/nmp.php';
const SUPPORTED_FORMATS = ['mp3', 'flac', 'wav'];

CSS 规范

遵循项目的 CSS 变量和响应式设计模式：

css

/* ✅ 推荐的 CSS 风格（基于项目实际样式） */
:root {
  /* 亮色主题 */
  --nmp-primary-color: #ec4141;
  --nmp-bg-color: #ffffff;
  --nmp-text-color: #333333;
  --nmp-border-color: #e0e0e0;
}

/* 深色主题 */
@media (prefers-color-scheme: dark) {
  :root {
    --nmp-primary-color: #ff6b6b;
    --nmp-bg-color: #1a1a1a;
    --nmp-text-color: #ffffff;
    --nmp-border-color: #333333;
  }
}

.netease-mini-player {
  position: fixed;
  background: var(--nmp-bg-color);
  border: 1px solid var(--nmp-border-color);
  border-radius: 12px;
  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.1);
  transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
}

/* 响应式设计 */
@media (max-width: 768px) {
  .netease-mini-player {
    width: calc(100% - 20px);
    margin: 10px;
  }
}

API 使用规范

NeteaseCloudMusicApi 接口

项目使用的主要 API 接口：

javascript

// 1. 获取歌曲详情
const songDetailUrl = `${API_BASE_URL}/song/detail?ids=${songId}`;

// 2. 获取歌曲播放链接
const songUrlApi = `${API_BASE_URL}/song/url/v1?id=${songId}&level=exhigh`;

// 3. 获取歌词
const lyricApi = `${API_BASE_URL}/lyric?id=${songId}`;

// 4. 获取歌单详情
const playlistApi = `${API_BASE_URL}/playlist/detail?id=${playlistId}`;

// 5. 搜索歌曲
const searchApi = `${API_BASE_URL}/search?keywords=${keywords}&type=1`;

API 返回数据结构

基于项目提供的示例数据：

javascript

// 歌曲播放链接返回格式
{
  "data": [{
    "id": 534541512,
    "url": "http://m704.music.126.net/...",
    "br": 320000,        // 比特率
    "size": 11375848,    // 文件大小
    "type": "mp3",       // 文件格式
    "time": 284328       // 时长（毫秒）
  }]
}

// 歌词返回格式
{
  "lrc": {
    "lyric": "[00:00.00] 作词 : 瀧田綺美\n[00:06.79]描いてた未来へ駆け抜ける願いを\n..."
  },
  "tlyric": {
    "lyric": "[00:06.79]向着描绘的未来奔跑的愿望\n..."  // 翻译歌词
  }
}

命名规范

变量和函数：camelCase（如 currentSong, fetchSongInfo）
常量：UPPER_SNAKE_CASE（如 API_BASE_URL）
类名：PascalCase（如 NeteaseMiniPlayer）
CSS 类：kebab-case（如 netease-mini-player）
CSS 变量：kebab-case with prefix（如 --nmp-primary-color）

错误处理

javascript

// ✅ 推荐的错误处理方式
async function fetchWithRetry(url, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url);
      if (!response.ok) {
        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
      }
      return await response.json();
    } catch (error) {
      console.warn(`请求失败 (${i + 1}/${maxRetries}):`, error.message);
      if (i === maxRetries - 1) {
        throw new Error(`请求失败，已重试 ${maxRetries} 次: ${error.message}`);
      }
      // 等待后重试
      await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
    }
  }
}

🧪 测试要求

浏览器兼容性测试

由于是纯静态项目，重点关注浏览器兼容性：

桌面端：Chrome 88+、Firefox 85+、Safari 14+、Edge 88+
移动端：iOS Safari 14+、Android Chrome 88+
功能测试：
- 音频播放和暂停
- 进度条拖拽
- 音量控制
- 歌词显示和滚动
- 主题切换
- 响应式布局

手动测试清单

markdown

## 基础功能测试
- [ ] 播放器初始化正常
- [ ] 歌曲加载和播放
- [ ] 暂停和继续播放
- [ ] 进度条显示和拖拽
- [ ] 音量调节
- [ ] 上一首/下一首切换

## 界面测试
- [ ] 亮色/暗色主题切换
- [ ] 移动端响应式布局
- [ ] 歌词显示和滚动
- [ ] 播放列表展示
- [ ] 加载状态显示

## 兼容性测试
- [ ] Chrome 浏览器
- [ ] Firefox 浏览器
- [ ] Safari 浏览器
- [ ] 移动端浏览器
- [ ] 不同屏幕尺寸

## 错误处理测试
- [ ] 网络断开时的处理
- [ ] 无效歌曲ID的处理
- [ ] API 请求失败的处理

性能测试

javascript

// 性能监控示例
function measurePerformance(label, fn) {
  const start = performance.now();
  const result = fn();
  const end = performance.now();
  console.log(`${label}: ${(end - start).toFixed(2)}ms`);
  return result;
}

// 使用示例
measurePerformance('播放器初始化', () => {
  new NeteaseMiniPlayer(config);
});

📚 项目资源

官方链接

🏠 项目主页：https://nmp.hypcvgm.top/
📦 GitHub 仓库：https://github.com/numakkiyu/NeteaseMiniPlayer
📖 API 文档：https://neteasecloudmusicapi.js.org/
📝 技术详解：NeteaseMiniPlayer技术实现详解

学习资源

🎵 网易云音乐 API：了解音乐数据获取和处理
🎨 现代 CSS：学习 CSS 变量、Grid、Flexbox 等现代特性
⚡ 原生 JavaScript：掌握 ES6+ 语法和 Web API
📱 响应式设计：适配不同设备和屏幕尺寸

开发工具推荐

编辑器：VS Code + 相关扩展
- Live Server：本地服务器
- Prettier：代码格式化
- ESLint：代码检查
浏览器：Chrome DevTools 进行调试
设计工具：Figma 或 Sketch（UI 设计）

🐛 问题报告

Bug 报告模板

提交 Issue 时请包含以下信息：

markdown

## Bug 描述
简要描述遇到的问题

## 复现步骤
1. 打开播放器
2. 点击播放按钮
3. 观察到的问题

## 预期行为
描述你期望的正确行为

## 实际行为
描述实际发生的情况

## 环境信息
- 浏览器：Chrome 120.0.0.0
- 播放器版本：v2.0.4
- 设备类型：桌面端/移动端

功能请求模板

markdown

## 功能描述
详细描述你希望添加的功能

## 使用场景
说明这个功能的使用场景和必要性

## 实现建议
如果有想法，可以提供实现建议

## 参考示例
提供类似功能的参考示例（如果有）

💡 贡献建议

适合新手的任务

🐛 修复小 Bug：从简单的问题开始
📝 改进文档：完善使用说明和示例
🎨 UI 优化：改善界面细节和用户体验
🌐 兼容性测试：在不同浏览器和设备上测试

进阶任务

⚡ 性能优化：减少内存使用，提升加载速度
🎵 新功能开发：添加播放模式、均衡器等功能
🔧 代码重构：优化代码结构和可维护性
📱 移动端优化：改善移动设备上的体验

专家级任务

🏗️ 架构设计：设计新的模块化架构
🔒 安全性：改善 API 调用的安全性
🌍 国际化：支持多语言界面
🎛️ 插件系统：设计可扩展的插件架构

再次感谢你对 NeteaseMiniPlayer v2 项目的关注和贡献！ 🎉

如果你在贡献过程中遇到任何问题，请随时通过 GitHub Issues 联系我们。让我们一起打造更好的音乐播放体验！

📝 提交规范

Commit Message 格式

使用 Conventional Commits 规范：

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

类型说明

feat: 新功能
fix: Bug 修复
docs: 文档更新
style: 代码格式调整（不影响功能）
refactor: 代码重构
perf: 性能优化
test: 测试相关
chore: 构建过程或辅助工具的变动

示例

bash

# 新功能
git commit -m "feat: 添加歌词滚动功能"

# Bug 修复
git commit -m "fix: 修复移动端播放按钮点击问题"

# 文档更新
git commit -m "docs: 更新 API 使用说明"

# 样式调整
git commit -m "style: 调整播放器圆角样式"

# 性能优化
git commit -m "perf: 优化歌曲加载速度"

Pull Request 规范

PR 标题格式

<type>: <description>

PR 描述模板

markdown

## 变更类型
- [ ] 新功能
- [ ] Bug 修复
- [ ] 文档更新
- [ ] 代码重构
- [ ] 性能优化
- [ ] 其他

## 变更描述
详细描述本次 PR 的变更内容

## 测试情况
- [ ] 在 Chrome 浏览器测试通过
- [ ] 在 Firefox 浏览器测试通过
- [ ] 在移动端测试通过
- [ ] 功能测试通过
- [ ] 回归测试通过

## 相关 Issue
关联的 Issue 编号（如果有）

## 截图或录屏
如果涉及 UI 变更，请提供截图或录屏

## 检查清单
- [ ] 代码遵循项目规范
- [ ] 已添加必要的注释
- [ ] 已测试相关功能
- [ ] 文档已更新（如需要）

🔄 版本发布

版本号规范

遵循 Semantic Versioning 规范：

MAJOR: 不兼容的 API 修改
MINOR: 向下兼容的功能性新增
PATCH: 向下兼容的问题修正

再次感谢你对 NeteaseMiniPlayer v2 项目的关注和贡献！ 🎉

如果你在贡献过程中遇到任何问题，请随时通过 GitHub Issues 联系我们。让我们一起打造更好的音乐播放体验！

NeteaseMiniPlayer v2 贡献指南 ​

📖 项目概述 ​

项目特点 ​

技术栈 ​

项目结构 ​

🤝 如何贡献 ​

贡献方式 ​

开发环境准备 ​

参与流程 ​

📋 开发规范 ​

代码风格 ​

JavaScript 规范 ​

CSS 规范 ​

API 使用规范 ​

NeteaseCloudMusicApi 接口 ​

API 返回数据结构 ​

命名规范 ​

错误处理 ​

🧪 测试要求 ​

浏览器兼容性测试 ​

手动测试清单 ​

性能测试 ​

📚 项目资源 ​

官方链接 ​

学习资源 ​

开发工具推荐 ​

🐛 问题报告 ​

Bug 报告模板 ​

功能请求模板 ​

💡 贡献建议 ​

适合新手的任务 ​

进阶任务 ​

专家级任务 ​

📝 提交规范 ​

Commit Message 格式 ​

类型说明 ​

示例 ​

Pull Request 规范 ​

PR 标题格式 ​

PR 描述模板 ​

🔄 版本发布 ​

版本号规范 ​

NeteaseMiniPlayer v2 贡献指南

📖 项目概述

项目特点

技术栈

项目结构

🤝 如何贡献

贡献方式

开发环境准备

参与流程

📋 开发规范

代码风格

JavaScript 规范

CSS 规范

API 使用规范

NeteaseCloudMusicApi 接口

API 返回数据结构

命名规范

错误处理

🧪 测试要求

浏览器兼容性测试

手动测试清单

性能测试

📚 项目资源

官方链接

学习资源

开发工具推荐

🐛 问题报告

Bug 报告模板

功能请求模板

💡 贡献建议

适合新手的任务

进阶任务

专家级任务

📝 提交规范

Commit Message 格式

类型说明

示例

Pull Request 规范

PR 标题格式

PR 描述模板

🔄 版本发布

版本号规范