# PERLER LAB 本地开发环境搭建指南 本文档介绍如何在本地一键启动 PERLER LAB 的完整开发环境(前端 + 后端)。 ## 一、环境要求(前置条件) | 依赖 | 最低版本 | 说明 | | ---- | -------- | ---- | | Node.js | 20+ | 请从 [nodejs.org](https://nodejs.org/) 下载安装,安装时勾选 "Add to PATH" | | npm | 随 Node.js 自带 | 无需单独安装 | > 注意:Node.js 22 / 24 等更新版本同样兼容。 ### 首次使用前需安装依赖 **后端**(在 `D:\拼豆\perler-lab-server` 目录下): ```bash npm install ``` **前端**(在 `D:\拼豆\perler-lab` 目录下): ```bash npm install ``` > 两个项目是独立目录,需要分别安装依赖。如果重新拉取代码后启动失败,请先重新执行以上两步。 ## 二、一键启动 直接**双击** `D:\拼豆\start-dev.bat`,或在命令行中执行: ```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",...}` 即正常): ```bat 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. 若仍然占用,手动查找占用进程: ```bat netstat -ano | findstr ":8788" ``` `netstat -ano | findstr ":5173"`,记下最后一列 PID,然后: ```bat taskkill /F /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!`。 解决办法:分别在两个项目目录下重新安装依赖: ```bash 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 混用 导致来源不匹配。