开发指南
快速启动
# 安装依赖
pnpm install
# 启动前后端开发服务器（默认同时开放到局域网）
pnpm dev
# 其他设备通过 http://你的局域网IP:5173 访问前端
# 前端会自动连接到 http://你的局域网IP:3001 后端
# 仅启动前端
pnpm dev:client
# 仅启动后端
pnpm dev:server
端口
| 服务 | 默认端口 |
|---|---|
| 前端 (Vite) | 5173 |
| 后端 (Express + Socket.IO) | 3001 |
环境变量
服务端 (packages/server/.env)
| 变量 | 说明 | 默认值 |
|---|---|---|
PORT |
服务端口 | 3001 |
CLIENT_URL |
客户端地址（CORS） | http://localhost:5173 |
CORS_ORIGINS |
额外 CORS 源（逗号分隔） | 空 |
客户端 (Vite 环境变量)
| 变量 | 说明 | 默认值 |
|---|---|---|
VITE_SERVER_URL |
后端地址 | http://localhost:3001 |
构建
# 构建所有包
pnpm build
# 前端产物 → packages/client/dist/
# 后端产物 → packages/server/dist/
# shared 包无构建步骤，直接作为 TS 源码引用
添加 shadcn/ui 组件
cd packages/client
npx shadcn@latest add <component-name>
组件会安装到 src/components/ui/。
注意事项
- 服务端数据全部存储在内存中，重启后丢失
- 无数据库、无服务端持久化（客户端 Cookie 通过 localStorage 持久化）
- 用户身份基于持久化 nanoid（localStorage）+ 昵称（无注册/登录账号系统）；
socket.id仅用于 Socket 传输层映射 - 平台认证（网易云/酷狗 QR 扫码登录、QQ 手动 Cookie）用于 VIP 歌曲访问，Cookie 作用域为房间级。QR 登录状态码在
shared/constants.ts中定义为QR_STATUS（800-803），前后端共用，QrLoginDialog无需区分平台 - Auth Cookie 持久化策略：只有用户主动登出（
useAuth.logout()）才删除 localStorage 中的 cookie。useAuthSync在收到AUTH_SET_COOKIE_RESULT失败时（无论reason是expired还是error）仅通过 toast 反馈，永远不删除 cookie，确保下次进房间时自动重试。LoginSection在 localStorage 有 cookie 但服务端未确认时显示 "验证登录中…" 乐观状态 - Auth Cookie 自动重发：
useRoomState在收到ROOM_STATE时自动重发 localStorage 中的 cookie。另外，当从 HomePage 导航到 RoomPage 时（ROOM_STATE已被 HomePage 提前消费），useRoomState挂载时检测到 room 已存在会立即补发 cookie，确保任何入口都能恢复认证 - Auth Cookie 服务端验证双路径：
authController收到AUTH_SET_COOKIE时先检查hasCookie()——如果 cookie 已在内存池中（刷新页面场景），走 fast path 跳过 API 调用直接返回成功；否则走 slow path 调用getUserInfo()→ncmApi.login_status()。slow path 对任何失败原因（expired或error）都自动重试 1 次（间隔 1.5 秒），因为网易云login_statusAPI 可能对有效 cookie 临时返回空 profile shared包修改后前后端会自动热重载（pnpm workspace 链接）