使用原生語言除錯器

如果你只用 Dart 程式碼撰寫 Flutter 應用程式，可以直接使用你的 IDE 除錯器來除錯程式碼。Flutter 團隊推薦使用 VS Code。

如果你撰寫平台專屬的 plugin 或使用平台專屬的函式庫，你可以使用原生除錯器來除錯這部分的程式碼。

• 若要除錯以 Swift 或 Objective-C 撰寫的 iOS 或 macOS 程式碼，可以使用 Xcode。
• 若要除錯以 Java 或 Kotlin 撰寫的 Android 程式碼，可以使用 Android Studio。
• 若要除錯以 C++ 撰寫的 Windows 程式碼，可以使用 Visual Studio。

本指南將說明如何為你的 Dart 應用程式同時連接「兩個」除錯器，一個用於 Dart，另一個用於原生程式碼。

本指南將說明如何使用 VS Code 來除錯你的 Flutter 應用程式。你也可以使用你偏好的 IDE，只要安裝並設定好 Flutter 與 Dart 外掛即可。

以下步驟說明如何使用 Dart 除錯器來除錯預設的 Flutter 範例應用程式。這些在 VS Code 中提供的功能元件，在你除錯自己的 Flutter 專案時同樣適用且會顯示。

1. 建立一個基本的 Flutter 應用程式。

   flutter create my_app

   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.

   cd my_app

2. 在 Flutter 應用程式中，使用 VS Code 開啟 lib\main.dart 檔案。

3. 點擊錯誤偵錯圖示（bug icon） (）。 這會在 VS Code 中開啟以下面板：

   • Debug
   • Debug Console
   • Widget Inspector（元件檢查器）

   第一次執行偵錯工具時，所需時間會比較長。

4. 測試偵錯工具。

   a. 在 main.dart 中，點擊這一行：

   dart

   _counter++;

   b. 按下 Shift + F9。 這會在 _counter 變數遞增的地方新增一個中斷點。

   c. 在應用程式中，點擊 + 按鈕 來遞增計數器。應用程式會暫停。

   d. 此時，VS Code 會顯示：

   • 在 編輯器群組（Editor Groups） 中：
     • main.dart 中被標記的中斷點
     • Flutter 應用程式的元件階層（widget hierarchy）， 顯示於 Widget Inspector 的 Widget Tree
   • 在 側邊欄（side bar） 中：
     • Call Stack 區段中的應用程式狀態
     • Variables 區段中 this 區域變數的值
   • 在 面板（panel） 中：
     • Debug console 中 Flutter 應用程式的日誌

Flutter 外掛程式會為 VS Code 增加多項 使用者介面元件。

啟動後，Flutter 除錯器會在 VS Code 介面中加入除錯工具。

下方的螢幕截圖與表格說明了各個工具的用途。

若要變更 VS Code 中面板（橘色）的位置， 請前往 檢視（View） > 外觀（Appearance） > 面板位置（Panel Position）。

此工具列可讓你使用任何除錯器進行除錯。 你可以逐步執行 Dart 陳述式、熱重載（hot reload）、或繼續執行應用程式。

圖示	動作	預設鍵盤快捷鍵
	啟動或繼續執行	F5
	暫停	F6
	單步跳過（Step Over）	F10
	單步執行（Step Into）	F11
	單步跳出（Step Out）	Shift + F11
	熱重載（Hot Reload）	Ctrl + F5
	熱重啟（Hot Restart）	Shift + Special + F5
	停止	Shift + F5
	開啟 Widget Inspector

在本指南的接下來部分，你需要更新 測試用 Flutter 應用程式。這次更新會加入可進行原生除錯的程式碼。

1. 使用你偏好的 IDE 開啟 lib/main.dart 檔案。

2. 用下列程式碼取代 main.dart 的內容。

   展開以檢視本範例的 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),
             ],
           ),
         ),
       );
     }
   }

3. 若要將 url_launcher 套件新增為相依套件，請執行 flutter pub add：

   flutter pub add url_launcher

   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!

4. 檢查程式碼庫有何變更：

   1. 在 Linux 或 macOS 上，執行此 find 指令。

      find ./ -mmin -120

      ./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

   2. 在 Windows 中，請在命令提示字元（Command Prompt）執行以下指令。

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

      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

安裝 url_launcher 會在 Flutter 應用程式目錄中為所有目標平台新增設定檔與程式碼檔案。

本節說明如何同時使用 Flutter 的熱重載（hot reload）功能，來偵錯 Flutter 應用程式中的 Dart 程式碼，以及使用各自原生除錯器偵錯原生程式碼。此功能可讓你在編輯原生程式碼時，充分利用 Flutter 的熱重載。

若要偵錯原生 Android 程式碼，你需要一個包含 Android 程式碼的 Flutter 應用程式。在本節中，你將學習如何將 Dart、Java 與 Kotlin 除錯器連接到你的應用程式。你不需要 VS Code 來同時偵錯 Dart 與 Android 程式碼。本指南包含 VS Code 的操作說明，是為了與 Xcode 及 Visual Studio 指南保持一致。

本節使用在 Update test Flutter app 中建立的相同範例 Flutter url_launcher 應用程式。

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

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。

本節使用在 Update test Flutter app 中建立的相同範例 Flutter url_launcher 應用程式。

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

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。

本節使用在 Update test Flutter app 中建立的相同範例 Flutter url_launcher 應用程式。

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

flutter build macos --debug

Building macOS application...

若要偵錯 C++ 程式碼，你需要一個包含 C++ 程式碼的 Flutter 應用程式。在本節中，你將學習如何將兩個除錯器連接到你的應用程式：透過 VS Code 的 Flutter 除錯器，以及 Visual Studio。你需要同時執行 VS Code 與 Visual Studio。

本節使用在 Update test Flutter app 中建立的相同範例 Flutter url_launcher 應用程式。

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

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 檢查器 以及 DevTools 文件
• 效能分析

你可以在 developer.android.com 找到以下偵錯資源。

• 偵錯你的應用程式
• Android Debug Bridge (adb)

你可以在 developer.apple.com 找到以下偵錯資源。

• 偵錯
• Instruments 說明

你可以在 Microsoft Learn 找到 Windows 偵錯相關資源。

• Visual Studio 除錯器
• 學習如何使用 Visual Studio 偵錯 C++ 程式碼