156 lines
4.5 KiB
Markdown
156 lines
4.5 KiB
Markdown
# 🚀 Spotify 集成快速启动指南
|
||
|
||
您的 Spotify Client ID 已配置完成！
|
||
|
||
## ✨ 授权方式升级
|
||
|
||
本应用使用 **Authorization Code Flow with PKCE**（最新、最安全的授权方式）：
|
||
- ✅ 不需要 Client Secret
|
||
- ✅ 更安全的授权流程
|
||
- ✅ Spotify 官方推荐
|
||
- ✅ 防止授权码拦截攻击
|
||
- ✅ [100% 符合官方文档](https://developer.spotify.com/documentation/web-api/tutorials/code-pkce-flow)
|
||
|
||
详细实现说明见：[SPOTIFY_PKCE_IMPLEMENTATION.md](./SPOTIFY_PKCE_IMPLEMENTATION.md)
|
||
|
||
## ⚡ 快速开始（3步）
|
||
|
||
### 第 1 步：配置 Spotify Dashboard ⚙️
|
||
|
||
**必须完成！** 否则授权会失败
|
||
|
||
1. 访问 [Spotify Developer Dashboard](https://developer.spotify.com/dashboard/4ed200672ba1421baa31b9859bd84d39/settings)
|
||
2. 在 **"Redirect URIs"** 中添加以下两个地址：
|
||
|
||
**开发环境：**
|
||
```
|
||
http://localhost:5173/callback
|
||
```
|
||
|
||
**生产环境：**
|
||
```
|
||
https://sports.rucky.cn/callback
|
||
```
|
||
|
||
⚠️ 注意：使用 `/callback` 路径（符合官方文档示例），两个地址都要添加！
|
||
|
||
3. 点击 **"Add"** 添加每个地址
|
||
4. 点击 **"Save"** 保存设置
|
||
|
||
### 第 2 步：启动应用 🚀
|
||
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
### 第 3 步：使用 Spotify 🎵
|
||
|
||
**开发环境：**
|
||
1. 打开浏览器访问：`http://localhost:5173/`
|
||
2. 点击 **"音乐律动·步频检测"**
|
||
3. 点击 **"Spotify"** 标签页
|
||
4. 点击 **"连接 Spotify 账号"** 按钮
|
||
5. 授权后开始使用！
|
||
|
||
**生产环境：**
|
||
1. 打开浏览器访问：`https://sports.rucky.cn/`
|
||
2. 按照相同步骤操作即可
|
||
|
||
## 📋 使用前检查清单
|
||
|
||
请确保以下条件都满足：
|
||
|
||
- [ ] ✅ 你有 **Spotify Premium** 账号（免费账号无法播放）
|
||
- [ ] ✅ 在 Spotify Dashboard 中添加了 `http://localhost:5173/` 作为 Redirect URI
|
||
- [ ] ✅ Spotify 桌面应用或手机 App 已打开并登录
|
||
- [ ] ✅ 应用已启动并运行在 `http://localhost:5173/`
|
||
|
||
## 🎯 三种播放方式
|
||
|
||
### 1️⃣ 根据步频推荐（智能匹配）
|
||
- 选择运动模式（散步、慢跑、跑步等）
|
||
- 点击 **"🎯 匹配步频"** 标签
|
||
- 点击 **"🎵 推荐歌曲"** 按钮
|
||
- 系统会根据你的步频（BPM）推荐最匹配的音乐
|
||
- 点击任意歌曲开始播放
|
||
|
||
**示例：**
|
||
- 散步 80 BPM → 推荐轻松慢歌
|
||
- 跑步 170 BPM → 推荐快节奏电音
|
||
|
||
### 2️⃣ 关键词搜索
|
||
- 点击 **"🔍 关键词搜索"** 标签
|
||
- 输入歌曲名、艺术家或专辑
|
||
- 点击搜索或按回车
|
||
- 点击任意歌曲开始播放
|
||
|
||
**示例搜索：**
|
||
- 歌曲名：`Shape of You`
|
||
- 艺术家：`Taylor Swift`
|
||
- 专辑：`1989`
|
||
|
||
### 3️⃣ 我的歌单
|
||
- 点击 **"📋 我的歌单"** 标签
|
||
- 浏览你的 Spotify 歌单
|
||
- 点击歌单查看歌曲列表
|
||
- 点击任意歌曲开始播放
|
||
|
||
## ❓ 常见问题快速解决
|
||
|
||
### 🚫 授权失败 / Redirect URI mismatch
|
||
|
||
**原因：** Redirect URI 配置不正确
|
||
|
||
**解决：**
|
||
1. 检查 Spotify Dashboard 中的 Redirect URI 是否为 `http://localhost:5173/`（包含最后的斜杠）
|
||
2. 如果使用其他端口，请相应修改
|
||
3. 保存后重新授权
|
||
|
||
### 🚫 播放失败 / No active device found
|
||
|
||
**原因：** 没有活动的播放设备
|
||
|
||
**解决：**
|
||
1. 打开 Spotify 桌面应用或手机 App
|
||
2. 在 Spotify 中随便播放一首歌（激活设备）
|
||
3. 返回 Web 应用重试播放
|
||
|
||
### 🚫 搜索不到歌曲
|
||
|
||
**原因：** Token 过期或网络问题
|
||
|
||
**解决：**
|
||
1. 点击右上角 **"退出"** 按钮
|
||
2. 重新点击 **"连接 Spotify 账号"**
|
||
3. 重新授权
|
||
|
||
### 🚫 提示需要 Premium 账号
|
||
|
||
**原因：** 使用了免费账号
|
||
|
||
**解决：**
|
||
- Spotify Web Playback API 仅支持 Premium 账号
|
||
- 可以注册 Premium 试用或升级账号
|
||
- 免费账号可以搜索和查看，但无法播放
|
||
|
||
## 🎨 功能亮点
|
||
|
||
- 🎯 **智能步频匹配**：根据你的运动步频推荐最合适的音乐
|
||
- 🔍 **强大搜索**：搜索 Spotify 数百万首歌曲
|
||
- 📋 **歌单管理**：访问你的所有 Spotify 歌单
|
||
- 🎵 **实时播放控制**：播放、暂停、上一首、下一首
|
||
- 🖼️ **精美展示**：显示歌曲封面和详细信息
|
||
- 💾 **自动保存**：授权状态自动保存，下次无需重新登录
|
||
|
||
## 🔗 相关链接
|
||
|
||
- [Spotify Developer Dashboard](https://developer.spotify.com/dashboard)
|
||
- [你的应用设置](https://developer.spotify.com/dashboard/4ed200672ba1421baa31b9859bd84d39/settings)
|
||
- [Spotify Web API 文档](https://developer.spotify.com/documentation/web-api)
|
||
- [完整设置指南](./SPOTIFY_SETUP.md)
|
||
|
||
---
|
||
|
||
**现在就开始享受音乐吧！** 🎉
|
||
|