贡献指南
感谢您对 SPlayer for Android 的关注！本指南介绍如何为项目做出贡献。
范围约定
- 本仓库只接受 Android 相关改动；
- 跨平台 / 桌面端的问题与需求请提交到上游 imsyy/SPlayer。
前置知识
| 技术 | 说明 | 学习资源 |
|---|---|---|
| Vue 3 | 前端框架 | 官方文档 |
| TypeScript | 类型安全的 JavaScript | 官方手册 |
| Pinia | 状态管理 | 官方文档 |
| Vite | 构建工具 | 官方文档 |
| Naive UI | UI 组件库 | 官方文档 |
| Capacitor | Web → 原生桥接 | 官方文档 |
| Android / Java | 播放、通知、悬浮窗等原生层 | 官方文档 |
| Rust / wasm（可选） | 繁体转换 WASM 包 | Rust 程序设计语言 |
开发环境搭建
请参考 构建与发布 完成环境准备，然后：
bash
git clone https://github.com/SPlayer-Dev/SPlayer-for-Android.git
cd SPlayer-for-Android
pnpm install # postinstall 会自动修补 nodejs-mobile-cordova
pnpm build:android # 完整构建管线
cd android && ./gradlew assembleDebugGit 工作流
1. Fork 并克隆
bash
git clone https://github.com/YOUR_USERNAME/SPlayer-for-Android.git
cd SPlayer-for-Android
git remote add upstream https://github.com/SPlayer-Dev/SPlayer-for-Android.git2. 创建功能分支
从 dev 分支拉出，永远不要直接在主分支上开发：
bash
git checkout dev
git pull upstream dev
git checkout -b feat/player-xxx分支命名规范（小写 kebab-case）：
| 前缀 | 用途 |
|---|---|
feat/ | 新功能 |
fix/ | Bug 修复 |
refactor/ | 重构 |
docs/ | 文档 |
格式：<type>/<模块>-<简述>，如 fix/desktop-lyric-offset。
3. 提交
<type>(<scope>): <描述>| 类型 | 说明 |
|---|---|
feat | 新功能 |
fix | Bug 修复 |
perf | 性能优化 |
refactor | 重构 |
style | 代码格式（不影响功能） |
docs | 文档更新 |
test | 测试相关 |
chore | 构建 / 工具相关 |
ci | CI 配置 |
revert | 回滚 |
常用 scope：DesktopLyric / Player / Lyric / Search / Setting / Notification / Capacitor / Android / CI。
示例：
bash
git commit -m "feat(Player): 新增横屏沉浸式播放模式"
git commit -m "fix(Lyric): 修复 AMLL 歌词对齐偏移"4. 提交前自检
bash
pnpm lint # 0 错误 0 警告
pnpm typecheck # node + web 双端类型检查
pnpm build:web # 确认 Web 构建通过并在至少一台真机上验证改动；UI 改动请同时检查手机竖屏与平板横屏。
5. 创建 Pull Request
- 目标分支为
dev； - PR 标题与首个 commit 保持一致；
- 描述中说明动机与实现思路，关联 Issue（
Closes #123）； - UI 改动附前后对比截图；
- 一个 PR 只解决一个问题；
- 默认 squash merge；评审期间不要 force-push；
- 不要改动 workflow 中的签名 / Secrets 逻辑。
Issue 规范
- 一个 Issue 只描述一个问题，标题可被搜索；
- 保留模板字段，不要删除；
- Bug 报告必须包含：应用版本、设备型号、Android 版本、ABI、复现步骤，崩溃请附
adb logcat输出； - 提交前先搜索是否已有相同 Issue，并确认问题出现在本仓库而非上游桌面版；
- 不满足以上条件的 Issue 可能被关闭。
代码规范
- 包管理器只用 pnpm，禁止 npm / yarn；
- UI 组件只用 Naive UI，不引入其他 UI 库、不手写通用组件；
- 图标复用
src/assets/icons与SvgIcon组件； - 注释使用中文，保持简短；
- Prettier 风格：双引号、尾逗号、2 空格缩进、行宽 100；
- 未使用变量以
_前缀命名； - 新增功能前先检索项目内是否已有类似封装，优先复用。
目录结构
SPlayer-for-Android/
├── src/ # 前端源码（Vue 3）
│ ├── components/ # 组件（含 Setting 配置化设置项）
│ ├── stores/ # Pinia 状态
│ ├── views/ # 页面
│ ├── plugins/ # Capacitor 插件 JS 桥
│ ├── core/ # 播放器 / 下载 / 歌词调度核心
│ └── api/ # 网易云与流媒体 API 客户端
├── android/ # Android 原生工程（Java）
├── native/ # Rust workspace（opencc wasm 等）
├── API/ # 内置 / 独立网易云 API 服务
├── scripts/ # 构建脚本
└── docs/ # 文档（本站）获取帮助
感谢您的贡献！🎉