# Flutter Web 本地调试启动指南

> 本文档供 AI 编码助手阅读，用于在本项目中正确启动 Flutter Web 调试环境。

## 项目结构

- Flutter 应用目录：`airhub_app/`
- 后端服务入口：`server.py`（根目录，FastAPI + Uvicorn，端口 3000）
- 前端端口：`8080`

## 环境要求

- Flutter SDK（3.x）
- Python 3.x（后端服务）
- PowerShell（Windows 环境）

## 操作系统

Windows（所有命令均为 PowerShell 语法）

---

## 启动流程（严格按顺序执行）

### 1. 杀掉旧进程并确认端口空闲

```powershell
# 杀掉占用 8080 和 3000 的旧进程
Get-NetTCPConnection -LocalPort 8080 -ErrorAction SilentlyContinue | ForEach-Object { taskkill /F /PID $_.OwningProcess 2>$null }
Get-NetTCPConnection -LocalPort 3000 -ErrorAction SilentlyContinue | ForEach-Object { taskkill /F /PID $_.OwningProcess 2>$null }

# 等待端口释放
Start-Sleep -Seconds 3

# 确认端口已空闲（无输出 = 空闲）
Get-NetTCPConnection -LocalPort 8080 -ErrorAction SilentlyContinue
Get-NetTCPConnection -LocalPort 3000 -ErrorAction SilentlyContinue
```

### 2. 启动后端服务器（音乐生成功能依赖此服务）

```powershell
# 工作目录：项目根目录
cd d:\Airhub
python server.py
```

成功标志：
```
INFO:     Uvicorn running on http://0.0.0.0:3000 (Press CTRL+C to quit)
[Server] Music Server running on http://localhost:3000
```

### 3. 设置国内镜像源 + 启动 Flutter Web Server

```powershell
# 工作目录：airhub_app 子目录
cd d:\Airhub\airhub_app

# 设置镜像源（必须，否则网络超时）
$env:PUB_HOSTED_URL = "https://pub.flutter-io.cn"
$env:FLUTTER_STORAGE_BASE_URL = "https://storage.flutter-io.cn"

# 启动 web-server 模式
flutter run -d web-server --web-port=8080 --no-pub
```

成功标志：
```
lib\main.dart is being served at http://localhost:8080
```

### 4. 访问应用

浏览器打开：`http://localhost:8080`

---

## 关键规则

### 必须使用 `web-server` 模式
- **禁止**使用 `flutter run -d chrome`（会弹出系统 Chrome 窗口，不可控）
- **必须**使用 `flutter run -d web-server`（只启动 HTTP 服务，手动用浏览器访问）

### `--no-pub` 的使用条件
- 仅修改 Dart 代码（无新依赖、无新 asset）→ 加 `--no-pub`，编译更快
- 新增了 `pubspec.yaml` 依赖或 `assets/` 资源文件 → **不能**加 `--no-pub`

### 端口管理
- 固定使用 8080（Flutter）和 3000（后端），不要换端口绕过占用
- 每次启动前必须先确认端口空闲
- 停止服务后等 3 秒再重新启动

### 热重载
- 在 Flutter 终端按 `r` = 热重载（保留页面状态）
- 按 `R` = 热重启（重置页面状态）
- 浏览器 `Ctrl+Shift+R` = 强制刷新

---

## 停止服务

```powershell
# 方法1：在 Flutter 终端按 q 退出

# 方法2：强制杀进程
Get-NetTCPConnection -LocalPort 8080 | ForEach-Object { taskkill /F /PID $_.OwningProcess }
Get-NetTCPConnection -LocalPort 3000 | ForEach-Object { taskkill /F /PID $_.OwningProcess }
```

---

## 常见问题排查

| 问题 | 原因 | 解决方案 |
|------|------|---------|
| 端口被占用 | 旧进程未退出 | 执行第1步杀进程，等3秒 |
| 编译报错找不到包 | 使用了 `--no-pub` 但有新依赖 | 去掉 `--no-pub` 重新编译 |
| 网络超时 | 未设置镜像源 | 设置 `PUB_HOSTED_URL` 和 `FLUTTER_STORAGE_BASE_URL` |
| 页面白屏 | 缓存问题 | 浏览器 `Ctrl+Shift+R` 强刷 |
| 音乐功能不工作 | 后端未启动 | 先启动 `python server.py` |

---

## 编译耗时参考

- 首次完整编译（含 pub get）：90-120 秒
- 增量编译（`--no-pub`）：60-90 秒
- 热重载（按 r）：3-5 秒
- 热重启（按 R）：10-20 秒