Files

135 lines
4.5 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 混用
导致来源不匹配。