---
author: claude
created_at: 2026-06-27
purpose: 规范本地服务管理：强制使用 dev-services.py 控制前后端服务，固定前端/H5 端口从 5178 开始累加，优化热加载避免无意义重启
---

# 本地服务管理规则优化设计

## 背景

当前项目使用 `dev-services.py` 管理本地前后端服务，但存在以下问题：

1. 前端/H5 端口分散配置在各自 `vite.config.*` 中，未统一管理
2. `dev-services.py` 端口冲突时自动递增，导致端口号不稳定
3. 用户已习惯使用 `dev-services.py`，但缺少"禁止无意义重启"的强制约束
4. 热加载场景下，开发者可能误重启支持热更新的前端服务，浪费时间

## 目标

1. 强制：启动/重启/停止本地前后端服务必须使用 `dev-services.py`
2. 固定：前端和 H5 服务端口从 5178 开始累加分配
3. 优化：`dev-services.py restart` 在无必须重启的变更时禁止重启
4. 一致：更新 CLAUDE.md 规则文档，与脚本行为对齐

## 方案选择

采用 **方案 A：dev-services.py 内置固定端口表 + 修改各项目 vite 配置**

- 端口控制集中且与项目配置一致
- 与现有 `dev-services.py` 架构兼容
- 便于开发者直接查看配置文件了解端口

## 详细设计

### 1. 固定端口分配表

| 服务 | 目录 | 类型 | 固定端口 |
|---|---|---|---|
| Emotion-museum-web | `web/` | Vite | 5178 |
| Emotion-museum-admin | `web-admin/` | Vite | 5179 |
| Emotion-museum-uniapp | `mini-program/` | UniApp H5 | 5180 |
| Life-script 前端 | `life-script/` | Vite | 5181 |

后端服务端口保持现有配置不变。

### 2. dev-services.py 修改

#### 2.1 新增固定端口映射

```python
FIXED_FRONTEND_PORTS = {
    "web": 5178,
    "web-admin": 5179,
    "mini-program": 5180,
    "life-script": 5181,
}
```

按项目目录名匹配。如果目录名不在映射中，仍按原有逻辑处理。

#### 2.2 修改端口分配逻辑

在 `assign_unique_ports()` 中：
- 对 `FIXED_FRONTEND_PORTS` 中定义的服务，强制使用固定端口
- 如果固定端口被非前端服务占用，报错退出
- 如果固定端口被另一个前端服务占用，报错退出（说明映射配置错误）
- 不再对前端服务自动递增端口

#### 2.3 新增 restart 热加载保护

定义"必须重启才能生效"的文件模式：

```python
RESTART_REQUIRED_PATTERNS = [
    r'vite\.config\.(ts|js|mjs|cjs)$',
    r'tsconfig\.json$',
    r'\.env(\.[^/]*)?$',
    r'package\.json$',
    r'application.*\.ya?ml$',
    r'pom\.xml$',
    r'build\.gradle(\.kts)?$',
]
```

`restart` 命令执行前：
1. 获取 git 工作区中已修改的文件列表：`git diff --name-only`
2. 如果没有修改，提示"未检测到代码变更，无需重启"
3. 如果修改文件匹配 `RESTART_REQUIRED_PATTERNS`，允许正常 restart
4. 如果修改文件不匹配，拒绝 restart 并提示：
   > 当前修改只涉及支持热加载的源码文件，无需重启。如需强制重启，请使用 `python dev-services.py restart --force`

#### 2.4 支持 `--force` 参数

在 `restart` 子命令解析中增加 `--force` 选项，允许用户绕过热加载保护强制重启。

### 3. 前端项目配置修改

| 文件 | 修改内容 |
|---|---|
| `web/vite.config.ts` | `server.port` 改为 5178 |
| `web/.env.development` | 添加 `VITE_PORT=5178` |
| `web-admin/vite.config.ts` | `server.port` 改为 5179 |
| `web-admin/.env.development` | `VITE_APP_PORT` 改为 5179 |
| `mini-program/vite.config.js` | `server.port` 改为 5180 |
| `mini-program/.env.development` | 添加 `VITE_PORT=5180` |
| `life-script/vite.config.js` | `server.port` 改为 5181 |
| `life-script/.env.development` | 添加 `VITE_PORT=5181`（不存在则创建） |

### 4. CLAUDE.md 规则更新

新增"本地服务管理规则"章节：

1. **必须使用 dev-services.py**：
   - 启动、重启、停止本地前后端服务必须使用 `python dev-services.py [命令] [服务名]`
   - 禁止直接使用 `npm run dev`、`npm run dev:h5`、`mvn spring-boot:run` 等命令

2. **前端/H5 固定端口**：
   - `web`: 5178
   - `web-admin`: 5179
   - `mini-program`: 5180
   - `life-script`: 5181

3. **禁止无意义重启**：
   - 只有修改必须重启才能生效的文件时，才允许执行 `restart`
   - 修改源码文件（`.vue`、`.tsx`、`.ts`、`.js`、`.css`、`.scss` 等）时禁止 restart
   - 确需强制重启时，使用 `python dev-services.py restart --force`

4. **热加载规则**：
   - 前端修改源码文件优先利用热加载
   - 后端修改代码按现有规则处理（本地不启动后端，使用服务器验收）

### 5. 边界情况

| 场景 | 行为 |
|---|---|
| 固定端口被占用 | `dev-services.py` 报错，要求先停止占用该端口的服务 |
| 无代码变更执行 restart | 提示无需重启 |
| 只修改 `.vue` 文件执行 restart | 拒绝重启，提示使用 `--force` 或无需重启 |
| 修改 `vite.config.ts` 执行 restart | 允许正常 restart |
| 多个服务同时 restart | 每个服务独立检测，符合规则的重启，不符合的跳过 |
| 用户传 `--force` | 跳过所有检测，强制重启 |

## 修改范围

| 文件 | 操作 |
|---|---|
| `dev-services.py` | 修改：添加固定端口映射、优化端口分配、新增热加载保护 |
| `web/vite.config.ts` | 修改：端口改为 5178 |
| `web/.env.development` | 修改/创建：添加 `VITE_PORT=5178` |
| `web-admin/vite.config.ts` | 修改：端口改为 5179 |
| `web-admin/.env.development` | 修改：`VITE_APP_PORT` 改为 5179 |
| `mini-program/vite.config.js` | 修改：端口改为 5180 |
| `mini-program/.env.development` | 修改/创建：添加 `VITE_PORT=5180` |
| `life-script/vite.config.js` | 修改：端口改为 5181 |
| `life-script/.env.development` | 修改/创建：添加 `VITE_PORT=5181` |
| `CLAUDE.md` | 修改：更新本地服务管理规则 |