131 lines
3.8 KiB
Markdown
131 lines
3.8 KiB
Markdown
# 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 秒
|