newToy/QUICK_REFERENCE.md

🚀 快速参考指南

📋 关键配置清单

1. Spotify Dashboard 配置

Redirect URIs：

http://localhost:5173/callback    ← 开发环境
https://sports.rucky.cn/callback  ← 生产环境

配置地址：https://developer.spotify.com/dashboard/4ed200672ba1421baa31b9859bd84d39/settings

2. 服务器配置（解决刷新 404）

Nginx：

location / {
    try_files $uri $uri/ /index.html;
}

Apache：

<Directory /var/www/sports.rucky.cn>
    AllowOverride All  # 启用 .htaccess
</Directory>

.htaccess 已自动包含在构建中！

3. 构建命令

# 开发
npm run dev

# 构建生产版本
npm run build

# 生产文件在 dist/ 目录

4. 部署文件

dist/
  ├── index.html        ← 入口文件
  ├── assets/           ← JS/CSS
  ├── .htaccess         ← Apache 配置（自动包含）
  └── _redirects        ← Vercel/Netlify 配置

🔍 快速测试

测试 SPA 路由

# 1. 构建
npm run build

# 2. 本地测试
npx serve -s dist

# 3. 访问测试
http://localhost:3000/music-rhythm

# 4. 刷新页面 - 应该不会 404 ✅

测试 Spotify 授权

# 1. 确认 Redirect URI 配置正确
# 2. 访问应用
https://sports.rucky.cn/

# 3. 进入音乐律动页面
# 4. 点击"连接 Spotify 账号"
# 5. 授权后应自动返回 ✅

⚡ 常用命令

# 安装依赖
npm install

# 开发服务器
npm run dev

# 构建生产版本
npm run build

# 预览构建结果
npx serve -s dist

# 检查 TypeScript
npx tsc --noEmit

# 部署（示例）
rsync -avz --delete dist/ user@sports.rucky.cn:/var/www/sports.rucky.cn/

# 重启 Nginx
sudo systemctl restart nginx

# 重启 Apache
sudo systemctl restart apache2

# 查看 Nginx 日志
sudo tail -f /var/log/nginx/error.log

# 查看 Apache 日志
sudo tail -f /var/log/apache2/error.log

📄 文档索引

文档	用途
QUICK_START.md	3 步快速开始
SPOTIFY_SETUP.md	Spotify 详细配置
SPOTIFY_PKCE_IMPLEMENTATION.md	PKCE 官方实现说明 ⭐
SPOTIFY_CALLBACK_SOLUTION.md	授权流程说明
FIX_404_PROBLEM.md	解决刷新 404 问题
PRODUCTION_DEPLOYMENT.md	生产环境部署
nginx.conf.example	Nginx 配置示例
public/.htaccess	Apache 配置（自动）

🎯 故障排除快速检查

❌ 问题：授权失败

# 检查项
☐ Redirect URI 是否为 /callback
☐ 是否包含 http://localhost:5173/callback
☐ 是否包含 https://sports.rucky.cn/callback
☐ 是否点击了 "Save" 按钮

❌ 问题：刷新 404

# 检查项
☐ Nginx 是否配置了 try_files
☐ Apache 是否启用了 AllowOverride
☐ .htaccess 是否在网站根目录
☐ 服务器是否重启

❌ 问题：播放失败

# 检查项
☐ 是否有 Spotify Premium 账号
☐ Spotify 应用是否打开
☐ 是否有活动的播放设备
☐ 授权令牌是否过期（1小时）

🔐 配置信息

Client ID： 4ed200672ba1421baa31b9859bd84d39

域名：

• 开发：http://localhost:5173
• 生产：https://sports.rucky.cn

授权方式： Authorization Code Flow with PKCE

• ✅ 完全符合官方文档
• ✅ 不需要 Client Secret
• ✅ 防止 CSRF 攻击（state 参数）
• ✅ 防止授权码拦截

所需权限：

• user-read-playback-state
• user-modify-playback-state
• user-read-currently-playing
• streaming
• user-read-email
• user-read-private
• playlist-read-private
• playlist-read-collaborative
• user-library-read

📞 获取帮助

遇到问题？

1. 查看对应的详细文档
2. 检查浏览器控制台错误
3. 查看服务器日志
4. 参考 Spotify 开发者社区

---

快速开始： QUICK_START.md
完整部署： PRODUCTION_DEPLOYMENT.md
解决 404： FIX_404_PROBLEM.md