chore: deploy 触发分支改 master,竞品调研/原型/色板/i18n/分享组件/文档等成果入库

This commit is contained in:
Sisyphus committed 2026-08-14 09:58:52 +08:00
1 parent 5a97e6124e
commit 40e2342a02
75 files changed
+6848 -540

No files matched your search

+128
View File
@@ -0,0 +1,128 @@
# 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 后端」和「PERLER LAB 前端」),日志输出在各自窗口中,点击
任务栏对应标题即可查看。
## 三、端口一览
| 服务 | 端口 | 访问地址 |
| ---- | ---- | -------- |
| 前端(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. 端口被占用
现象:启动脚本提示「端口 8788 已被占用」或「端口 5173 已被占用」,
或浏览器访问时报错。
解决办法:
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. 提示「未检测到 Node.js」
- 确认 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 混用
导致来源不匹配。