使用旧版 Flutter 检查器

以下是检查器工具栏中可用功能的指南。空间有限时，将使用图标代替文字标签。

Select widget mode

Enable this button in order to select a widget on the device to inspect it. To learn more, check out Inspecting a widget.

选择 widget 模式

启用此按钮以在设备上选择 widget 进行检查。了解更多请参阅 Inspecting a widget（检查 widget）。

Refresh tree

Reload the current widget info.

刷新树

重新加载当前 widget 信息。

Slow animations

Run animations 5 times slower to help fine-tune them.

Slow animations （慢速动画）

以 5 倍慢速运行动画，便于微调。

Show guidelines

Overlay guidelines to assist with fixing layout issues.

Show guidelines （显示参考线）

叠加参考线以辅助修复布局问题。

Show baselines

Show baselines, which are used for aligning text. Can be useful for checking if text is aligned.

Show baselines （显示基线）

显示用于对齐文本的基线。可用于检查文本是否对齐。

Highlight repaints

Show borders that change color when elements repaint. Useful for finding unnecessary repaints.

Highlight repaints （高亮重绘）

在元素重绘时显示变色边框。有助于发现不必要的重绘。

Highlight oversized images

Highlights images that are using too much memory by inverting colors and flipping them.

Highlight oversized images （高亮过大图片）

通过反色并翻转来高亮占用过多内存的图片。

你可以浏览交互式 widget 树，查看相邻 widget 及其字段值。

要在 widget 树中定位单个 UI 元素，请点击工具栏中的 Select Widget Mode（选择 widget 模式）按钮。这会将设备上的应用置于「widget 选择」模式。点击应用 UI 中的任意 widget；会在应用屏幕上选中该 widget，并将 widget 树滚动到对应节点。再次切换 Select Widget Mode 按钮可退出 widget 选择模式。

调试布局问题时，关键字段是 size 和 constraints。约束沿树向下传递，尺寸向上回传。更多信息请参阅 Understanding constraints（理解约束）。

Flutter 布局浏览器（Layout Explorer）帮助你更好地理解 Flutter 布局。

有关此工具功能的概览，请参阅 Flutter Explorer 视频：

Watch on YouTube in a new tab: "DevTools Layout Explorer"

你可能还会觉得以下分步文章很有用：

• How to debug layout issues with the Flutter Inspector

• How to debug layout issues with the Flutter Inspector（如何使用 Flutter 检查器调试布局问题）

在 Flutter 检查器中选择 widget。布局浏览器支持 flex layouts（flex 布局）和固定尺寸布局，并为两者提供专用工具。

当你选择 flex widget（例如 Row、Column、Flex）或 flex widget 的直接子节点时，flex 布局工具会出现在布局浏览器中。

布局浏览器可视化 Flex widget 及其子节点的布局方式。它会标识主轴与交叉轴，以及当前对齐方式（例如 start、end、spaceBetween）。还会显示 flex 因子、flex fit 和布局约束等细节。

此外，浏览器会显示布局约束违规和渲染溢出错误。违规的布局约束标为红色，溢出错误以运行设备上常见的标准「黄黑警示条」图案呈现。这些可视化旨在帮助你理解溢出错误的原因及修复方法。

在布局浏览器中点击 widget 会同步设备上检查器的选中项。需要启用 Select Widget Mode（选择 widget 模式）。请点击检查器中的 Select Widget Mode 按钮以启用。

对于 flex 因子、flex fit 和对齐等部分属性，可通过浏览器中的下拉列表修改值。修改 widget 属性时，新值不仅反映在布局浏览器中，也反映在运行 Flutter 应用的设备上。属性变更时浏览器会播放动画，使效果更清晰。从布局浏览器所做的 widget 属性更改不会修改源码，热重载后会还原。

布局浏览器支持修改 mainAxisAlignment、crossAxisAlignment 和 FlexParentData.flex。未来可能增加对 mainAxisSize、textDirection 和 FlexParentData.fit 等属性的支持。

mainAxisAlignment（主轴对齐）

支持的值：

• MainAxisAlignment.start
• MainAxisAlignment.end
• MainAxisAlignment.center
• MainAxisAlignment.spaceBetween
• MainAxisAlignment.spaceAround
• MainAxisAlignment.spaceEvenly

crossAxisAlignment（交叉轴对齐）

支持的值：

• CrossAxisAlignment.start
• CrossAxisAlignment.center
• CrossAxisAlignment.end
• CrossAxisAlignment.stretch

FlexParentData.flex

FlexParentData.flex

布局浏览器在 UI 中提供 7 个 flex 选项（null、0、1、2、3、4、5），但技术上 flex widget 子节点的 flex 因子可以是任意 int。

Flexible.fit

Flexible.fit

布局浏览器支持 FlexFit 的两种类型：loose 和 tight。

当你选择的固定尺寸 widget 不是 flex widget 的子节点时，布局浏览器会显示固定尺寸布局信息。你可以查看所选 widget 及其最近上游 RenderObject 的尺寸、约束和内边距信息。

Flutter 检查器提供多种可视化调试应用的选项。

启用后，动画将以 5 倍慢速运行，便于视觉检查。若需仔细观察并微调看起来不太对的动画，这会很有用。

也可以在代码中设置：

import 'package:flutter/scheduler.dart';
​
void setSlowAnimations() {
  timeDilation = 5.0;
}

这会将动画减慢 5 倍。

以下链接提供更多信息。

• Flutter documentation: timeDilation property

• Flutter documentation: timeDilation property（Flutter 文档：timeDilation 属性）

以下录屏展示减慢动画前后的效果。

此功能在应用上绘制参考线，显示 render box、对齐、内边距、滚动视图、裁剪和 spacer。

此工具有助于理解布局，例如发现多余内边距或理解 widget 对齐。

也可以在代码中启用：

import 'package:flutter/rendering.dart';
​
void showLayoutGuidelines() {
  debugPaintSizeEnabled = true;
}

绘制到屏幕的 widget 会创建 render box，即 Flutter 布局的基本构建块。它们以亮蓝色边框显示：

对齐以黄色箭头显示，表示 widget 相对于父级的垂直与水平偏移。例如，此按钮图标由四支箭头显示为居中：

内边距以半透明蓝色背景显示：

具有滚动内容的 widget（如列表视图）以绿色箭头显示：

裁剪（例如使用 ClipRect widget 时）以带剪刀图标的粉色虚线显示：

Spacer widget 以灰色背景显示，例如没有子节点的 SizedBox：

此选项使所有基线可见。基线是用于定位文本的水平线。

可用于检查文本是否精确垂直对齐。例如，以下截图中的文本基线略有错位：

可使用 Baseline widget 调整基线。

任何设置了基线的 render box 都会绘制线条；字母基线为绿色，表意基线为黄色。

也可以在代码中启用：

import 'package:flutter/rendering.dart';
​
void showBaselines() {
  debugPaintBaselinesEnabled = true;
}

此选项为所有 render boxes 绘制边框，每次重绘时边框颜色都会变化。

这种旋转的彩虹色有助于找出应用中重绘过于频繁、可能影响性能的部分。

例如，一个小动画可能导致整页在每一帧都重绘。将动画包裹在 RepaintBoundary widget 中可将重绘限制在动画区域。

此处进度指示器导致其容器重绘：

class EverythingRepaintsPage extends StatelessWidget {
  const EverythingRepaintsPage({super.key});
​
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Repaint Example')),
      body: const Center(child: CircularProgressIndicator()),
    );
  }
}

将进度指示器包裹在 RepaintBoundary 中后，仅屏幕该区域会重绘：

class AreaRepaintsPage extends StatelessWidget {
  const AreaRepaintsPage({super.key});
​
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Repaint Example')),
      body: const Center(
        child: RepaintBoundary(child: CircularProgressIndicator()),
      ),
    );
  }
}

RepaintBoundary widget 有取舍：有助于性能，但创建新 canvas 也有开销，会占用额外内存。

也可以在代码中启用此选项：

import 'package:flutter/rendering.dart';
​
void highlightRepaints() {
  debugRepaintRainbowEnabled = true;
}

此选项通过反色并垂直翻转来高亮过大的图片：

被高亮的图片占用的内存超过所需；例如 5MB 大图以 100×100 像素显示。

此类图片可能导致性能不佳，尤其在低端设备上；列表视图中图片很多时，性能影响会累积。每张图片的信息会打印在调试控制台中：

dash.png has a display size of 213×392 but a decode size of 2130×392, which uses an additional 2542KB.

若图片比所需多占用至少 128KB，则视为过大。

尽可能缩小图片资源文件是修复此问题的最佳方式。

若无法做到，可在 Image 构造函数上使用 cacheHeight 和 cacheWidth 参数：

class ResizedImage extends StatelessWidget {
  const ResizedImage({super.key});
​
  @override
  Widget build(BuildContext context) {
    return Image.asset('dash.png', cacheHeight: 213, cacheWidth: 392);
  }
}

这会使引擎按指定尺寸解码图片并减少内存占用（解码与存储仍比直接缩小资源更耗资源）。无论这些参数如何，图片仍按布局约束或宽高渲染。

此属性也可在代码中设置：

void showOversizedImages() {
  debugInvertOversizedImages = true;
}

可在以下链接了解更多：

• Flutter documentation: debugInvertOversizedImages

• Flutter documentation: debugInvertOversizedImages（Flutter 文档：debugInvertOversizedImages）

选择 Widget Details Tree（Widget 详情树）标签页可显示所选 widget 的详情树。在此可收集 widget 属性、render object 和子节点等有用信息。

Flutter 检查器的部分功能基于对应用代码插桩，以更好理解 widget 的创建源码位置。源码插桩使检查器能以接近源码中 UI 定义的方式呈现 widget 树。若无此功能，widget 树中的节点层级更深，更难理解运行时 widget 层级与应用 UI 的对应关系。

可向 flutter run 命令传入 --no-track-widget-creation 禁用此功能。

以下是启用与禁用跟踪 widget 创建时 widget 树的可能外观示例。

启用跟踪 widget 创建（默认）：

禁用跟踪 widget 创建（不推荐）：

此功能会阻止原本相同的 const Widget 在调试构建中被视为相等。更多细节请参阅 common problems when debugging（调试时的常见问题）讨论。

将指针悬停在任意 widget 上会显示其属性与值。

切换此值可启用或禁用悬停检查功能。

默认情况下，DevTools 将 widget 树中显示的 widget 限制为项目根目录和 Flutter 中的 widget。此筛选仅适用于检查器 Widget 树（检查器左侧）——不适用于与布局浏览器同标签页中检查器右侧的 Widget 详情树。在 Widget 详情树中，你可以看到所有包中树上的全部 widget。

要显示其他 widget，必须将其父目录添加到包目录（Package Directories）。

例如，考虑以下目录结构：

project_foo
  pkgs
    project_foo_app
    widgets_A
    widgets_B

从 project_foo_app 运行应用时，widget 检查器树中仅显示 project_foo/pkgs/project_foo_app 中的 widget。

要在 widget 树中显示 widgets_A 的 widget，请将 project_foo/pkgs/widgets_A 添加到包目录。

要在 widget 树中显示项目根目录的 全部 widget，请将 project_foo 添加到包目录。

对包目录的更改会在下次为该应用打开 widget 检查器时保留。

有关检查器一般能力的演示，请参阅展示 IntelliJ 版 Flutter 检查器的 DartConf 2018 talk。

要了解如何使用 DevTools 可视化调试布局问题，请参阅引导式 Flutter Inspector tutorial（Flutter 检查器教程）。