跳转至正文

调试 add-to-app 模块

如何运行、调试并对 add-to-app Flutter 模块进行热重载。

将 Flutter 模块集成到你的项目,并使用 Flutter 平台 API 运行 Flutter 引擎和/或 UI 之后,你就可以像运行普通 Android 或 iOS 应用一样,构建并运行你的 Android 或 iOS 应用。

只要你的代码中包含 FlutterActivityFlutterViewController, Flutter 就会驱动相应的 UI。

概览

#

你可能习惯了在 IDE 中运行 flutter run 或等效命令时,使用一整套你喜爱的 Flutter 调试工具。但在 add-to-app 场景中,你同样可以使用所有 Flutter 调试功能,例如热重载、性能叠加层、DevTools 以及设置断点。

flutter attach 命令提供这些功能。要运行此命令,你可以使用 SDK 的 CLI 工具、VS Code、 IntelliJ IDEA 或 Android Studio。

运行 FlutterEngine 后,flutter attach 命令便会建立连接,并在你 dispose FlutterEngine 之前保持连接。你可以在启动引擎之前调用 flutter attach,该命令会等待引擎托管的下一个可用 Dart VM。

从终端调试

#

要从终端附加调试,请运行 flutter attach。要选择特定的目标设备,请添加 -d <deviceId>

flutter attach

该命令应打印出类似以下的输出:

Syncing files to device iPhone 15 Pro...
 7,738ms (!)

To hot reload the changes while running, press "r".
To hot restart (and rebuild state). press "R".

在 Xcode 与 VS Code 中调试 iOS 扩展

#

在终端中构建 Flutter app 的 iOS 版本

#

要生成所需的 iOS 平台依赖,请运行 flutter build 命令。

flutter build ios --config-only --no-codesign --debug
Warning: Building for device with codesigning disabled. You will have to manually codesign before deploying to device.
Building com.example.myApp for device (ios)...

先从 VS Code 开始调试

#

若你主要用 VS Code 调试代码,请从本节开始。

在 VS Code 中启动 Dart 调试器
#
  1. 要打开 Flutter app 目录,请前往 File > Open Folder...,选择 my_app 目录。

  2. 打开 lib/main.dart 文件。

  3. 若可为多种设备构建 app,须先选择设备。

    前往 View > Command Palette...

    也可按 Ctrl / Cmd + Shift + P

  4. 输入 flutter select

  5. 点击 Flutter: Select Device 命令。

  6. 选择目标设备。

  7. 点击调试图标 (VS Code's bug icon to trigger the debugging mode of a Flutter app)。这会打开 Debug 窗格并启动 app。等待 app 在设备上启动,且调试窗格显示 Connected。首次启动调试器耗时更长,之后启动会更快。

    此 Flutter app 包含两个按钮:

    • Launch in browser:此按钮会在设备的默认浏览器中打开本页。

    • Launch in app:此按钮会在 app 内打开本页。仅适用于 iOS 或 Android。桌面 app 会启动浏览器。

启用自动附加
#

你可以配置 VS Code,使其在你开始调试时自动附加到 Flutter 模块项目。要启用此功能,请在 Flutter 模块项目中创建 .vscode/launch.json 文件。

  1. 前往 View > Run

    也可按 Ctrl / Cmd + Shift + D

    VS Code 会显示 Run and Debug 侧边栏。

  2. 在此侧边栏中点击 create a launch.json file

    VS Code 会在顶部显示 Select debugger 菜单。

  3. 选择 Dart & Flutter

    VS Code 会创建并打开 .vscode/launch.json 文件。

    展开查看 launch.json 示例文件
    json
    {
        // Use IntelliSense to learn about possible attributes.
        // Hover to view descriptions of existing attributes.
        // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
        "version": "0.2.0",
        "configurations": [
            {
                "name": "my_app",
                "request": "launch",
                "type": "dart"
            },
            {
                "name": "my_app (profile mode)",
                "request": "launch",
                "type": "dart",
                "flutterMode": "profile"
            },
            {
                "name": "my_app (release mode)",
                "request": "launch",
                "type": "dart",
                "flutterMode": "release"
            }
        ]
    }
    
  4. 要附加,请前往 Run > Start Debugging

    也可按 F5

在 Xcode 中附加到 Flutter 进程
#

要在 Xcode 中附加到 Flutter app:

  1. 前往 Debug > Attach to Process

  2. 选择 Runner。它应位于 Attach to Process 菜单 Likely Targets 标题下的顶部。

先从 Xcode 开始调试

#

若你主要用 Xcode 调试代码,请从本节开始。

启动 Xcode 调试器
#
  1. 从 Flutter app 目录打开 ios/Runner.xcworkspace

  2. 使用工具栏中的 Scheme 菜单选择正确的设备。

    若无偏好,请选择 iPhone Pro 14

  3. 在 Xcode 中将此 Runner 作为普通 app 运行。

    运行完成后,Xcode 底部的 Debug 区域会显示包含 Dart VM 服务 URI 的消息,类似以下输出:

    2023-07-12 14:55:39.966191-0500 Runner[58361:53017145]
        flutter: The Dart VM service is listening on
        http://127.0.0.1:50642/00wEOvfyff8=/
    
  4. 复制 Dart VM 服务 URI。

在 VS Code 中附加到 Dart VM
#
  1. 要打开命令面板,请前往 View > Command Palette...

    也可按 Cmd + Shift + P

  2. 输入 debug

  3. 点击 Debug: Attach to Flutter on Device 命令。

  4. Paste an VM Service URI 框中粘贴从 Xcode 复制的 URI,然后按 Enter

在 Android Studio 中调试 Android 扩展

#
  1. 要打开 Flutter app 目录,请前往 File > Open...,选择 my_app 目录。

  2. 打开 lib/main.dart 文件。

  3. 选择虚拟 Android 设备。在工具栏打开最左侧下拉菜单,点击 Open Android Emulator: <device>

    你可以选择任何已安装且名称中不包含 arm64 的模拟器。

  4. 在同一菜单中选择该虚拟 Android 设备。

  5. 在工具栏点击 Run 'main.dart'

    也可按 Ctrl + Shift + R

    app 在模拟器中显示后,继续下一步。

无 USB 连接调试

#

要在 iOS 或 Android 设备上通过 Wi-Fi 调试你的应用,请使用 flutter attach

在 iOS 设备上通过 Wi-Fi 调试

#

对于 iOS 目标,请完成以下步骤:

  1. iOS 设置指南 所述,确认你的设备已通过 Wi-Fi 连接到 Xcode。

  2. 在你的 macOS 开发机上,打开 Xcode > Product > Scheme > Edit Scheme...

    也可以按 Cmd + <

  3. 点击 Run

  4. 点击 Arguments

  5. Arguments Passed On Launch 中,点击 +

    1. 若你的开发机使用 IPv4,请添加 --vm-service-host=0.0.0.0

    2. 若你的开发机使用 IPv6,请添加 --vm-service-host=::0

    <DashImage figure img-class="site-mobile-screenshot border" image="development/add-to-app/debugging/wireless-port.png" caption="Arguments Passed On Launch with an IPv4 network added", width="100%" />

如何判断你是否处于 IPv6 网络

#
  1. 打开 Settings > Wi-Fi

  2. 点击你已连接的网络。

  3. 点击 Details...

  4. 点击 TCP/IP

  5. 查看是否有 IPv6 address 部分。

    WiFi dialog box for macOS System Settings

    WiFi dialog box for macOS System Settings

在 Android 设备上通过 Wi-Fi 调试

#

Android 设置指南 所述,确认你的设备已通过 Wi-Fi 连接到 Android Studio。