跳转至正文

调试 add-to-app 模块

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

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

只要代码中包含 FlutterActivityFlutterViewController,UI 就由 Flutter 驱动。

概览

#

你可能习惯在 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. To open the Flutter app directory, go to File > Open Folder... and choose the my_app directory.

    1. 要打开 Flutter app 目录,请前往 File > Open Folder...,选择 my_app 目录。
  2. Open the lib/main.dart file.

    1. 打开 lib/main.dart 文件。
  3. If you can build an app for more than one device, you must select the device first.

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

    前往 View > Command Palette...

    也可按 Ctrl / Cmd + Shift + P

  4. Type flutter select.

    1. 输入 flutter select
  5. Click the Flutter: Select Device command.

    1. 点击 Flutter: Select Device 命令。
  6. Choose your target device.

    1. 选择目标设备。
  7. Click the debug icon (VS Code's bug icon to trigger the debugging mode of a Flutter app). This opens the Debug pane and launches the app. Wait for the app to launch on the device and for the debug pane to indicate Connected. The debugger takes longer to launch the first time. Subsequent launches start faster.

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

    此 Flutter app 包含两个按钮:

    • Launch in browser: This button opens this page in the default browser of your device.

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

    • Launch in app: This button opens this page within your app. This button only works for iOS or Android. Desktop apps launch a browser.

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

启用自动附加
#

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

  1. Go to View > Run.

    1. 前往 View > Run

    也可按 Ctrl / Cmd + Shift + D

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

  2. In this sidebar, click create a launch.json file.

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

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

  3. Select Dart & Flutter.

    1. 选择 Dart & Flutter

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

    Expand to see an example launch.json file展开查看 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. To attach, go to Run > Start Debugging.

    1. 要附加,请前往 Run > Start Debugging

    也可按 F5

在 Xcode 中附加到 Flutter 进程
#

要在 Xcode 中附加到 Flutter app:

  1. Go to Debug > Attach to Process.

    1. 前往 Debug > Attach to Process
  2. Select Runner. It should be at the top of the Attach to Process menu under the Likely Targets heading.

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

先从 Xcode 开始调试

#

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

启动 Xcode 调试器
#
  1. Open ios/Runner.xcworkspace from your Flutter app directory.

    1. 从 Flutter app 目录打开 ios/Runner.xcworkspace
  2. Select the correct device using the Scheme menu in the toolbar.

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

    若无偏好,请选择 iPhone Pro 14

  3. Run this Runner as a normal app in Xcode.

    1. 在 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. Copy the Dart VM service URI.

    1. 复制 Dart VM 服务 URI。
在 VS Code 中附加到 Dart VM
#
  1. To open the command palette, go to View > Command Palette...

    1. 要打开命令面板,请前往 View > Command Palette...

    也可按 Cmd + Shift + P

  2. Type debug.

    1. 输入 debug
  3. Click the Debug: Attach to Flutter on Device command.

    1. 点击 Debug: Attach to Flutter on Device 命令。
  4. In the Paste an VM Service URI box, paste the URI you copied from Xcode and press Enter.

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

在 Android Studio 中调试 Android 扩展

#
  1. To open the Flutter app directory, go to File > Open... and choose the my_app directory.

    1. 要打开 Flutter app 目录,请前往 File > Open...,选择 my_app 目录。
  2. Open the lib/main.dart file.

    1. 打开 lib/main.dart 文件。
  3. Choose a virtual Android device. Go to the toolbar, open the leftmost dropdown menu, and click on Open Android Emulator: <device>.

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

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

  4. From that same menu, select the virtual Android device.

    1. 在同一菜单中选择该虚拟 Android 设备。
  5. From the toolbar, click Run 'main.dart'.

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

    也可按 Ctrl + Shift + R

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

无 USB 连接调试

#

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

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

#

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

  1. Verify your device connects to Xcode over Wi-Fi as described in the iOS setup guide.

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

  3. On your macOS development machine, open Xcode > Product > Scheme > Edit Scheme....

    You can also press Cmd + <.

  4. 在 macOS 开发机上,打开 Xcode > Product > Scheme > Edit Scheme...

    也可以按 Cmd + <

  5. Click Run.

  6. 点击 Run

  7. Click Arguments.

  8. 点击 Arguments

  9. In Arguments Passed On Launch, Click +.

    1. If your dev machine uses IPv4, add --vm-service-host=0.0.0.0.

    2. If your dev machine uses IPv6, add --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%" />

  10. 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. Open Settings > Wi-Fi.

  2. 打开 Settings > Wi-Fi

  3. Click on your connected network.

  4. 点击已连接的网络。

  5. Click Details...

  6. 点击 Details...

  7. Click TCP/IP.

  8. 点击 TCP/IP

  9. Check for an IPv6 address section.

    WiFi dialog box for macOS System Settings

    WiFi dialog box for macOS System Settings

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

    WiFi dialog box for macOS System Settings

    WiFi dialog box for macOS System Settings

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

#

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