Skip to content

Commit 3cb0950

Browse files
imsyyimsyy
committed
📄 docs: 完善文档
1 parent 5b4a7af commit 3cb0950

12 files changed

Lines changed: 1332 additions & 128 deletions

File tree

‎auto-eslint.mjs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -96,11 +96,11 @@ export default {
9696
"refAutoReset": true,
9797
"refDebounced": true,
9898
"refDefault": true,
99-
"refManualReset": true,
10099
"refThrottled": true,
101100
"refWithControl": true,
102101
"resolveComponent": true,
103102
"resolveRef": true,
103+
"resolveUnref": true,
104104
"shallowReactive": true,
105105
"shallowReadonly": true,
106106
"shallowRef": true,

‎docs/.vitepress/config.ts‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,21 @@ export default defineConfig({
4040
},
4141
{
4242
text: "开发指南",
43-
items: [{ text: "原生插件", link: "/native" }],
43+
items: [
44+
{ text: "原生插件", link: "/native" },
45+
{ text: "贡献指南", link: "/contributing" },
46+
],
47+
},
48+
{
49+
text: "故障排查",
50+
items: [
51+
{ text: "调试模式和错误排查", link: "/troubleshooting/debug" },
52+
{ text: "macOS 常见问题", link: "/troubleshooting/macos" },
53+
{ text: "Mac 应用显示已损坏", link: "/troubleshooting/macos-damaged" },
54+
{ text: "macOS ARM 设备 API 启动失败", link: "/troubleshooting/macos-arm-api" },
55+
{ text: "Windows 7 系统兼容性问题", link: "/troubleshooting/windows7" },
56+
{ text: "Ubuntu 系统沙箱启动失败", link: "/troubleshooting/ubuntu-sandbox" },
57+
],
4458
},
4559
],
4660

‎docs/contributing.md‎

Lines changed: 252 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,252 @@
1+
# 贡献指南
2+
3+
感谢您对 SPlayer 的关注！本指南将帮助您了解如何为项目做出贡献。
4+
5+
## 前置知识
6+
7+
参与本项目开发需要掌握以下技术：
8+
9+
### 前端技术栈
10+
11+
| 技术 | 说明 | 学习资源 |
12+
| -------------- | --------------------- | ------------------------------------------------ |
13+
| **Vue 3** | 前端框架 | [官方文档](https://cn.vuejs.org/) |
14+
| **TypeScript** | 类型安全的 JavaScript | [官方手册](https://www.typescriptlang.org/docs/) |
15+
| **Pinia** | 状态管理 | [官方文档](https://pinia.vuejs.org/zh/) |
16+
| **Vite** | 构建工具 | [官方文档](https://cn.vitejs.dev/) |
17+
| **Naive UI** | UI 组件库 | [官方文档](https://www.naiveui.com/zh-CN/) |
18+
19+
### 桌面端技术栈
20+
21+
| 技术 | 说明 | 学习资源 |
22+
| ------------ | -------------------- | ------------------------------------------------------ |
23+
| **Electron** | 桌面应用框架 | [官方文档](https://www.electronjs.org/zh/docs/latest/) |
24+
| **N-API** | Node.js 原生模块接口 | [官方文档](https://nodejs.org/api/n-api.html) |
25+
26+
### 原生模块开发 (可选)
27+
28+
如需开发原生插件，还需掌握：
29+
30+
| 技术 | 说明 | 学习资源 |
31+
| --------------- | ---------------------- | ------------------------------------------------------------ |
32+
| **Rust** | 系统编程语言 | [Rust 程序设计语言](https://kaisery.github.io/trpl-zh-cn/) |
33+
| **napi-rs** | Rust 编写 Node.js 扩展 | [官方文档](https://napi.rs/) |
34+
| **Windows API** | Windows 系统编程 | [MSDN 文档](https://docs.microsoft.com/zh-cn/windows/win32/) |
35+
36+
## 开发环境搭建
37+
38+
请参考 [使用指南](/guide.html#本地开发环境) 完成以下准备工作：
39+
40+
1. 安装 Node.js (v18+)
41+
2. 安装 pnpm
42+
3. 安装 Git
43+
4. 克隆仓库并安装依赖
44+
5. (可选) 安装 Rust 和 C++ 构建工具
45+
46+
## Git 工作流
47+
48+
### 1. Fork 仓库
49+
50+
访问 [SPlayer 仓库](https://github.com/imsyy/SPlayer)，点击右上角 **Fork** 按钮复制仓库到你的账号。
51+
52+
### 2. 克隆你的 Fork
53+
54+
```bash
55+
# 克隆你的 Fork（替换 YOUR_USERNAME）
56+
git clone https://github.com/YOUR_USERNAME/SPlayer.git
57+
cd SPlayer
58+
59+
# 添加上游仓库
60+
git remote add upstream https://github.com/imsyy/SPlayer.git
61+
62+
# 验证远程仓库配置
63+
git remote -v
64+
# 应显示:
65+
# origin https://github.com/YOUR_USERNAME/SPlayer.git (fetch)
66+
# origin https://github.com/YOUR_USERNAME/SPlayer.git (push)
67+
# upstream https://github.com/imsyy/SPlayer.git (fetch)
68+
# upstream https://github.com/imsyy/SPlayer.git (push)
69+
```
70+
71+
### 3. 同步上游更新
72+
73+
在开始新功能开发前，确保本地代码是最新的：
74+
75+
```bash
76+
# 获取上游最新代码
77+
git fetch upstream
78+
79+
# 切换到主分支
80+
git checkout main
81+
82+
# 合并上游更新
83+
git merge upstream/main
84+
85+
# 推送到你的 Fork
86+
git push origin main
87+
```
88+
89+
### 4. 创建功能分支
90+
91+
**永远不要直接在 main 分支上开发！**
92+
93+
```bash
94+
# 创建并切换到新分支
95+
git checkout -b feature/your-feature-name
96+
97+
# 分支命名规范：
98+
# feature/xxx - 新功能
99+
# fix/xxx - Bug 修复
100+
# docs/xxx - 文档更新
101+
# refactor/xxx - 代码重构
102+
# style/xxx - 代码格式调整
103+
```
104+
105+
### 5. 开发与提交
106+
107+
```bash
108+
# 进行开发...
109+
110+
# 查看更改
111+
git status
112+
git diff
113+
114+
# 暂存更改
115+
git add .
116+
117+
# 提交（遵循 Conventional Commits 规范）
118+
git commit -m "feat: 添加新功能描述"
119+
```
120+
121+
**提交信息规范：**
122+
123+
| 类型 | 说明 |
124+
| ---------- | ------------------------------ |
125+
| `feat` | 新功能 |
126+
| `fix` | Bug 修复 |
127+
| `docs` | 文档更新 |
128+
| `style` | 代码格式（不影响功能） |
129+
| `refactor` | 重构（既不是新功能也不是修复） |
130+
| `perf` | 性能优化 |
131+
| `test` | 测试相关 |
132+
| `chore` | 构建/工具相关 |
133+
134+
示例：
135+
136+
```bash
137+
git commit -m "feat: 添加歌词翻译显示功能"
138+
git commit -m "fix: 修复播放列表滚动位置问题"
139+
git commit -m "docs: 更新原生插件文档"
140+
```
141+
142+
### 6. 推送分支
143+
144+
```bash
145+
# 推送到你的 Fork
146+
git push origin feature/your-feature-name
147+
```
148+
149+
### 7. 创建 Pull Request
150+
151+
1. 访问你的 Fork 仓库页面
152+
2. 点击 **Compare & pull request** 按钮
153+
3. 填写 PR 标题和描述：
154+
- 清晰描述更改内容
155+
- 关联相关 Issue（如有）：`Closes #123`
156+
- 提供测试方法或截图
157+
4. 点击 **Create pull request**
158+
159+
### 8. 代码审查
160+
161+
- 维护者可能会提出修改建议
162+
- 根据反馈进行修改并推送更新
163+
- PR 合并后，可删除功能分支
164+
165+
```bash
166+
# 删除本地分支
167+
git branch -d feature/your-feature-name
168+
169+
# 删除远程分支
170+
git push origin --delete feature/your-feature-name
171+
```
172+
173+
## 代码规范
174+
175+
### 代码风格
176+
177+
项目使用 ESLint 和 Prettier 进行代码规范检查：
178+
179+
```bash
180+
# 检查代码规范
181+
pnpm lint
182+
183+
# 自动格式化
184+
pnpm format
185+
```
186+
187+
提交前请确保代码通过规范检查。
188+
189+
### 目录结构
190+
191+
```
192+
SPlayer/
193+
├── src/ # 前端源码
194+
│ ├── components/ # Vue 组件
195+
│ ├── stores/ # Pinia 状态管理
196+
│ ├── views/ # 页面视图
197+
│ ├── utils/ # 工具函数
198+
│ └── types/ # TypeScript 类型定义
199+
├── electron/ # Electron 主进程
200+
│ ├── main/ # 主进程代码
201+
│ └── preload/ # 预加载脚本
202+
├── native/ # 原生 Rust 插件
203+
│ ├── smtc-for-splayer/ # SMTC 模块
204+
│ └── discord-rpc-for-splayer/ # Discord RPC 模块
205+
├── docs/ # 文档
206+
└── scripts/ # 构建脚本
207+
```
208+
209+
## 常见问题
210+
211+
### Q: 如何解决合并冲突？
212+
213+
```bash
214+
# 获取上游最新代码
215+
git fetch upstream
216+
217+
# 在你的功能分支上 rebase
218+
git rebase upstream/main
219+
220+
# 解决冲突后继续
221+
git add .
222+
git rebase --continue
223+
224+
# 强制推送（注意：仅在你自己的分支上使用）
225+
git push origin feature/your-feature-name --force
226+
```
227+
228+
### Q: 如何撤销最近的提交？
229+
230+
```bash
231+
# 撤销最近一次提交（保留更改）
232+
git reset --soft HEAD~1
233+
234+
# 撤销最近一次提交（丢弃更改）
235+
git reset --hard HEAD~1
236+
```
237+
238+
### Q: 如何修改最近的提交信息？
239+
240+
```bash
241+
git commit --amend -m "新的提交信息"
242+
```
243+
244+
## 获取帮助
245+
246+
如果您在贡献过程中遇到问题：
247+
248+
1. 查阅项目 [Issues](https://github.com/imsyy/SPlayer/issues)
249+
2. 提交新 Issue 描述您的问题
250+
3. 加入项目讨论群组
251+
252+
感谢您的贡献！🎉

0 commit comments

Comments
 (0)