❓ 常见问题

🔧 安装与启动

启动报错 "Node.js 版本不支持"

确保 Node.js 版本 >= 22：

node -v
# 应输出 v22.x.x 或更高版本

推荐使用 nvm 或 nvm-windows 管理 Node.js 版本。

依赖安装失败

尝试清除缓存后重新安装：

pnpm store prune
rm -rf node_modules
pnpm install

开发服务器无法访问

检查端口是否被占用（默认 5089）：

# Windows
netstat -ano | findstr :5089

# macOS/Linux
lsof -i :5089

---

🌐 API 相关

播放器没有音乐/无法播放

1. ✅ 确认已正确配置 .env 文件中的 VITE_APP_BASE_API
2. ✅ 确认 API 服务可正常访问
3. ⚠️ 部分歌曲可能因版权限制无法播放

API 请求失败/跨域问题

1. ✅ 确保 API 服务支持 CORS
2. ⚠️ 如使用 Vercel 部署的 API，注意可能有请求限制
3. 💡 建议自行部署 NeteaseCloudMusicApi

登录失效

1. 🔄 尝试刷新登录状态
2. 🗑️ 清除浏览器 localStorage 后重新登录
3. 🍪 检查 API 服务的 Cookie 设置

---

🎨 功能问题

主题切换无效

清除浏览器缓存或 localStorage：

localStorage.removeItem('global')
location.reload()

背景效果卡顿

1. 🎨 尝试切换到其他背景主题
2. 🖥️ 检查浏览器是否支持 WebGL
3. ⚙️ 降低背景参数（速度、强度等）

歌词不显示/不同步

1. ⚠️ 部分歌曲可能没有歌词数据
2. 🔄 刷新页面重新加载歌词
3. 🌐 检查网络连接

移动端布局异常

1. 📱 确保使用现代浏览器（Chrome、Safari、Firefox）
2. 📐 检查视口设置是否正确
3. 🗑️ 尝试清除浏览器缓存

---

🚀 部署问题

构建失败

1. 📘 检查 TypeScript 类型错误：pnpm run typecheck（如有）
2. 🔍 检查 ESLint 错误：pnpm run lint
3. 📦 确保所有依赖已正确安装

部署后路由 404

使用 hash 路由模式（默认）或配置服务器支持 history 模式：

# .env
VITE_ROUTER_MODE = 'hash'

Nginx history 模式配置：

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

静态资源路径错误

检查 VITE_PUBLIC_PATH 配置：

# 根目录部署
VITE_PUBLIC_PATH = '/'

# 子目录部署
VITE_PUBLIC_PATH = '/your-subdirectory/'

---

💬 其他

如何贡献代码？

1. 🍴 Fork 项目
2. 🌿 创建功能分支：git checkout -b feature/your-feature
3. 💾 提交更改：git commit -m 'Add your feature'
4. 📤 推送分支：git push origin feature/your-feature
5. 🔀 创建 Pull Request

如何反馈问题？

在 GitHub 仓库创建 Issue：GlassMusicPlayer Issues

📄 许可证

本项目采用 PolyForm-Noncommercial-1.0.0 许可证，仅限非商业用途。