Files

4.5 KiB
Raw Permalink Blame History

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"

脚本会自动完成以下操作:

  1. 检查 Node.js / npm 是否可用;
  2. 检查端口 8788 / 5173 是否被占用(仅警告,不中断);
  3. 以最小化窗口启动后端(perler-lab-server,端口 8788);
  4. 等待 3 秒后,以最小化窗口启动前端(perler-lab,Vite 端口 5173);
  5. 打印访问地址与健康检查命令。

启动成功后,两个服务分别运行在独立的 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!,或浏览器访问时报错。

解决办法:

  1. 先运行 stop-dev.bat 停止旧的开发进程;
  2. 若仍然占用,手动查找占用进程:
    netstat -ano | findstr ":8788"
    
    netstat -ano | findstr ":5173",记下最后一列 PID,然后:
    taskkill /F /PID <PID>
    
  3. 重新运行 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 混用 导致来源不匹配。