快速开始
本页说明如何在本地运行项目，依次覆盖环境要求、依赖安装、开发调试、生产构建与代码检查，并列出启动失败的常见原因与处理方式。
环境要求
- Node.js 20.19 或更高版本（也可使用 22.12+；项目使用 Vite 8，Node 18 无法运行）
- npm 10 或更高版本（也可使用 pnpm / yarn）
使用以下命令确认当前环境版本：
bash
node -v
npm -v安装依赖
在项目根目录运行：
bash
npm install启动开发服务器
bash
npm run dev默认在 http://localhost:5173 打开，端口被占用时 Vite 会自动切换到其它端口。
开发服务器已配置监听优化：忽略 public/music/** 等大文件目录的变更，避免音乐文件触发整页热更新。
构建生产版本
bash
npm run build该命令包含两步：
vite build—— 产物输出到dist/node scripts/prerender.js—— 用 Playwright 预渲染/和/contributors两个路由，生成对搜索引擎友好的静态 HTML
提示
首次构建时如果提示「找不到浏览器」，运行以下命令安装 Chromium：
bash
npx playwright install chromium预览生产构建
bash
npm run preview代码检查
bash
npm run lint使用 ESLint 10 检查全部源码，包含 React Hooks 与 React Refresh 规则。
常见问题：启动失败
下表列出启动或构建失败的常见现象及对应处理方式。
| 现象 | 解决 |
|---|---|
npm run build 报预渲染失败 | 运行 npx playwright install chromium 安装浏览器 |
| 端口 5173 被占用 | 无需处理，Vite 会自动换端口；或按提示用 --port 指定 |
| 修改配置后样式没变化 | theme.config.js 由构建插件读取，保存文件后 Vite 会自动重编译，如未生效请重启 dev server |