# 调试 add-to-app 模块

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



Once you've integrated the Flutter module to your project and used
Flutter's platform APIs to run the Flutter engine and/or UI,
you can then build and run your Android or iOS app the same way
you run normal Android or iOS apps.

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

Flutter now powers the UI wherever your code includes
`FlutterActivity` or `FlutterViewController`.

只要你的代码中包含 `FlutterActivity` 或 `FlutterViewController`，
Flutter 就会驱动相应的 UI。

## Overview

## 概览

You might be used to having your suite of favorite Flutter debugging tools
available when running `flutter run` or an equivalent command from an IDE.
But you can also use all your Flutter [debugging functionalities][] such as
hot reload, performance overlays, DevTools, and setting breakpoints in
add-to-app scenarios.

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

The `flutter attach` command provides these functionalities.
To run this command, you can use the SDK's CLI tools, VS Code
or IntelliJ IDEA or Android Studio.

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

The `flutter attach` command connects once you run your `FlutterEngine`.
It remains attached until you dispose your `FlutterEngine`.
You can invoke `flutter attach` before starting your engine.
The `flutter attach` command waits for the next available Dart VM that
your engine hosts.

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

## Debug from the Terminal

## 从终端调试

To attach from the terminal, run `flutter attach`.
To select a specific target device, add `-d <deviceId>`.

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

```console
$ flutter attach
```

The command should print output resembling the following:

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

```console
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".
```

## Debug iOS extension in Xcode and VS Code

## 在 Xcode 与 VS Code 中调试 iOS 扩展

#### Build the iOS version of the Flutter app in the Terminal

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

To generate the needed iOS platform dependencies,
run the `flutter build` command.

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

```console
$ flutter build ios --config-only --no-codesign --debug
```

```console
Warning: Building for device with codesigning disabled. You will have to manually codesign before deploying to device.
Building com.example.myApp for device (ios)...
```

<Tabs key="darwin-debug-flow">
<!-- <Tab name="Start from VS Code"> -->
<Tab name="从 VS Code 开始">

#### Start debugging with VS Code first {:#vscode-ios}

#### 先从 VS Code 开始调试 {:#vscode-ios}

If you use VS Code to debug most of your code, start with this section.

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

##### Start the Dart debugger in VS Code

##### 在 VS Code 中启动 Dart 调试器

1. To open the Flutter app directory, go to
   **File** <span aria-label="and then">></span>
   **Open Folder...** and choose the `my_app` directory.

   要打开 Flutter app 目录，请前往
   **File** <span aria-label="and then">></span>
   **Open Folder...**，选择 `my_app` 目录。

1. Open the `lib/main.dart` file.

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

1. If you can build an app for more than one device,
   you must select the device first.

   若可为多种设备构建 app，须先选择设备。

   Go to
   **View** <span aria-label="and then">></span>
   **Command Palette...**

   前往
   **View** <span aria-label="and then">></span>
   **Command Palette...**

   You can also press <kbd>Ctrl</kbd> / <kbd>Cmd</kbd> +
   <kbd>Shift</kbd> + <kbd>P</kbd>.

   也可按 <kbd>Ctrl</kbd> / <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd>。

1. Type `flutter select`.

   输入 `flutter select`。

1. Click the **Flutter: Select Device** command.

   点击 **Flutter: Select Device** 命令。

1. Choose your target device.

   选择目标设备。

1. Click the debug icon
   (![VS Code's bug icon to trigger the debugging mode of a Flutter app](/assets/images/docs/testing/debugging/vscode-ui/icons/debug.png)).
   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.

   点击调试图标
   (![VS Code's bug icon to trigger the debugging mode of a Flutter app](/assets/images/docs/testing/debugging/vscode-ui/icons/debug.png))。
   这会打开 **Debug** 窗格并启动 app。
   等待 app 在设备上启动，且调试窗格显示 **Connected**。
   首次启动调试器耗时更长，之后启动会更快。

   This Flutter app contains two buttons:

   此 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 会启动浏览器。



##### Enable automatic attachment

##### 启用自动附加

You can configure VS Code to attach to your Flutter module project
whenever you start debugging.
To enable this feature,
create a `.vscode/launch.json` file in your Flutter module project.

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

1. Go to **View** <span aria-label="and then">></span> **Run**.

   前往 **View** <span aria-label="and then">></span> **Run**。

   You can also press
   <kbd>Ctrl</kbd> / <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>D</kbd>.

   也可按 <kbd>Ctrl</kbd> / <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>D</kbd>。

   VS Code displays the **Run and Debug** sidebar.

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

1. In this sidebar, click **create a launch.json file**.

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

   VS Code displays the **Select debugger** menu at the top.

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

1. Select **Dart & Flutter**.

   选择 **Dart & Flutter**。

   VS Code creates then opens the `.vscode/launch.json` file.

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

   <details markdown="1">
   <summary><t>Expand to see an example launch.json file</t><t>展开查看 launch.json 示例文件</t></summary>

    ```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"
            }
        ]
    }
    ```

    </details>

1. To attach, go to **Run** <span aria-label="and then">></span>
   **Start Debugging**.

   要附加，请前往 **Run** <span aria-label="and then">></span>
   **Start Debugging**。

   You can also press <kbd>F5</kbd>.

   也可按 <kbd>F5</kbd>。



##### Attach to the Flutter process in Xcode

##### 在 Xcode 中附加到 Flutter 进程

To attach to the Flutter app in Xcode:

要在 Xcode 中附加到 Flutter app：

1. Go to **Debug** <span aria-label="and then">></span> **Attach to Process**.

   前往 **Debug** <span aria-label="and then">></span> **Attach to Process**。

1. Select **Runner**. It should be at the top of the
   **Attach to Process** menu under the **Likely Targets** heading.

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

</Tab>
<!-- <Tab name="Start from Xcode"> -->
<Tab name="从 Xcode 开始">

#### Start debugging with Xcode first {:#xcode-ios}

#### 先从 Xcode 开始调试 {:#xcode-ios}

If you use Xcode to debug most of your code, start with this section.

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

##### Start the Xcode debugger

##### 启动 Xcode 调试器

1. Open `ios/Runner.xcworkspace` from your Flutter app directory.

   从 Flutter app 目录打开 `ios/Runner.xcworkspace`。

1. Select the correct device using the **Scheme** menu in the toolbar.

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

    If you have no preference, choose **iPhone Pro 14**.

    若无偏好，请选择 **iPhone Pro 14**。

   

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

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

    

    When the run completes, the **Debug** area at the bottom of Xcode displays
    a message with the Dart VM service URI. It resembles the following response:

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

    ```console
    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=/
    ```

1. Copy the Dart VM service URI.

   复制 Dart VM 服务 URI。

##### Attach to the Dart VM in VS Code

##### 在 VS Code 中附加到 Dart VM

1. To open the command palette, go to
    **View** <span aria-label="and then">></span>
    **Command Palette...**

   要打开命令面板，请前往
   **View** <span aria-label="and then">></span>
   **Command Palette...**

    You can also press <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd>.

    也可按 <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd>。

1. Type `debug`.

   输入 `debug`。

1. Click the **Debug: Attach to Flutter on Device** command.

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



1. In the **Paste an VM Service URI** box, paste the URI you copied
    from Xcode and press <kbd>Enter</kbd>.

   在 **Paste an VM Service URI** 框中粘贴从 Xcode 复制的 URI，
   然后按 <kbd>Enter</kbd>。



</Tab>
</Tabs>


## Debug Android extension in Android Studio

## 在 Android Studio 中调试 Android 扩展

1. To open the Flutter app directory, go to
   **File** <span aria-label="and then">></span>
   **Open...** and choose the `my_app` directory.

   要打开 Flutter app 目录，请前往
   **File** <span aria-label="and then">></span>
   **Open...**，选择 `my_app` 目录。

1. Open the `lib/main.dart` file.

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

1. Choose a virtual Android device.
   Go to the toolbar, open the leftmost dropdown menu, and click on
   **Open Android Emulator: \<device\>**.

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

   You can choose any installed emulator that's doesn't include `arm64`.

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

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

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

1. From the toolbar, click **Run 'main.dart'**.

   在工具栏点击 **Run 'main.dart'**。

   You can also press <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>R</kbd>.

   也可按 <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>R</kbd>。

   After the app displays in the emulator, continue to the next step.

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


[debugging functionalities]: /testing/debugging

## Debug without USB connection {:#wireless-debugging}

## 无 USB 连接调试

To debug your app over Wi-Fi on an iOS or Android device,
use `flutter attach`.

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

### Debug over Wi-Fi on iOS devices

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

For an iOS target, complete the follow steps:

对于 iOS 目标，请完成以下步骤：

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

   按 [iOS 设置指南][iOS setup guide] 所述，
   确认你的设备已通过 Wi-Fi 连接到 Xcode。

1. On your macOS development machine,
   open **Xcode** <span aria-label="and then">></span>
   **Product** <span aria-label="and then">></span>
   **Scheme** <span aria-label="and then">></span>
   **Edit Scheme...**.

   在你的 macOS 开发机上，
   打开 **Xcode** <span aria-label="and then">></span>
   **Product** <span aria-label="and then">></span>
   **Scheme** <span aria-label="and then">></span>
   **Edit Scheme...**。

   You can also press <kbd>Cmd</kbd> + <kbd><</kbd>.

   也可以按 <kbd>Cmd</kbd> + <kbd><</kbd>。

1. Click **Run**.

   点击 **Run**。

1. Click **Arguments**.

   点击 **Arguments**。

1. In **Arguments Passed On Launch**, Click **+**.

   在 **Arguments Passed On Launch** 中，点击 **+**。

   {:type="a"}
   1. If your dev machine uses IPv4, add `--vm-service-host=0.0.0.0`.

      若你的开发机使用 IPv4，请添加 `--vm-service-host=0.0.0.0`。

   1. If your dev machine uses IPv6, add `--vm-service-host=::0`.

      若你的开发机使用 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%" />

#### To determine if you're on an IPv6 network

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

1. Open **Settings** <span aria-label="and then">></span> **Wi-Fi**.

   打开 **Settings** <span aria-label="and then">></span> **Wi-Fi**。

1. Click on your connected network.

   点击你已连接的网络。

1. Click **Details...**

   点击 **Details...**

1. Click **TCP/IP**.

   点击 **TCP/IP**。

1. Check for an **IPv6 address** section.

   查看是否有 **IPv6 address** 部分。

   <DashImage figure img-class="site-mobile-screenshot border" image="development/add-to-app/ipv6.png" caption="WiFi dialog box for macOS System Settings" width="60%" />

### Debug over Wi-Fi on Android devices

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

Verify your device connects to Android Studio over Wi-Fi
as described in the [Android setup guide][].

按 [Android 设置指南][Android setup guide] 所述，
确认你的设备已通过 Wi-Fi 连接到 Android Studio。

[iOS setup guide]: /platform-integration/ios/setup
[Android setup guide]: /platform-integration/android/setup#set-up-devices