244 lines
7.6 KiB
Markdown
244 lines
7.6 KiB
Markdown
# 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) 获取帮助。
|
||
|