202 lines
3.9 KiB
Markdown
202 lines
3.9 KiB
Markdown
# 🚀 快速参考指南
|
||
|
||
## 📋 关键配置清单
|
||
|
||
### 1. Spotify Dashboard 配置
|
||
|
||
**Redirect URIs：**
|
||
```
|
||
http://localhost:5173/callback ← 开发环境
|
||
https://sports.rucky.cn/callback ← 生产环境
|
||
```
|
||
|
||
配置地址：https://developer.spotify.com/dashboard/4ed200672ba1421baa31b9859bd84d39/settings
|
||
|
||
### 2. 服务器配置（解决刷新 404）
|
||
|
||
**Nginx：**
|
||
```nginx
|
||
location / {
|
||
try_files $uri $uri/ /index.html;
|
||
}
|
||
```
|
||
|
||
**Apache：**
|
||
```apache
|
||
<Directory /var/www/sports.rucky.cn>
|
||
AllowOverride All # 启用 .htaccess
|
||
</Directory>
|
||
```
|
||
|
||
`.htaccess` 已自动包含在构建中！
|
||
|
||
### 3. 构建命令
|
||
|
||
```bash
|
||
# 开发
|
||
npm run dev
|
||
|
||
# 构建生产版本
|
||
npm run build
|
||
|
||
# 生产文件在 dist/ 目录
|
||
```
|
||
|
||
### 4. 部署文件
|
||
|
||
```
|
||
dist/
|
||
├── index.html ← 入口文件
|
||
├── assets/ ← JS/CSS
|
||
├── .htaccess ← Apache 配置（自动包含）
|
||
└── _redirects ← Vercel/Netlify 配置
|
||
```
|
||
|
||
## 🔍 快速测试
|
||
|
||
### 测试 SPA 路由
|
||
|
||
```bash
|
||
# 1. 构建
|
||
npm run build
|
||
|
||
# 2. 本地测试
|
||
npx serve -s dist
|
||
|
||
# 3. 访问测试
|
||
http://localhost:3000/music-rhythm
|
||
|
||
# 4. 刷新页面 - 应该不会 404 ✅
|
||
```
|
||
|
||
### 测试 Spotify 授权
|
||
|
||
```bash
|
||
# 1. 确认 Redirect URI 配置正确
|
||
# 2. 访问应用
|
||
https://sports.rucky.cn/
|
||
|
||
# 3. 进入音乐律动页面
|
||
# 4. 点击"连接 Spotify 账号"
|
||
# 5. 授权后应自动返回 ✅
|
||
```
|
||
|
||
## ⚡ 常用命令
|
||
|
||
```bash
|
||
# 安装依赖
|
||
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 配置（自动） |
|
||
|
||
## 🎯 故障排除快速检查
|
||
|
||
### ❌ 问题：授权失败
|
||
|
||
```bash
|
||
# 检查项
|
||
☐ Redirect URI 是否为 /callback
|
||
☐ 是否包含 http://localhost:5173/callback
|
||
☐ 是否包含 https://sports.rucky.cn/callback
|
||
☐ 是否点击了 "Save" 按钮
|
||
```
|
||
|
||
### ❌ 问题：刷新 404
|
||
|
||
```bash
|
||
# 检查项
|
||
☐ Nginx 是否配置了 try_files
|
||
☐ Apache 是否启用了 AllowOverride
|
||
☐ .htaccess 是否在网站根目录
|
||
☐ 服务器是否重启
|
||
```
|
||
|
||
### ❌ 问题：播放失败
|
||
|
||
```bash
|
||
# 检查项
|
||
☐ 是否有 Spotify Premium 账号
|
||
☐ Spotify 应用是否打开
|
||
☐ 是否有活动的播放设备
|
||
☐ 授权令牌是否过期（1小时）
|
||
```
|
||
|
||
## 🔐 配置信息
|
||
|
||
**Client ID：** `4ed200672ba1421baa31b9859bd84d39`
|
||
|
||
**域名：**
|
||
- 开发：`http://localhost:5173`
|
||
- 生产：`https://sports.rucky.cn`
|
||
|
||
**授权方式：** Authorization Code Flow with PKCE
|
||
- ✅ [完全符合官方文档](https://developer.spotify.com/documentation/web-api/tutorials/code-pkce-flow)
|
||
- ✅ 不需要 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`
|
||
|