通过代码调试应用

通过输出代码的方式调试 Flutter 应用

测试 Flutter 应用chevron_right通过输出代码的方式调试 Flutter 应用

This guide describes which debugging features you can enable in your code. For a full list of debugging and profiling tools, check out the Debugging page.

info提示

If you are looking for a way to use GDB to remotely debug the Flutter engine running within an Android app process, check out flutter_gdb.

Add logging to your application

info提示

You can view logs in DevTools' Logging view or in your system console. This sections shows how to set up your logging statements.

You have two options for logging for your application.

Print to stdout and stderr using print() statements.
Import dart:io and invoking methods on stderr and stdout. For example:

dart
```
stderr.writeln('print me');
```
content_copy

If you output too much at once, then Android might discard some log lines. To avoid this outcome, use debugPrint() from Flutter's foundation library. This wrapper around print throttles the output to avoid the Android kernel dropping output.

You can also log your app using the dart:developer log() function. This allows you to include greater granularity and more information in the logging output.

Example 1

dart

import 'dart:developer' as developer;

void main() {
  developer.log('log me', name: 'my.app.category');

  developer.log('log me 1', name: 'my.other.category');
  developer.log('log me 2', name: 'my.other.category');
}

content_copy

You can also pass app data to the log call. The convention for this is to use the error: named parameter on the log() call, JSON encode the object you want to send, and pass the encoded string to the error parameter.

Example 2

dart

import 'dart:convert';
import 'dart:developer' as developer;

void main() {
  var myCustomObject = MyCustomObject();

  developer.log(
    'log me',
    name: 'my.app.category',
    error: jsonEncode(myCustomObject),
  );
}

content_copy

DevTool's logging view interprets the JSON encoded error parameter as a data object. DevTool renders in the details view for that log entry.

Set breakpoints

You can set breakpoints in DevTools' Debugger or in the built-in debugger of your IDE.

To set programmatic breakpoints:

Import the dart:developer package into the relevant file.
Insert programmatic breakpoints using the debugger() statement. This statement takes an optional when argument. This boolean argument sets a break when the given condition resolves to true.

Example 3 illustrates this.

Example 3

dart

import 'dart:developer';

void someFunction(double offset) {
  debugger(when: offset > 30);
  // ...
}

content_copy

Debug app layers using flags

Each layer of the Flutter framework provides a function to dump its current state or events to the console using the debugPrint property.

info提示

All of the following examples were run as macOS native apps on a MacBook Pro M1. These will differ from any dumps your development machine prints.

lightbulb小提示

Each render object in any tree includes the first five hexadecimal digits of its hashCode. This hash serves as a unique identifier for that render object.

To dump the state of the Widgets library, call the debugDumpApp() function.

Open your source file.
Import package:flutter/rendering.dart.
Call the debugDumpApp() function from within the runApp() function. You need your app in debug mode. You cannot call this function inside a build() method when the app is building.
If you haven't started your app, debug it using your IDE.
If you have started your app, save your source file. Hot reload re-renders your app.

Example 4: Call `debugDumpApp()`

dart

import 'package:flutter/material.dart';

void main() {
  runApp(
    const MaterialApp(
      home: AppHome(),
    ),
  );
}

class AppHome extends StatelessWidget {
  const AppHome({super.key});

  @override
  Widget build(BuildContext context) {
    return Material(
      child: Center(
        child: TextButton(
          onPressed: () {
            debugDumpApp();
          },
          child: const Text('Dump Widget Tree'),
        ),
      ),
    );
  }
}

content_copy

This function recursively calls the toStringDeep() method starting with the root of the widget tree. It returns a "flattened" tree.

Example 4 produces the following widget tree. It includes:

All the widgets projected through their various build functions.
Many widgets that don't appear in your app's source. The framework's widgets' build functions insert them during the build.

The following tree, for example, shows _InkFeatures. That class implements part of the Material widget. It doesn't appear anywhere in the code in Example 4.

Expand to view the widget tree for Example 4

When the button changes from being pressed to being released, this invokes the debugDumpApp() function. It also coincides with the TextButton object calling setState() and thus marking itself dirty. This explains why a Flutter marks a specific object as "dirty". When you review the widget tree, look for a line that resembles the following:

└TextButton(dirty, dependencies: [MediaQuery, _InheritedTheme, _LocalizationsScope-[GlobalKey#5880d]], state: _ButtonStyleState#ab76e)

content_copy

If you write your own widgets, override the debugFillProperties() method to add information. Add DiagnosticsProperty objects to the method's argument and call the superclass method. The toString method uses this function to fill in the widget's description.

Print the render tree

When debugging a layout issue, the Widgets layer's tree might lack detail. The next level of debugging might require a render tree. To dump the render tree:

Open your source file.
Call the debugDumpRenderTree() function. You can call this any time except during a layout or paint phase. Consider calling it from a frame callback or an event handler.
If you haven't started your app, debug it using your IDE.
If you have started your app, save your source file. Hot reload re-renders your app.

Example 5: Call `debugDumpRenderTree()`

dart

import 'package:flutter/material.dart';

void main() {
  runApp(
    const MaterialApp(
      home: AppHome(),
    ),
  );
}

class AppHome extends StatelessWidget {
  const AppHome({super.key});

  @override
  Widget build(BuildContext context) {
    return Material(
      child: Center(
        child: TextButton(
          onPressed: () {
            debugDumpRenderTree();
          },
          child: const Text('Dump Render Tree'),
        ),
      ),
    );
  }
}

content_copy

When debugging layout issues, look at the size and constraints fields. The constraints flow down the tree and the sizes flow back up.

Expand to view the render tree for Example 5

In the render tree for Example 5:

The RenderView, or window size, limits all render objects up to and including RenderPositionedBox#dc1df render object to the size of the screen. This example sets the size to Size(800.0, 600.0)
The constraints property of each render object limits the size of each child. This property takes the BoxConstraints render object as a value. Starting with the RenderSemanticsAnnotations#fe6b5, the constraint equals BoxConstraints(w=800.0, h=600.0).
The Center widget created the RenderPositionedBox#dc1df render object under the RenderSemanticsAnnotations#8187b subtree.
Each child under this render object has BoxConstraints with both minimum and maximum values. For example, RenderSemanticsAnnotations#a0a4b uses BoxConstraints(0.0<=w<=800.0, 0.0<=h<=600.0).
All children of the RenderPhysicalShape#8e171 render object use BoxConstraints(BoxConstraints(56.0<=w<=800.0, 28.0<=h<=600.0)).
The child RenderPadding#8455f sets a padding value of EdgeInsets(8.0, 0.0, 8.0, 0.0). This sets a left and right padding of 8 to all subsequent children of this render object. They now have new constraints: BoxConstraints(40.0<=w<=784.0, 28.0<=h<=600.0).

This object, which the creator field tells us is probably part of the TextButton's definition, sets a minimum width of 88 pixels on its contents and a specific height of 36.0. This is the TextButton class implementing the Material Design guidelines regarding button dimensions.

RenderPositionedBox#80b8d render object loosens the constraints again to center the text within the button. The RenderParagraph#59bc2 render object picks its size based on its contents. If you follow the sizes back up the tree, you see how the size of the text influences the width of all the boxes that form the button. All parents take their child's dimensions to size themselves.

Another way to notice this is by looking at the relayoutBoundary attribute of in the descriptions of each box. This tells you how many ancestors depend on this element's size.

For example, the innermost RenderPositionedBox line has a relayoutBoundary=up13. This means that when Flutter marks the RenderConstrainedBox as dirty, it also marks box's 13 ancestors as dirty because the new dimensions might affect those ancestors.

To add information to the dump if you write your own render objects, override debugFillProperties(). Add DiagnosticsProperty objects to the method's argument then call the superclass method.

Print the layer tree

To debug a compositing issue, use debugDumpLayerTree().

Example 6: Call `debugDumpLayerTree()`

dart

import 'package:flutter/material.dart';

void main() {
  runApp(
    const MaterialApp(
      home: AppHome(),
    ),
  );
}

class AppHome extends StatelessWidget {
  const AppHome({super.key});

  @override
  Widget build(BuildContext context) {
    return Material(
      child: Center(
        child: TextButton(
          onPressed: () {
            debugDumpLayerTree();
          },
          child: const Text('Dump Layer Tree'),
        ),
      ),
    );
  }
}

content_copy

Expand to view the output of layer tree for Example 6

The RepaintBoundary widget creates:

A RenderRepaintBoundary RenderObject in the render tree as shown in the Example 5 results.

╎     └─child: RenderRepaintBoundary#f8f28
╎       │ needs compositing
╎       │ creator: RepaintBoundary ← _FocusInheritedScope ← Semantics ←
╎       │   FocusScope ← PrimaryScrollController ← _ActionsScope ← Actions
╎       │   ← Builder ← PageStorage ← Offstage ← _ModalScopeStatus ←
╎       │   UnmanagedRestorationScope ← ⋯
╎       │ parentData: <none> (can use size)
╎       │ constraints: BoxConstraints(w=800.0, h=600.0)
╎       │ layer: OffsetLayer#e73b7
╎       │ size: Size(800.0, 600.0)
╎       │ metrics: 66.7% useful (1 bad vs 2 good)
╎       │ diagnosis: insufficient data to draw conclusion (less than five
╎       │   repaints)

content_copy

A new layer in the layer tree as shown in the Example 6 results.

├─child 1: OffsetLayer#0f766
│ │ creator: RepaintBoundary ← _FocusInheritedScope ← Semantics ←
│ │   FocusScope ← PrimaryScrollController ← _ActionsScope ← Actions
│ │   ← Builder ← PageStorage ← Offstage ← _ModalScopeStatus ←
│ │   UnmanagedRestorationScope ← ⋯
│ │ engine layer: OffsetEngineLayer#1768d
│ │ handles: 2
│ │ offset: Offset(0.0, 0.0)

content_copy

This reduces how much needs to be repainted.

Print the focus tree

To debug a focus or shortcut issue, dump the focus tree using the debugDumpFocusTree() function.

The debugDumpFocusTree() method returns the focus tree for the app.

The focus tree labels nodes in the following way:

The focused node is labeled PRIMARY FOCUS.
Ancestors of the focus nodes are labeled IN FOCUS PATH.

If your app uses the Focus widget, use the debugLabel property to simplify finding its focus node in the tree.

You can also use the debugFocusChanges boolean property to enable extensive logging when the focus changes.

Example 7: Call `debugDumpFocusTree()`

dart

import 'package:flutter/material.dart';

void main() {
  runApp(
    const MaterialApp(
      home: AppHome(),
    ),
  );
}

class AppHome extends StatelessWidget {
  const AppHome({super.key});

  @override
  Widget build(BuildContext context) {
    return Material(
      child: Center(
        child: TextButton(
          onPressed: () {
            debugDumpFocusTree();
          },
          child: const Text('Dump Focus Tree'),
        ),
      ),
    );
  }
}

content_copy

Expand to view the focus tree for Example 7

Print the semantics tree

The debugDumpSemanticsTree() function prints the semantic tree for the app.

The Semantics tree is presented to the system accessibility APIs. To obtain a dump of the Semantics tree:

Enable accessibility using a system accessibility tool or the SemanticsDebugger
Use the debugDumpSemanticsTree() function.

Example 8: Call `debugDumpSemanticsTree()`

dart

import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';
import 'package:flutter/rendering.dart';

void main() {
  runApp(
    const MaterialApp(
      home: AppHome(),
    ),
  );
}

class AppHome extends StatelessWidget {
  const AppHome({super.key});

  @override
  Widget build(BuildContext context) {
    return Material(
      child: Center(
        child: Semantics(
          button: true,
          enabled: true,
          label: 'Clickable text here!',
          child: GestureDetector(
              onTap: () {
                debugDumpSemanticsTree();
                if (kDebugMode) {
                  print('Clicked!');
                }
              },
              child: const Text('Click Me!', style: TextStyle(fontSize: 56))),
        ),
      ),
    );
  }
}

content_copy

Expand to view the semantic tree for Example 8

Print event timings

If you want to find out where your events happen relative to the frame's begin and end, you can set prints to log these events. To print the beginning and end of the frames to the console, toggle the debugPrintBeginFrameBanner and the debugPrintEndFrameBanner.

The print frame banner log for Example 1

I/flutter : ▄▄▄▄▄▄▄▄ Frame 12         30s 437.086ms ▄▄▄▄▄▄▄▄
I/flutter : Debug print: Am I performing this work more than once per frame?
I/flutter : Debug print: Am I performing this work more than once per frame?
I/flutter : ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀

content_copy

To print the call stack causing the current frame to be scheduled, use the debugPrintScheduleFrameStacks flag.

Debug layout issues

To debug a layout problem using a GUI, set debugPaintSizeEnabled to true. This flag can be found in the rendering library. You can enable it at any time and affects all painting while true. Consider adding it to the top of your void main() entry point.

Example 9

See an example in the following code:

dart

// Add import to the Flutter rendering library.
import 'package:flutter/rendering.dart';

void main() {
  debugPaintSizeEnabled = true;
  runApp(const MyApp());
}

content_copy

When enabled, Flutter displays the following changes to your app:

Displays all boxes in a bright teal border.
Displays all padding as a box with a faded blue fill and blue border around the child widget.
Displays all alignment positioning with yellow arrows.
Displays all spacers in gray, when they have no child.

The debugPaintBaselinesEnabled flag does something similar but for objects with baselines. The app displays the baseline for alphabetic characters in bright green and the baseline for ideographic characters in orange. Alphabetic characters "sit" on the alphabetic baseline, but that baseline "cuts" through the bottom of CJK characters. Flutter positions the ideographic baseline at the very bottom of the text line.

The debugPaintPointersEnabled flag turns on a special mode that highlights any objects that you tap in teal. This can help you determine if an object fails to hit test. This might happen if the object falls outside the bounds of its parent and thus not considered for hit testing in the first place.

If you're trying to debug compositor layers, consider using the following flags.

Use the debugPaintLayerBordersEnabled flag to find the boundaries of each layer. This flag results in outlining each layer's bounds in orange.
Use the debugRepaintRainbowEnabled flag to display a repainted layer. Whenever a layer repaints, it overlays with a rotating set of colors.

Any function or method in the Flutter framework that starts with debug... only works in debug mode.

Debug animation issues

info提示

To debug animations with the least effort, slow them down. To slow down the animation, click Slow Animations in DevTools' Inspector view. This reduces the animation to 20% speed. If you want more control over the amount of slowness, use the following instructions.

Set the timeDilation variable (from the scheduler library) to a number greater than 1.0, for instance, 50.0. It's best to only set this once on app startup. If you change it on the fly, especially if you reduce it while animations are running, it's possible that the framework will observe time going backwards, which will probably result in asserts and generally interfere with your efforts.

Debug performance issues

info提示

You can achieve similar results to some of these debug flags using DevTools. Some of the debug flags provide little benefit. If you find a flag with functionality you would like to add to DevTools, file an issue.

Flutter provides a wide variety of top-level properties and functions to help you debug your app at various points along the development cycle. To use these features, compile your app in debug mode.

The following list highlights some of flags and one function from the rendering library for debugging performance issues.

debugDumpRenderTree()

To dump the rendering tree to the console, call this function when not in a layout or repaint phase.To set these flags either:
edit the framework code
import the module, set the value in your main() function, then hot restart.
debugPaintLayerBordersEnabled

To display the boundaries of each layer, set this property to true. When set, each layer paints a box around its boundary.
debugRepaintRainbowEnabled

To display a colored border around each widget, set this property to true. These borders change color as the app user scrolls in the app. To set this flag, add debugRepaintRainbowEnabled = true; as a top-level property in your app. If any static widgets rotate through colors after setting this flag, consider adding repaint boundaries to those areas.
debugPrintMarkNeedsLayoutStacks

To determine if your app creates more layouts than expected, set this property to true. This layout issue could happen on the timeline, on a profile, or from a print statement inside a layout method. When set, the framework outputs stack traces to the console to explain why your app marks each render object to be laid out.
debugPrintMarkNeedsPaintStacks

To determine if your app paints more layouts than expected, set this property to true.

You can generate stack traces on demand as well. To print your own stack traces, add the debugPrintStack() function to your app.

Trace Dart code performance

info提示

You can use the DevTools Timeline events tab to perform traces. You can also import and export trace files into the Timeline view, but only files generated by DevTools.

To perform custom performance traces and measure wall or CPU time of arbitrary segments of Dart code like Android does with systrace, use dart:developer Timeline utilities.

Open your source code.

Wrap the code you want to measure in Timeline methods.

dart

import 'dart:developer';

void main() {
  Timeline.startSync('interesting function');
  // iWonderHowLongThisTakes();
  Timeline.finishSync();
}

content_copy

While connected to your app, open DevTools' Timeline events tab.
Select the Dart recording option in the Performance settings.
Perform the function you want to measure.

To ensure that the runtime performance characteristics closely match that of your final product, run your app in profile mode.

Add performance overlay

info提示

You can toggle display of the performance overlay on your app using the Performance Overlay button in the Flutter inspector. If you prefer to do it in code, use the following instructions.

To enable the PerformanceOverlay widget in your code, set the showPerformanceOverlay property to true on the MaterialApp, CupertinoApp, or WidgetsApp constructor:

Example 10

dart

import 'package:flutter/material.dart';

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      showPerformanceOverlay: true,
      title: 'My Awesome App',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
      ),
      home: const MyHomePage(title: 'My Awesome App'),
    );
  }
}

content_copy

(If you're not using MaterialApp, CupertinoApp, or WidgetsApp, you can get the same effect by wrapping your application in a stack and putting a widget on your stack that was created by calling PerformanceOverlay.allEnabled().)

To learn how to interpret the graphs in the overlay, check out The performance overlay in Profiling Flutter performance.

To add an overlay to a Material Design baseline grid on your app to help verify alignments, add the debugShowMaterialGrid argument in the MaterialApp constructor.

posted on 2024-12-11 09:19 AtlasLapetos 阅读(20) 评论(0) 收藏举报

通过代码调试应用

通过输出代码的方式调试 Flutter 应用

Add logging to your application

Example 1

Example 2

Set breakpoints

Example 3

Debug app layers using flags

Print the widget tree

Example 4: Call `debugDumpApp()`

Print the render tree

Example 5: Call `debugDumpRenderTree()`

Print the layer tree

Example 6: Call `debugDumpLayerTree()`

Print the focus tree

Example 7: Call `debugDumpFocusTree()`

Print the semantics tree

Example 8: Call `debugDumpSemanticsTree()`

Print event timings

Debug layout issues

Example 9

Debug animation issues

Debug performance issues

Trace Dart code performance

Add performance overlay

Example 10

Add widget alignment grid

通过代码调试应用

通过输出代码的方式调试 Flutter 应用

Add logging to your application

Example 1

Example 2

Set breakpoints

Example 3

Debug app layers using flags

Print the widget tree

Example 4: Call debugDumpApp()

Print the render tree

Example 5: Call debugDumpRenderTree()

Print the layer tree

Example 6: Call debugDumpLayerTree()

Print the focus tree

Example 7: Call debugDumpFocusTree()

Print the semantics tree

Example 8: Call debugDumpSemanticsTree()

Print event timings

Debug layout issues

Example 9

Debug animation issues

Debug performance issues

Trace Dart code performance

Add performance overlay

Example 10

Add widget alignment grid

Example 4: Call `debugDumpApp()`

Example 5: Call `debugDumpRenderTree()`

Example 6: Call `debugDumpLayerTree()`

Example 7: Call `debugDumpFocusTree()`

Example 8: Call `debugDumpSemanticsTree()`