4.5 KiB
PERLER LAB 本地开发环境搭建指南
本文档介绍如何在本地一键启动 PERLER LAB 的完整开发环境(前端 + 后端)。
一、环境要求(前置条件)
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| Node.js | 20+ | 请从 nodejs.org 下载安装,安装时勾选 "Add to PATH" |
| npm | 随 Node.js 自带 | 无需单独安装 |
注意:Node.js 22 / 24 等更新版本同样兼容。
首次使用前需安装依赖
后端(在 D:\拼豆\perler-lab-server 目录下):
npm install
前端(在 D:\拼豆\perler-lab 目录下):
npm install
两个项目是独立目录,需要分别安装依赖。如果重新拉取代码后启动失败,请先重新执行以上两步。
二、一键启动
直接双击 D:\拼豆\start-dev.bat,或在命令行中执行:
cmd /c "D:\拼豆\start-dev.bat"
脚本会自动完成以下操作:
- 检查 Node.js / npm 是否可用;
- 检查端口 8788 / 5173 是否被占用(仅警告,不中断);
- 以最小化窗口启动后端(
perler-lab-server,端口 8788); - 等待 3 秒后,以最小化窗口启动前端(
perler-lab,Vite 端口 5173); - 打印访问地址与健康检查命令。
启动成功后,两个服务分别运行在独立的 cmd 窗口中(标题分别为
PERLER LAB Backend 和 PERLER LAB Frontend),日志输出在各自窗口中,
点击任务栏对应标题即可查看。
编码兼容说明(BUG-087):
start-dev.bat/stop-dev.bat为纯 ASCII 编码 + CRLF 换行,并改用%~dp0解析项目目录,因此在任意代码页 (包括中文 GBK / cp936)的 Windows 下均可直接双击或命令行运行, 无需依赖chcp或 UTF-8 BOM。脚本内提示信息为英文,本中文文档 为唯一使用说明。
三、端口一览
| 服务 | 端口 | 访问地址 |
|---|---|---|
| 前端(Vite + React) | 5173 | http://localhost:5173 |
| 后端(Express API) | 8788 | http://localhost:8788 |
四、验证是否启动成功
1. 后端健康检查
在浏览器或命令行中访问(返回 {"status":"ok",...} 即正常):
curl http://localhost:8788/health
2. 前端页面
在浏览器打开 http://localhost:5173 ,看到 PERLER LAB 页面即正常。
五、停止开发环境
直接双击 D:\拼豆\stop-dev.bat,脚本会查找并终止监听 5173 / 8788 端口的进程。
实现方式说明:使用系统内置的 netstat 查找端口对应进程 PID,再通过
taskkill 终止。不使用 wmic,因为 wmic 已被微软弃用(Windows 11 24H2
起已移除),而 netstat / taskkill 无需额外依赖、对普通用户进程无需管理员权限。
六、常见问题排查
1. 端口被占用
现象:启动脚本提示 [WARNING] Port 8788 is already in use! 或
[WARNING] Port 5173 is already in use!,或浏览器访问时报错。
解决办法:
- 先运行
stop-dev.bat停止旧的开发进程; - 若仍然占用,手动查找占用进程:
netstat -ano | findstr ":8788"netstat -ano | findstr ":5173",记下最后一列 PID,然后:taskkill /F /PID <PID> - 重新运行
start-dev.bat。
2. 提示 [ERROR] Node.js not found
- 确认 Node.js 已安装:命令行执行
node --version; - 若已安装但仍报错,说明 Node.js 未加入 PATH。重新运行安装程序勾选
"Add to PATH",或手动将
C:\Program Files\nodejs加入系统环境变量 Path, 然后重新打开命令行窗口再试。
3. 启动后依赖缺失 / 模块找不到
现象:后端或前端窗口报错 Cannot find module 'xxx' 或 npm ERR!。
解决办法:分别在两个项目目录下重新安装依赖:
cd /d D:\拼豆\perler-lab-server && npm install
cd /d D:\拼豆\perler-lab && npm install
4. 后端窗口一闪而过 / 立即退出
- 若提示
tsx找不到:先执行cd /d D:\拼豆\perler-lab-server && npm install; - 若提示端口冲突:参照第 1 条处理;
- 若提示 SQLite 相关错误:确认
perler-lab-server/data目录可写。
5. 前端能打开但接口请求失败(CORS / 网络错误)
- 确认后端窗口显示
PERLER LAB server running on http://localhost:8788; - 确认浏览器访问的是 http://localhost:5173(前端开发服务器已对
localhost:5173来源开启 CORS 白名单),不要用 127.0.0.1 与 localhost 混用 导致来源不匹配。