newToy/SPOTIFY_SETUP.md

Spotify Web API 集成指南

本应用已集成 Spotify Web API，可以直接播放 Spotify 上的音乐。

🎯 前置要求

1. Spotify Premium 账号（必需）

   • 只有 Premium 账号才能使用 Web Playback API
   • 免费账号只能查看数据，无法控制播放

2. Spotify 开发者账号（免费）

   • 需要注册开发者应用获取 Client ID

📝 设置步骤

第一步：注册 Spotify 开发者应用

1. 访问 Spotify Developer 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
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 官方文档示例）
• ✅ 必须完全匹配，包括协议和路径
• ✅ 必须同时添加开发和生产环境的 URI
• ✅ 授权成功后会自动跳转回音乐律动页面

设置步骤：

1. 访问 你的应用设置
2. 点击 "Edit Settings"
3. 在 "Redirect URIs" 中添加 /callback 路径：
   • http://localhost:5173/callback （开发环境）
   • https://sports.rucky.cn/callback （生产环境）
4. 点击 "Add" 添加每个 URI
5. 点击 "Save" 保存

✅ 符合官方文档！ 使用专门的 /callback 路由处理授权回调，更清晰规范。

🎵 使用说明

基本使用流程

1. 启动应用

   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 文档
• 授权指南
• 播放控制 API
• 搜索 API
• 推荐 API

🎨 功能特性

• ✅ OAuth 2.0 授权流程
• ✅ 根据 BPM 推荐歌曲
• ✅ 关键词搜索
• ✅ 访问用户歌单
• ✅ 播放控制（播放、暂停、上一首、下一首）
• ✅ 显示歌曲信息和封面
• ✅ 自动保存授权状态
• ✅ 优雅的错误处理

🔄 更新日志

• 2025-11-23: 初始版本，集成 Spotify Web API

---

如有问题，请参考 Spotify 开发者社区 获取帮助。