rtc_prd/FLUTTER_WEB_DEV_GUIDE.md

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. 杀掉旧进程并确认端口空闲

# 杀掉占用 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. 启动后端服务器（音乐生成功能依赖此服务）

# 工作目录：项目根目录
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

# 工作目录：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 = 强制刷新

---

停止服务

# 方法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 秒