使用原生语言调试器

如果你仅用 Dart 代码编写 Flutter 应用，可以使用 IDE 的调试器调试代码。 Flutter 团队推荐使用 VS Code。

如果你编写平台特定插件或使用平台特定库，可以使用原生调试器调试那部分代码。

• To debug iOS or macOS code written in Swift or Objective-C, you can use Xcode.

• To debug Android code written in Java or Kotlin, you can use Android Studio.

• To debug Windows code written in C++, you can use Visual Studio.

• 要调试用 Swift 或 Objective-C 编写的 iOS 或 macOS 代码，可以使用 Xcode。

• 要调试用 Java 或 Kotlin 编写的 Android 代码，可以使用 Android Studio。

• 要调试用 C++ 编写的 Windows 代码，可以使用 Visual Studio。

本指南说明如何将 两个 调试器连接到你的 Dart 应用：一个用于 Dart，一个用于原生代码。

本指南介绍如何使用 VS Code 调试 Flutter 应用。你也可以使用已安装并配置 Flutter 和 Dart 插件的首选 IDE。

以下步骤说明如何将 Dart 调试器与默认示例 Flutter 应用配合使用。在调试你自己的 Flutter 项目时， VS Code 中展示的这些组件同样可用并会出现。

1. Create a basic Flutter app.

   1. 创建一个基本的 Flutter 应用。

   $ flutter create my_app
   

   content_copy

   Creating project my_app...
   Resolving dependencies in my_app...
   Got dependencies in my_app.
   Wrote 129 files.
   
   All done!
   You can find general documentation for Flutter at: https://docs.flutter.dev/
   Detailed API documentation is available at: https://api.flutter.dev/
   If you prefer video documentation, consider: https://www.youtube.com/c/flutterdev
   
   In order to run your application, type:
   
     $ cd my_app
     $ flutter run
   
   Your application code is in my_app/lib/main.dart.
   

   content_copy

   $ cd my_app
   

   content_copy

2. Open the lib\main.dart file in the Flutter app using VS Code.

   1. 使用 VS Code 打开 Flutter 应用中的 lib\main.dart 文件。

3. Click the bug icon (). This opens the following panes in VS Code:

   1. 点击虫子图标（）。这会在 VS Code 中打开以下窗格：

   • Debug

   • Debug Console

   • Widget Inspector

   • Debug

   • Debug Console

   • Widget Inspector

   首次运行调试器耗时最长。

4. Test the debugger.

   1. 测试调试器。

   a. 在 main.dart 中，点击这一行：

   dart

   _counter++;
   

   content_copy

   b. 按 Shift + F9。这会在 _counter 变量递增处添加断点。

   c. 在应用中，点击 + 按钮以增加计数器。应用会暂停。

   d. 此时，VS Code 会显示：

   • In the Editor Groups:

     • The highlighted breakpoint in main.dart
     • The widget hierarchy for the Flutter app in the Widget Tree of the Widget Inspector

   • In the side bar:

     • The state of the app in the Call Stack section
     • The value of the this local variable in the Variables section

   • In the panel:

     • The log of the Flutter app in the Debug console

   • 在 Editor Groups 中：

     • main.dart 中高亮的断点
     • Widget Inspector 的 Widget Tree 中 Flutter 应用的 widget 层级

   • 在侧边栏中：

     • Call Stack 部分中的应用状态
     • Variables 部分中 this 局部变量的值

   • 在面板中：

     • Debug console 中的 Flutter 应用日志

VS Code 的 Flutter 插件会向 VS Code 用户界面添加多个组件。

启动后，Flutter 调试器会向 VS Code 界面添加调试工具。

以下截图和表格说明每个工具的用途。

要更改面板（橙色）在 VS Code 中的位置，请前往 View > Appearance > Panel Position。

工具栏允许你使用任何调试器进行调试。你可以单步进入、跳出和跳过 Dart 语句，热重载或恢复应用。

Icon	Action	Default keyboard shortcut

| Start or Resume | F5 | |

| Pause | F6 | |

| Step Over | F10 | |

| Step Into | F11 | |

| Step Out | Shift + F11 | |

| Hot Reload | Ctrl + F5 | |

| Hot Restart | Shift + Special + F5 | |

| Stop | Shift + F5 | |

| Open Widget Inspector | |

图标	操作	默认键盘快捷键

| 启动或恢复 | F5 | |

| 暂停 | F6 | |

| 单步跳过 | F10 | |

| 单步进入 | F11 | |

| 单步跳出 | Shift + F11 | |

| 热重载 | Ctrl + F5 | |

| 热重启 | Shift + Special + F5 | |

| 停止 | Shift + F5 | |

| 打开 Widget Inspector | |

在本指南的其余部分，你需要更新测试用 Flutter 应用。此更新会添加用于调试的原生代码。

1. Open the lib/main.dart file using your preferred IDE.

   1. 使用你首选的 IDE 打开 lib/main.dart 文件。

2. Replace the contents of main.dart with the following code.

   1. 将 main.dart 的内容替换为以下代码。
   Expand to see Flutter code for this example · 展开以查看此示例的 Flutter 代码

   lib/main.dart

   dart

   // Copyright 2023 The Flutter Authors. All rights reserved.
   // Use of this source code is governed by a BSD-style license that can be
   // found in the LICENSE file.
   ​
   import 'package:flutter/material.dart';
   import 'package:url_launcher/url_launcher.dart';
   ​
   void main() {
     runApp(const MyApp());
   }
   ​
   class MyApp extends StatelessWidget {
     const MyApp({super.key});
   ​
     @override
     Widget build(BuildContext context) {
       return MaterialApp(
         title: 'URL Launcher',
         theme: ThemeData(
           colorSchemeSeed: Colors.purple,
           brightness: Brightness.light,
         ),
         home: const MyHomePage(title: 'URL Launcher'),
       );
     }
   }
   ​
   class MyHomePage extends StatefulWidget {
     const MyHomePage({super.key, required this.title});
     final String title;
   ​
     @override
     State<MyHomePage> createState() => _MyHomePageState();
   }
   ​
   class _MyHomePageState extends State<MyHomePage> {
     Future<void>? _launched;
   ​
     Future<void> _launchInBrowser(Uri url) async {
       if (!await launchUrl(
         url,
         mode: LaunchMode.externalApplication,
       )) {
         throw Exception('Could not launch $url');
       }
     }
   ​
     Future<void> _launchInWebView(Uri url) async {
       if (!await launchUrl(
         url,
         mode: LaunchMode.inAppWebView,
       )) {
         throw Exception('Could not launch $url');
       }
     }
   ​
     Widget _launchStatus(BuildContext context, AsyncSnapshot<void> snapshot) {
       if (snapshot.hasError) {
         return Text('Error: ${snapshot.error}');
       } else {
         return const Text('');
       }
     }
   ​
     @override
     Widget build(BuildContext context) {
       final Uri toLaunch = Uri(
           scheme: 'https',
           host: 'docs.flutter.dev',
           path: 'testing/native-debugging');
       return Scaffold(
         appBar: AppBar(
           title: Text(widget.title),
         ),
         body: Center(
           child: Column(
             mainAxisAlignment: MainAxisAlignment.center,
             children: <Widget>[
               Padding(
                 padding: const EdgeInsets.all(16),
                 child: Text(toLaunch.toString()),
               ),
               FilledButton(
                 onPressed: () => setState(() {
                   _launched = _launchInBrowser(toLaunch);
                 }),
                 child: const Text('Launch in browser'),
               ),
               const Padding(padding: EdgeInsets.all(16)),
               FilledButton(
                 onPressed: () => setState(() {
                   _launched = _launchInWebView(toLaunch);
                 }),
                 child: const Text('Launch in app'),
               ),
               const Padding(padding: EdgeInsets.all(16.0)),
               FutureBuilder<void>(future: _launched, builder: _launchStatus),
             ],
           ),
         ),
       );
     }
   }
   

   content_copy

3. To add the url_launcher package as a dependency, run flutter pub add:

   1. 要将 url_launcher 包添加为依赖，请运行 flutter pub add：

   $ flutter pub add url_launcher
   

   content_copy

   Resolving dependencies...
     collection 1.17.1 (1.17.2 available)
   + flutter_web_plugins 0.0.0 from sdk flutter
     matcher 0.12.15 (0.12.16 available)
     material_color_utilities 0.2.0 (0.8.0 available)
   + plugin_platform_interface 2.1.4
     source_span 1.9.1 (1.10.0 available)
     stream_channel 2.1.1 (2.1.2 available)
     test_api 0.5.1 (0.6.1 available)
   + url_launcher 6.1.11
   + url_launcher_android 6.0.36
   + url_launcher_ios 6.1.4
   + url_launcher_linux 3.0.5
   + url_launcher_macos 3.0.5
   + url_launcher_platform_interface 2.1.3
   + url_launcher_web 2.0.17
   + url_launcher_windows 3.0.6
   Changed 10 dependencies!
   

   content_copy

4. To check what changed with the codebase:

   1. 要检查代码库有哪些变更：

   1. In Linux or macOS, run this find command.

      1. 在 Linux 或 macOS 上，运行此 find 命令。

      $ find ./ -mmin -120
      

      content_copy

      ./ios/Flutter/Debug.xcconfig
      ./ios/Flutter/Release.xcconfig
      ./linux/flutter/generated_plugin_registrant.cc
      ./linux/flutter/generated_plugins.cmake
      ./macos/Flutter/Flutter-Debug.xcconfig
      ./macos/Flutter/Flutter-Release.xcconfig
      ./macos/Flutter/GeneratedPluginRegistrant.swift
      ./pubspec.lock
      ./pubspec.yaml
      ./windows/flutter/generated_plugin_registrant.cc
      ./windows/flutter/generated_plugins.cmake
      

      content_copy

   2. In Windows, run this command in the command prompt.

      1. 在 Windows 上，在命令提示符中运行此命令。

      Get-ChildItem C:\dev\example\ -Rescurse | Where-Object {$_.LastWriteTime -gt (Get-Date).AddDays(-1)}
      

      content_copy

      C:\dev\example\ios\Flutter\
      
      
      Mode                LastWriteTime         Length Name
      ----                -------------         ------ ----
                      8/1/2025   9:15 AM                Debug.xcconfig
                      8/1/2025   9:15 AM                Release.xcconfig
      
      C:\dev\example\linux\flutter\
      
      
      Mode                LastWriteTime         Length Name
      ----                -------------         ------ ----
                      8/1/2025   9:15 AM                generated_plugin_registrant.cc
                      8/1/2025   9:15 AM                generated_plugins.cmake
      
      C:\dev\example\macos\Flutter\
      
      
      Mode                LastWriteTime         Length Name
      ----                -------------         ------ ----
                      8/1/2025   9:15 AM                Flutter-Debug.xcconfig
                      8/1/2025   9:15 AM                Flutter-Release.xcconfig
                      8/1/2025   9:15 AM                GeneratedPluginRegistrant.swift
      
      C:\dev\example\
      
      
      Mode                LastWriteTime         Length Name
      ----                -------------         ------ ----
                      8/1/2025   9:15 AM                pubspec.lock
                      8/1/2025   9:15 AM                pubspec.yaml
      
      C:\dev\example\windows\flutter\
      
      
      Mode                LastWriteTime         Length Name
      ----                -------------         ------ ----
                      8/1/2025   9:15 AM                generated_plugin_registrant.cc
                      8/1/2025   9:15 AM                generated_plugins.cmake
      

      content_copy

安装 url_launcher 会在 Flutter 应用目录中为所有目标平台添加配置文件和代码文件。

本节说明如何调试 Flutter 应用中的 Dart 代码，并使用其常规调试器调试任何原生代码。此能力让你在编辑原生代码时仍可利用 Flutter 的热重载。

要调试原生 Android 代码，你需要包含 Android 代码的 Flutter 应用。在本节中，你将学习如何将 Dart、Java 和 Kotlin 调试器连接到你的应用。调试 Dart 与 Android 代码不一定需要 VS Code。本指南包含 VS Code 说明，以与 Xcode 和 Visual Studio 指南保持一致。

本节使用在更新测试用 Flutter 应用中创建的相同示例 Flutter url_launcher 应用。

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

flutter build appbundle --debug

Running Gradle task 'bundleDebug'...                               27.1s
✓ Built build/app/outputs/bundle/debug/app-debug.aab.

要调试 iOS 代码，你需要包含 iOS 代码的 Flutter 应用。在本节中，你将学习将两个调试器连接到你的应用：通过 VS Code 的 Flutter 与 Xcode。你需要同时运行 VS Code 和 Xcode。

本节使用在更新测试用 Flutter 应用中创建的相同示例 Flutter url_launcher 应用。

要生成所需的 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)...

要调试 macOS 代码，你需要包含 macOS 代码的 Flutter 应用。在本节中，你将学习将两个调试器连接到你的应用：通过 VS Code 的 Flutter 与 Xcode。你需要同时运行 VS Code 和 Xcode。

本节使用在更新测试用 Flutter 应用中创建的相同示例 Flutter url_launcher 应用。

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

flutter build macos --debug

Building macOS application...

要调试 C++ 代码，你需要包含 C++ 代码的 Flutter 应用。在本节中，你将学习将两个调试器连接到你的应用：通过 VS Code 的 Flutter 与 Visual Studio。你需要同时运行 VS Code 和 Visual Studio。

本节使用在更新测试用 Flutter 应用中创建的相同示例 Flutter url_launcher 应用。

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

C:\> flutter build windows --debug

Building Windows application...                                    31.4s
√  Built build\windows\runner\Debug\my_app.exe.

请查阅以下关于调试 Flutter、iOS、Android、 macOS 和 Windows 的资源：

• 调试 Flutter 应用

• Flutter inspector 与 DevTools 文档

• 性能分析

你可以在 developer.android.com 上找到以下调试资源。

• 调试你的应用

• Android Debug Bridge (adb)

  Android Debug Bridge (adb)

你可以在 developer.apple.com 上找到以下调试资源。

• 调试

• Instruments 帮助

你可以在 Microsoft Learn 上找到调试资源。

• Visual Studio 调试器

• 学习使用 Visual Studio 调试 C++ 代码