freefire
d032668c66
cmd 按 ANSI 解析 .bat，中文提示改由带 BOM 的 stop.ps1 输出。 Co-authored-by: Cursor <cursoragent@cursor.com>
67 lines
2.8 KiB
Plaintext
67 lines
2.8 KiB
Plaintext
---
|
||
description: 本地开发启动/停止约定：工作目录、单实例、按端口杀进程树，避免孤儿进程与头像 404
|
||
alwaysApply: true
|
||
---
|
||
|
||
# 本地开发环境
|
||
|
||
## 后端启动（必须遵守）
|
||
|
||
规范命令与 `start.bat` / `start.sh` 一致：
|
||
|
||
```
|
||
cd backend
|
||
go run ./cmd/jiang13
|
||
```
|
||
|
||
- 数据目录**只有** `backend/data/`（头像在 `backend/data/uploads/avatars/`）
|
||
- 配置文件是 `backend/app.ini`，不是仓库根、也不是 `cmd/jiang13/`
|
||
- **禁止**在仓库根、`backend/cmd/jiang13/` 或其他目录执行 `go run`（会另建一套 data，DB 里头像 URL 对不上文件）
|
||
- **禁止**同时跑两个后端。启动前若 `:3001` 已在听，沿用现有进程，或先停再启；不要再开一个
|
||
- 启动日志必须含 `workPath=.../backend` 且 `dataDir=.../backend/data`。若不是，立刻停掉重来
|
||
- 覆盖工作目录只用环境变量 `JIANG13_WORK_PATH`（指向 `backend/`）
|
||
|
||
## 前端
|
||
|
||
```
|
||
cd frontend
|
||
npm.cmd run dev
|
||
```
|
||
|
||
`:3000` 把 `/uploads` rewrite 到 `:3001`。头像 404 先查后端 `dataDir`，不要改前端。
|
||
|
||
## 进程生命周期（Windows 孤儿进程）
|
||
|
||
根因：Cursor/agent 停掉的往往是 **shell 父进程**；`go run` / `npm` 拉起的 `go.exe`/`node.exe`/编译产物仍在听端口，任务管理器里才看得见。
|
||
|
||
### Agent 必须遵守
|
||
|
||
1. **先查再启**：启动前用端口探测；`:3000`/`:3001` 已在听 → **复用**，禁止再开一份
|
||
2. **停服务优先跑脚本**（仓库根）：
|
||
- Windows：`stop.bat`（内部调用 `stop.ps1`）
|
||
- Unix：`./stop.sh`
|
||
3. **禁止**只依赖「结束终端 / Ctrl+C / 杀 shell PID」当作已停干净
|
||
4. 无脚本时，Windows 用 **按端口 + 进程树** 清理（PowerShell）：
|
||
```powershell
|
||
foreach ($port in 3000,3001) {
|
||
Get-NetTCPConnection -LocalPort $port -State Listen -EA SilentlyContinue |
|
||
Select-Object -ExpandProperty OwningProcess -Unique |
|
||
ForEach-Object { if ($_ -gt 0) { taskkill /T /F /PID $_ } }
|
||
}
|
||
```
|
||
5. 声称已停止后，**再查一次**端口是否空闲；仍占用则继续 `/T` 杀树，勿让用户去任务管理器
|
||
6. 默认**不动** Docker Postgres；用户要停库再 `docker compose down`
|
||
7. 会话结束前若本会话启动过前后端：主动清理或明确告知用户执行 `stop.bat`
|
||
|
||
### 用户侧
|
||
|
||
双击 / 运行仓库根 `stop.bat`（或 `./stop.sh`）即可，无需开任务管理器。
|
||
|
||
### Windows `.bat` 编码
|
||
|
||
`cmd.exe` 按系统 ANSI（中文 Windows 多为 GBK）解析 `.bat`，**禁止**在 `.bat` 里写 UTF-8 中文（会乱码断行，出现 `'/' 不是内部或外部命令`）。`.bat` 保持 ASCII；中文提示放 `stop.ps1`（UTF-8 BOM）或英文。
|
||
|
||
## 遗留目录
|
||
|
||
`backend/cmd/jiang13/data/` 是错误 cwd 的产物，禁止当数据源。发现后把 `uploads/` 合并进 `backend/data/uploads/`，再删遗留目录。
|