添加了一个修改
This commit is contained in:
rucky
243
SPOTIFY_SETUP.md
Normal file
243
SPOTIFY_SETUP.md
Normal file
@@ -0,0 +1,243 @@
|
||||
# Spotify Web API 集成指南
|
||||
|
||||
本应用已集成 [Spotify Web API](https://developer.spotify.com/documentation/web-api)，可以直接播放 Spotify 上的音乐。
|
||||
|
||||
## 🎯 前置要求
|
||||
|
||||
1. **Spotify Premium 账号**（必需）
|
||||
- 只有 Premium 账号才能使用 Web Playback API
|
||||
- 免费账号只能查看数据，无法控制播放
|
||||
|
||||
2. **Spotify 开发者账号**（免费）
|
||||
- 需要注册开发者应用获取 Client ID
|
||||
|
||||
## 📝 设置步骤
|
||||
|
||||
### 第一步：注册 Spotify 开发者应用
|
||||
|
||||
1. 访问 [Spotify Developer Dashboard](https://developer.spotify.com/dashboard)
|
||||
2. 使用你的 Spotify 账号登录
|
||||
3. 点击 **"Create app"** 按钮
|
||||
4. 填写应用信息：
|
||||
- **App name**: `Music Rhythm App`（可自定义）
|
||||
- **App description**: `A music app with BPM detection`（可自定义）
|
||||
- **Website**: `http://localhost:5173`（开发环境）
|
||||
- **Redirect URI**:
|
||||
- `http://localhost:5173/`（开发环境，重要！必须精确匹配）
|
||||
- `https://sports.rucky.cn/`（生产环境）
|
||||
- **Which APIs are you planning to use?**: 选择 `Web API`
|
||||
5. 勾选同意服务条款
|
||||
6. 点击 **"Save"** 保存
|
||||
|
||||
⚠️ **注意：** 本应用使用 **Authorization Code Flow with PKCE**，这是 Spotify 推荐的安全授权方式，不需要 Client Secret。
|
||||
|
||||
### 第二步：获取 Client ID
|
||||
|
||||
1. 在应用详情页面，找到 **"Client ID"**
|
||||
2. 复制 **Client ID**
|
||||
3. **不需要** Client Secret（PKCE 流程不需要密钥，更安全）
|
||||
|
||||
### 第三步：配置应用
|
||||
|
||||
✅ **Client ID 已配置完成！**
|
||||
|
||||
当前使用的 Client ID: `4ed200672ba1421baa31b9859bd84d39`
|
||||
|
||||
**重要：请确保在 Spotify Dashboard 中配置了正确的 Redirect URI**
|
||||
|
||||
在你的 Spotify 应用设置中，必须添加以下 Redirect URI：
|
||||
|
||||
**开发环境：**
|
||||
```
|
||||
http://localhost:5173/
|
||||
```
|
||||
|
||||
**如果使用其他端口，请相应修改，例如：**
|
||||
```
|
||||
http://localhost:5174/
|
||||
http://localhost:3000/
|
||||
```
|
||||
|
||||
如何设置：
|
||||
1. 访问 [Spotify Developer Dashboard](https://developer.spotify.com/dashboard)
|
||||
2. 找到你的应用
|
||||
3. 点击 **"Edit Settings"**
|
||||
4. 在 **"Redirect URIs"** 输入框中添加 `http://localhost:5173/`
|
||||
5. 点击 **"Add"** 按钮
|
||||
6. 点击 **"Save"** 保存设置
|
||||
|
||||
### 第四步：配置生产环境的 Redirect URI（必需）
|
||||
|
||||
**你的生产环境 URI：** `https://sports.rucky.cn`
|
||||
|
||||
请在 Spotify Dashboard 中添加以下 Redirect URIs：
|
||||
|
||||
**开发环境：**
|
||||
```
|
||||
http://localhost:5173/callback
|
||||
```
|
||||
|
||||
**生产环境：**
|
||||
```
|
||||
https://sports.rucky.cn/callback
|
||||
```
|
||||
|
||||
⚠️ **重要说明：**
|
||||
- ✅ 使用 `/callback` 路径（符合 [Spotify 官方文档示例](https://developer.spotify.com/documentation/web-api/tutorials/code-flow)）
|
||||
- ✅ 必须完全匹配，包括协议和路径
|
||||
- ✅ 必须同时添加开发和生产环境的 URI
|
||||
- ✅ 授权成功后会自动跳转回音乐律动页面
|
||||
|
||||
设置步骤：
|
||||
1. 访问 [你的应用设置](https://developer.spotify.com/dashboard/4ed200672ba1421baa31b9859bd84d39/settings)
|
||||
2. 点击 **"Edit Settings"**
|
||||
3. 在 **"Redirect URIs"** 中添加 `/callback` 路径：
|
||||
- `http://localhost:5173/callback` （开发环境）
|
||||
- `https://sports.rucky.cn/callback` （生产环境）
|
||||
4. 点击 **"Add"** 添加每个 URI
|
||||
5. 点击 **"Save"** 保存
|
||||
|
||||
✅ **符合官方文档！** 使用专门的 `/callback` 路由处理授权回调，更清晰规范。
|
||||
|
||||
## 🎵 使用说明
|
||||
|
||||
### 基本使用流程
|
||||
|
||||
1. **启动应用**
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
2. **进入音乐律动页面**
|
||||
- 在首页点击 "🎵 音乐律动·步频检测" 卡片
|
||||
|
||||
3. **连接 Spotify**
|
||||
- 点击 "Spotify" 标签页
|
||||
- 点击 "连接 Spotify 账号" 按钮
|
||||
- 在弹出的页面中授权应用访问你的 Spotify 账号
|
||||
- 授权成功后会自动返回应用
|
||||
|
||||
4. **播放音乐**
|
||||
|
||||
**方式一：根据步频推荐**
|
||||
- 选择运动模式（散步、慢跑等）
|
||||
- 点击 "🎯 匹配步频" 标签
|
||||
- 点击 "🎵 推荐歌曲" 按钮
|
||||
- 系统会根据当前步频（BPM）推荐匹配的歌曲
|
||||
- 点击任意歌曲开始播放
|
||||
|
||||
**方式二：关键词搜索**
|
||||
- 点击 "🔍 关键词搜索" 标签
|
||||
- 输入歌曲名、艺术家或专辑名
|
||||
- 按回车或点击 "搜索" 按钮
|
||||
- 点击任意歌曲开始播放
|
||||
|
||||
**方式三：我的歌单**
|
||||
- 点击 "📋 我的歌单" 标签
|
||||
- 选择你的 Spotify 歌单
|
||||
- 从歌单中选择歌曲播放
|
||||
|
||||
5. **播放控制**
|
||||
- 支持播放/暂停、上一首、下一首
|
||||
- 显示当前播放的歌曲信息和封面
|
||||
|
||||
## ⚠️ 常见问题
|
||||
|
||||
### Q1: 提示"播放失败"怎么办？
|
||||
|
||||
确保满足以下条件：
|
||||
1. ✅ 你有 Spotify Premium 账号
|
||||
2. ✅ Spotify 桌面应用或手机应用已打开并登录
|
||||
3. ✅ 至少有一个活动的播放设备
|
||||
4. ✅ 授权令牌未过期（令牌有效期 1 小时）
|
||||
|
||||
### Q2: 找不到可用设备？
|
||||
|
||||
解决方法：
|
||||
1. 打开 Spotify 桌面应用或手机应用
|
||||
2. 在 Spotify 应用中随便播放一首歌（这会激活设备）
|
||||
3. 返回 Web 应用重试
|
||||
|
||||
### Q3: 搜索不到歌曲？
|
||||
|
||||
可能的原因：
|
||||
1. 授权令牌过期 - 点击 "退出" 后重新连接
|
||||
2. 网络问题 - 检查网络连接
|
||||
3. Spotify API 限制 - 等待几分钟后重试
|
||||
|
||||
### Q4: 授权后返回应用但显示未授权？
|
||||
|
||||
解决方法：
|
||||
1. 检查 Redirect URI 是否完全匹配
|
||||
2. 清除浏览器缓存和 localStorage
|
||||
3. 重新授权
|
||||
|
||||
## 🔒 关于 PKCE 授权流程
|
||||
|
||||
本应用使用 **Authorization Code Flow with PKCE (Proof Key for Code Exchange)**，这是 Spotify 推荐的最安全的授权方式。
|
||||
|
||||
### PKCE 的优势
|
||||
|
||||
1. **更安全**：不需要 Client Secret，避免密钥泄露风险
|
||||
2. **适合单页应用**：专为前端应用设计
|
||||
3. **防止授权码拦截**：使用动态生成的 code_verifier 和 code_challenge
|
||||
4. **Spotify 推荐**：官方推荐方式，Implicit Grant Flow 已被弃用
|
||||
|
||||
### 授权流程
|
||||
|
||||
1. 生成随机的 `code_verifier`（64位随机字符串）
|
||||
2. 使用 SHA-256 哈希生成 `code_challenge`
|
||||
3. 用户授权后获得 `authorization_code`
|
||||
4. 使用 `code_verifier` 交换 `access_token`
|
||||
|
||||
### 与旧版本的区别
|
||||
|
||||
- ❌ 旧版：使用 `response_type=token`（Implicit Grant，已弃用）
|
||||
- ✅ 新版：使用 `response_type=code` + PKCE（Authorization Code Flow）
|
||||
|
||||
## 🔒 安全注意事项
|
||||
|
||||
1. **Client ID 是公开的**
|
||||
- Client ID 可以公开，不需要隐藏
|
||||
- 不需要 Client Secret（PKCE 流程不使用）
|
||||
|
||||
2. **访问令牌**
|
||||
- 访问令牌存储在 localStorage 中
|
||||
- 令牌有效期为 1 小时
|
||||
- 不要与他人分享你的访问令牌
|
||||
|
||||
3. **Code Verifier**
|
||||
- 动态生成，每次授权都不同
|
||||
- 临时存储在 localStorage，使用后立即删除
|
||||
|
||||
4. **生产环境**
|
||||
- 必须使用 HTTPS
|
||||
- 限制 Redirect URI 到你的域名
|
||||
|
||||
## 📚 API 文档参考
|
||||
|
||||
- [Spotify Web API 文档](https://developer.spotify.com/documentation/web-api)
|
||||
- [授权指南](https://developer.spotify.com/documentation/web-api/tutorials/getting-started)
|
||||
- [播放控制 API](https://developer.spotify.com/documentation/web-api/reference/start-a-users-playback)
|
||||
- [搜索 API](https://developer.spotify.com/documentation/web-api/reference/search)
|
||||
- [推荐 API](https://developer.spotify.com/documentation/web-api/reference/get-recommendations)
|
||||
|
||||
## 🎨 功能特性
|
||||
|
||||
- ✅ OAuth 2.0 授权流程
|
||||
- ✅ 根据 BPM 推荐歌曲
|
||||
- ✅ 关键词搜索
|
||||
- ✅ 访问用户歌单
|
||||
- ✅ 播放控制（播放、暂停、上一首、下一首）
|
||||
- ✅ 显示歌曲信息和封面
|
||||
- ✅ 自动保存授权状态
|
||||
- ✅ 优雅的错误处理
|
||||
|
||||
## 🔄 更新日志
|
||||
|
||||
- 2025-11-23: 初始版本，集成 Spotify Web API
|
||||
|
||||
---
|
||||
|
||||
如有问题，请参考 [Spotify 开发者社区](https://community.spotify.com/t5/Spotify-for-Developers/bd-p/Spotify_Developer) 获取帮助。
|
||||
|
||||
Reference in New Issue
Block a user