135 lines
4.5 KiB
Markdown
135 lines
4.5 KiB
Markdown
# 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 <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 混用
|
||
导致来源不匹配。
|