Flutter iOS 真机无线调试完整指南（含常见问题排查）

一、无线调试的基本原理

Flutter 在 iOS 上的无线调试依赖 Xcode 提供的网络调试能力。

整体流程：

1. iPhone 安装并启动 App
2. App 启动 Dart VM Service（调试服务）
3. Mac电脑通过局域网连接 iPhone上的VM Service
4. VS Code / Flutter attach 调试

---

二、环境要求（必须满足）

1. 基础条件

• Mac 安装 Xcode
• Flutter SDK 正常配置
• iPhone 与 Mac 在同一网络（Wi-Fi / 热点）

2. iPhone 设置

• 必须开启 Developer Mode（iOS 16+）
• 首次必须通过数据线连接一次
• 调式的Flutter App必须允许"本地网络“ 权限

可以在这里设置并查看你的应用是否允许：

设置→ 隐私与安全性 → 本地网络

查看你的应用的开关是否开启

---

三、标准无线调试步骤

Step 1：首次 USB 连接

使用数据线连接 iPhone：

• 打开 Xcode → Devices and Simulators

---

Step 2：断开数据线

确认设备仍显示在Connected栏，并且设备后面显示一个网路球状标识。

---

Step 3：Flutter 检测设备

应该能看到你连接的iPhone

---

Step 4：运行调试

---

四、VS Code 调试方式

方式一：直接运行

VS Code 自动 attach

---

方式二：手动 attach（推荐排查用）

---

五、典型问题与解决方案

---

问题 1：flutter devices 能看到，但 VS Code 没设备

原因：

IDE 没同步 Flutter daemon

解决：

• VS Code 执行：

或重启 VS Code

---

问题 2：The Dart VM Service was not discovered after 75 seconds

本质：

Mac 无法连接 iPhone 的 Dart VM Service

常见原因：

1. 网络隔离

• 公司 Wi-Fi
• 路由器 AP Isolation

2. macOS 防火墙

• 拦截 TCP 连接

3. mDNS（Bonjour）失败

• 设备发现正常，但端口不可达

---

推荐解决：

换 iPhone 热点
关闭防火墙测试
重新运行 flutter run

---

问题 3：能运行 App，但无法调试

原因：

VM Service 没成功 attach

解决：

---

问题 4：无线调试突然失效（之前正常）

常见触发原因：

• Xcode cache 异常
• Pods 重建
• xcconfig 被污染

修复：

---

问题 5：CocoaPods xcconfig 冲突

报错：

CocoaPods did not set base configuration

原因：

Flutter 自定义 xcconfig 覆盖 CocoaPods

修复方式：

在 Xcode：

• Runner → Build Settings
• Base Configuration 指向：

---

问题 6：Generated.xcconfig 丢失

原因：

flutter pub get 未执行或中断

修复：

---

六、稳定无线调试最佳实践

1. 推荐网络环境

• iPhone 热点，Mac电脑直接连接iPhone热点（最稳定）
• 或独立 5GHz Wi-Fi

---

2. 避免使用环境

• 公司 Wi-Fi（常有隔离）
• VPN 网络
• 公共热点

---

3. 开发习惯建议

调试优先 USB
无线用于验证 / 演示
不在 build 过程中切网络

---

七、底层机制理解（重要）

Flutter iOS 无线调试依赖三层：

设备发现（mDNS / Bonjour）

用于 flutter devices

---

VM Service（Dart 调试服务）

用于断点 / 热重载

---

TCP 连接

实际调试通道

---

任何一层失败都会导致：

• 设备看得到，但调试失败
• 或 75 秒超时

---

八、总结

一句话：

Flutter iOS 无线调试 = Xcode 网络调试 + Dart VM Service + 稳定局域网连接