Flutter 3.38 版本有哪些新功能

flutter 3.38

引言

欢迎回到我们定期发布的季度更新：Flutter 3.38。本次更新专注于提升您的开发效率并优化开发者体验，带来了点语法简写和 Widget 预览的改进。感谢社区的贡献，本次发布共包含来自 145 位独立贡献者的 825 次提交，其中有 37 位是首次贡献者。让我们深入了解一下本次发布的内容。

What’s new in Flutter 3.38

点符号简写

编写更简洁的 Dart 代码！我们很高兴推出一项新的 Dart 功能—— 点简写（dot shorthands）！该功能通过允许省略 Dart 可推断的类型，减少模板代码。

例如，你可以使用简写形式，用 .start 代替 MainAxisAlignment.start。

// With shorthands
Column(
  mainAxisAlignment: .start,
  crossAxisAlignment: .center,
  children: [ /* ... */ ],
),

// Without shorthands
Column(
  mainAxisAlignment: MainAxisAlignment.start,
  crossAxisAlignment: CrossAxisAlignment.center,
  children: [ /* … */ ],
),

这也适用于命名构造函数！你可以写 .all 代替 EdgeInsets.all：

Padding(
  padding: .all(8.0),
  child: Text('Hello world'),
),

此功能在 Dart 3.10 和 Flutter 3.38 中默认启用。更多信息请查看 dart.dev 上的点简写页面。您还可以在 Dart 3.10 发布博客文章中了解此功能及其他新特性（例如 Dart hooks！）。

Web

Web 开发配置文件

flutter run 命令现在支持用于 Web 设置的配置文件。你可以在项目根目录下的 web_dev_config.yaml 文件中指定主机、端口、证书和头部信息。将该文件提交到版本控制，以便团队中的每个人都能使用相同的设置进行调试。更多信息，请访问设置 Web 开发配置文件。

Web 开发代理设置

除了现有的命令行标志外，Web 开发配置文件还支持新的代理设置。代理设置可以将发送到已配置路径的请求转发到另一台服务器，从而更轻松地开发连接到同一主机上动态端点的 Web 客户端。

有关代理设置的详细信息也请参见设置 Web 开发配置文件。

对 Web 平台的热重载支持进一步扩展

使用 -d web-server 运行并在浏览器中打开 Flutter 应用链接时，有状态的热重载现在默认启用。即使同时连接多个浏览器也能正常工作。

与 -d chrome 一样，此功能可使用 --no-web-experimental-hot-reload 标志临时禁用。该功能的禁用选项将在未来的版本中移除，因此，如果在开发工作流中遇到问题，请使用 Dart 的 Web 热重载问题模板提交 bug。更多信息请参见 Web 上热重载文档。

框架

本次发布在框架范围内引入了多项强大的新功能和改进，使开发者能够更精细地控制高级 UI、导航以及平台交互。

开发者在创建弹窗、对话框和其他浮动 UI 元素时，现在可以使用 OverlayPortal 获得更强的控制能力。通过 OverlayPortal.overlayChildLayoutBuilder （#174239），现在可以在 widget 树中向上任意一个 Overlay 中渲染子元素，从而更轻松地显示全应用范围的通知或其他需要突破父级 widget 布局限制的 UI。底层的 Overlay.of 方法也变得更加健壮和高效（#174315）。

为了实现更现代的 Android 导航体验，现在默认在 MaterialApp 中启用了预测性返回路由过渡（#173860）。当用户执行返回手势时，当前路由动画退出的同时，他们会看到主屏幕的预览效果。此外，默认页面过渡已从 ZoomPageTransitionsBuilder 更新为 FadeForwardsPageTransitionsBuilder ，以匹配原生行为。

此版本还加深了对桌面端的集成。在 Windows 上，开发者现在可以获取已连接显示器的列表，并查询每个显示器的详细属性，例如分辨率、刷新率和物理尺寸（#164460）。这使得开发者能够创建具备复杂窗口管理功能的应用程序。

最后，框架本身现在更加稳健。在组件生命周期回调（例如 didUpdateWidget）中发生的错误现在能够被更优雅地处理，防止其在元素树中引发连锁故障（#173148）。ResizeImage 现在正确实现了相等性判断，确保相同的 ResizeImage 提供者被视为同一对象，从而使图像缓存和比较更加可预测（#172643）。

在 Web 上，UI 优化仍在继续：修复了当圆角半径大于控件本身时会导致渲染错误的 RSuperellipse 问题（#172254），此类情况现在将被正确处理，生成预期的胶囊形状。

对于国际用户，检测浏览器首选语言环境现在更加可靠。引擎现在使用标准的 Intl.Locale Web API 来解析浏览器语言，取代了之前手动实现且较为脆弱的方法（#172964）。这一更改使得语言环境检测更加可靠，为全球用户带来更好的体验。

已解决一个特定于 Android 的 Bug（#171973），该问题主要影响带硬件键盘的三星设备。此前，用户与 TextField 交互后，Android 输入法编辑器（IME）可能会卡在过时状态，导致 IME 错误地拦截“回车”或“空格”键的按键事件，从而使 Checkbox 或 Radio 按钮等非文本控件无法接收到该事件。此问题的修复确保在文本连接关闭时正确重置 InputMethodManager，清除 IME 的过时状态，恢复用户对硬件键盘操作的预期行为。

Material 和 Cupertino 更新

Material 和 Cupertino 库在持续演进中，重点关注 API 的一致性以及更精致的用户体验。本次发布带来了一次重要的 API 迁移、新的组件功能，以及大量改进，让构建美观且功能完善的用户界面变得更加简单直接。

在弃用 MaterialState 的基础上，本次发布继续推进内部向更统一的 WidgetState 迁移。这为定义组件在不同交互状态（如按下、悬停或禁用）下的外观提供了统一且富有表现力的方式，且无需对现有应用进行任何更改。此次迁移已应用于多种组件及其主题，包括 IconButton、ElevatedButton、Checkbox 和 Switch（#173893）。新的 API 还带来了更强的功能与灵活性；例如，IconButton 现在新增了 statesController 属性（#169821），允许以编程方式控制其视觉状态，从而实现更丰富的自定义和交互式设计。

此版本还引入了多项新功能和便捷的 API。Badge.count 构造函数现在包含一个 maxCount 参数（#171054），可轻松限制显示的数量（例如，显示“99+”而不是“100”）。

为了实现更精细的手势控制，InkWell 小部件现在新增了 onLongPressUp 回调（#173221），可用于触发仅在用户抬起手指时才完成的操作。

Cupertino 库也在持续提升其对 iOS 原生体验的还原度。isMomentary 属性（#164262）的加入使得控件可以触发操作而不保留选中状态。为了更贴近原生 iOS 行为，当 CupertinoSheet 完全展开并向上拖动时，现在会呈现轻微的“拉伸”效果（#168547）。

最后，此版本包含了许多对核心组件行为的优化改进。主要亮点包括修复了 DropdownMenuFormField 在表单重置时无法正确清空文本字段的问题（#174937），以及对 SegmentedButton 的更新，以改善焦点处理（#173953）并确保其边框能正确反映组件的状态（#172754）。

分离 Material 和 Cupertino

我们一直在为将 Material 和 Cupertino 库与框架解耦进行大量规划。以下列表包含了一些关于近期发布的设计文档的讨论。

改进 flutter/packages 的发布流程，解耦后将包含 Material 和 Cupertino。

颜色和点符号的简写

状态：已确定
Flutter 基础颜色集（公开共享）

解耦测试

状态：进行中
解耦框架测试（公开共享）
https://github.com/flutter/flutter/issues/177028

文本

状态：讨论中
Flutter 解耦设计与文本（公开共享）

滚动：更强大且可预测的 Sliver

此版本带来了多项修复，使得构建复杂的滚动布局（尤其是使用 SliverMainAxisGroup 和 SliverCrossAxisGroup 的布局）更加稳定和可预测。

使用这些组件来组合多个可滚动组件（slivers）的开发者会发现，手势处理现在更加可靠。针对这些组内可滚动组件的点击和其他指针事件的命中测试现在能够正确计算，确保用户交互按预期工作（#174265）。

其他一些修复改进了 SliverMainAxisGroup 内部滚动行为的准确性。使用固定头部时的过度滚动问题已解决（#173349），调用 showOnScreen 显示 sliver 现在可正常工作（#171339），且内部滚动偏移量计算更加精确（#174369）。

对于构建自定义滚动视图的开发者而言，新的 SliverGrid.list 构造函数（#173925）提供了一种更简洁的方式来从简单的子项列表创建网格。

此版本还改进了复杂布局中键盘和方向键用户的方向导航。在具有不同滚动轴的嵌套滚动视图中（例如垂直列表包含水平轮播），方向性焦点导航现在更加可预测，可防止焦点在不同部分之间意外跳转（#172875）。

无障碍功能：为所有用户带来更具包容性的体验

让所有用户都能无障碍使用应用程序是 Flutter 框架的核心原则之一。本次发布延续了这一承诺，为开发者提供了更多的程序化控制能力，改善了国际用户使用体验，并进一步优化了核心组件的可访问性。

对于构建复杂应用的开发者，此版本引入了通过使用 WidgetsFlutterBinding.instance.ensureSemantics （#174163）在 iOS 上默认启用辅助功能的功能。现在调试辅助功能问题更加方便，因为 debugDumpSemanticsTree 增加了文本输入验证结果信息，有助于更快地诊断问题（#174677）。

对于基于 Sliver 的滚动视图中的高级无障碍功能，现在可以使用新的 SliverSemantics 组件（#167300）。与现有的 Semantics 组件类似，开发者可以在 CustomScrollView 中使用 SliverSemantics，为 Sliver 树的某些部分添加特定的语义信息。这对于标注页眉、分配语义角色以及为 Sliver 添加供屏幕阅读器使用的描述性标签特别有用，从而为用户提供更清晰且更具可访问性的体验。

最后，核心组件的可访问性持续得到优化。CupertinoExpansionTile 现在默认支持可访问性（#174480），而 AutoComplete 组件现在会向用户播报搜索结果的状态（#173480）。其他改进，例如 TimePicker 中更大的触摸目标区域（#170060），进一步提升了开箱即用的可访问性体验。

iOS

我们很高兴确认，Flutter 完全支持苹果于 9 月发布的最新平台版本：iOS 26、Xcode 26 和 macOS 26。这确保您可以立即开始在苹果最新的操作系统和工具上开发和测试您的应用。

你可能已经注意到，在上一个 Flutter 版本中，针对 iOS 开发者的使用体验有了显著提升，解决了一个长期存在的用户痛点：过去在使用 flutter run 在物理设备上运行 Flutter 应用时，必须自动启动 Xcode 应用程序。我们引入了一种新的部署方式，通过 Xcode 26 的命令行工具 devicectl 来实现应用的安装、启动和调试。这一转变消除了部署过程中调用 Xcode 应用程序的需求，在大多数情况下仅依赖命令行形式的 Xcode 构建工具即可完成。如果你遇到问题，可以通过 flutter config --no-enable-lldb-debugging 禁用此部署方法，并请提交 issue 告知我们！

此前，此功能依赖于 Xcode 自动化，在 Xcode 26 上变得不稳定且容易出错，尤其是在连续执行命令时。如果您现在正在为最新的 Apple 版本进行开发，我们强烈建议将 Flutter 版本更新至 3.38 或更高版本。

UIScene 生命周期迁移

Flutter 3.38 包含了对苹果强制要求的 UIScene 生命周期的关键支持。这是在苹果于 WWDC25 上宣布“在 iOS 26 之后的版本中，任何使用最新 SDK 构建的 UIKit 应用都必须使用 UIScene 生命周期，否则将无法启动”后，一项至关重要的前瞻性更新。

为了确保您的 iOS Flutter 应用在未来的 iOS 版本中保持兼容并能成功启动，需要进行迁移。

迁移 Flutter 应用程序

所有现有的 iOS Flutter 应用必须迁移到新的生命周期。你可以通过以下两种途径完成此迁移：

手动迁移：请遵循 Flutter 官网提供的手动迁移说明。
自动迁移（实验性）：启用实验性功能以自动处理迁移。此功能将在未来的版本中默认启用。运行以下命令：

flutter config --enable-uiscene-migration

迁移 Flutter 插件

依赖应用程序生命周期事件的 Flutter 插件必须更新为使用 UIScene 生命周期事件。插件开发者应参考迁移指南。未完成迁移的插件将在未来的版本中显示警告。

迁移嵌入式 Flutter（可选）

对于在原生宿主应用中嵌入 Flutter 的项目，迁移是可选的，但强烈推荐。通过使用添加到应用迁移指南采用 Flutter 新的 UIScene API，可以为插件启用场景生命周期事件，确保与 Flutter 生态系统的兼容性

Android

16KB 页大小兼容性

升级到 Flutter 3.38 是为 Google Play 的 16 KB 页面大小兼容性要求做出的关键准备。从 2025 年 11 月 1 日起，面向 Android 15 及更高版本的应用必须支持 16 KB 页面。此项变更可确保您的应用在高内存设备上正确运行，并带来最高达 30% 更快启动速度等性能优势。Flutter 3.38 将默认的 Android ndkVersion 更新至 NDK r28，这是原生代码实现 16 KB 支持所需对齐的最低版本。

内存修复

Flutter 3.38 修复了影响所有 Android 平台上 Flutter 应用的一个重大内存泄漏问题。该问题自 3.29.0 版本引入，当 Activity 因开发者设置配置而被销毁，或因系统内存不足被系统终止时会发生。

Android 依赖更新

通常很难确定适用于应用程序的 Android 依赖项版本组合，包括 Gradle、Android Gradle 插件（AGP）、Kotlin Gradle 插件（KGP）、Java 等。对于 Flutter 3.38 版本，我们在持续集成（CI）环境中测试并确认了以下 Android 依赖项版本的兼容性：

Java 17：Flutter 3.38 中进行 Android 开发所需的最低版本。
KGP 2.2.20：工具支持的最高已知且受支持的 Kotlin Gradle Plugin 版本。
AGP 8.11.1：与 KGP 2.2.20 兼容的最新 Android Gradle 插件版本兼容。
Gradle 8.14：此版本与所选的 Java、KGP 和 AGP 版本兼容。请注意，Gradle 8.13 是 AGP 8.11.1 所需的最低版本。

为确保您的应用在 Flutter 版本发布时能够无缝衔接，我们强烈建议您在构建文件中使用 Flutter SDK 提供的 API 级别变量。本版本的配置值如下：

flutter.compileSdkVersion（API 36）
flutter.targetSdkVersion（API 36）
flutter.minSdkVersion（API 24）或更高版本

引擎

性能叠加层

性能叠加层已重构，效率更高，在 Skia 和 Impeller 后端上的渲染时间均有所减少。这意味着您能以更低的开销获得更准确的性能数据。（#176364）

Vulkan 和 OpenGL ES

对 Vulkan 和 OpenGL ES 后端的大量修复和改进，提升了更广泛设备上的稳定性和性能。包括更好地处理管线缓存（#176322）、栅栏等待器（#173085）以及图像布局转换（#173884）。

渲染器统一

CanvasKit 和 Skwasm 渲染器的统一工作仍在持续推进。本次发布包含了对两者之间共享代码的重大重构，这将带来更一致的体验，并加快未来的开发速度（#174588）。

线程合并

iOS 和 Android 上取消线程合并的功能已被移除。更多信息，请查看优秀的线程合并视频。

DevTools 和 IDE

实验性小部件预览 — 更新

Flutter 3.35 引入了 Widget 预览功能，这是一项实验性功能，已准备好接收社区的早期反馈。Flutter 3.38 版本对 Widget 预览功能带来了显著改进，包括：

IDE 集成 ：我们的 VSCode 和 Intellij / Android Studio 插件均已更新，初步支持 Widget 预览功能。你现在可以直接在 IDE 中查看预览，获得更流畅的开发体验。

IDE 集成

嵌入在 VSCode 中的小部件预览。

在 IDE 中使用时，小部件预览环境默认会根据当前选中的源文件来过滤显示的预览

小部件预览环境的主题和控件改进 ：小部件预览环境现在支持浅色和深色模式，以及自定义 IDE 颜色方案，以匹配您的开发环境。预览环境内的控件也经过调整，占用更少空间，从而为渲染预览留出更多可用区域。

小部件预览环境的主题和控件改进

Widget 预览环境中支持自定义主题。

预览扩展性 ：Preview 注解类不再标记为 final，现在可以继承以创建自定义的 Preview 注解，从而减少常见预览类型的样板代码。

预览扩展性

一个自定义 *BrightnessPreview* 注解的示例。

MultiPreview 支持 ：新的 MultiPreview 基类允许通过单个自定义注解创建多个 Preview 变体。

MultiPreview 支持

预览组 ：Preview 类中新增的 group 参数可用于将相关预览进行分组。

预览组

预览组中多个“亮度”预览的示例。

放宽了对 @Preview 注解参数的限制 ：现在支持将私有常量作为 Preview 注解的参数。函数参数（例如 wrapper 和 theme）仍要求具有公共的、静态可访问的名称。

Widget 预览目前仍是一项实验性功能，您的反馈对于塑造其未来发展至关重要。API 和用户体验尚未稳定，我们将根据您的反馈持续进行调整和变更。

根据早期反馈，计划进行更多改进以提升小部件预览体验，包括：

Flutter DevTools 小部件检查器支持 ：小部件检查器正在更新，以支持在小部件预览环境中检查预览。我们计划将检查器直接嵌入到小部件预览器中，使其无论在何种开发环境中都易于访问。
IDE 中的多项目支持 ：目前小部件预览器仅支持显示单个项目或 Pub 工作区内的预览。我们正在积极研究支持包含多个 Flutter 项目的 IDE 会话的方案（issue #173550）。
启动性能改进 ：正在研究性能改进的机会，以减少初始启动时间，包括：

首次运行后启动预编译小部件预览环境
并行化预览检测逻辑以更好地处理大型项目

要开始使用，请查看文档并告诉我们你的想法！

阅读文档 ：Flutter Widget 预览（实验性）入门
提供反馈 ：在 Flutter GitHub 仓库中提交问题和功能请求。
了解更多 ：如需深入技术细节，请参阅 Flutter Widget 预览架构文档。

重要提示* ：已知存在一个问题，在执行 *flutter pub get* 后，Widget 预览器可能会崩溃或停止更新。如果你遇到此问题，请在项目中运行 flutter pub get 并重启你的 IDE。更多详情请参见 #178317。*

DevTools 更新

Flutter 3.38 包含了针对 2025 年 DevTools 用户调查中用户指出的一些主要痛点的修复，包括：

网络面板改进

更方便地了解面板何时正在记录网络流量。(#9495)
修复了与复制粘贴网络请求相关的若干问题。（#9472，#9482，#9485，#8588）

Flutter 检查器修复

修复了选择小部件时有时会打开底层框架源代码而非用户源代码的 Bug。（#176530）
修复了一个偶尔导致无法与检查器面板顶部按钮交互的 bug。（#9327）

弃用和破坏性变更

本次发布包含多项重要的弃用和破坏性变更，这是持续现代化和改进 Flutter 框架工作的一部分。

一些关键的构建和工具变更可能会影响自定义构建脚本。Flutter SDK 根目录下的 version 文件已被移除，取而代之的是位于 bin/cache 目录中的新文件 flutter.version.json（#172793）。此外，默认情况下不再生成 AssetManifest.json 文件（#172594）。

其他值得注意的更改包括：

为了获得更可预测的行为，包含操作的 SnackBar 将不再自动关闭（#173084）。
OverlayPortal.targetsRootOverlay 构造函数已弃用，推荐使用更灵活的 OverlayPortal( overlayLocation: OverlayChildLocation.rootOverlay )。
CupertinoDynamicColor 上的多个属性（如 withAlpha 和 withOpacity）现已弃用，推荐使用标准的 Color 方法（#171160）。
Flutter 3.38 要求 Android 的最低 Java 版本为 Java 17，与 Gradle 8.14（2025 年 7 月发布版本）的最低要求保持一致。

有关这些及其他变更的更多详细信息和迁移指南，请查看重大变更页面。

结尾

Flutter 3.38 致力于让您的日常开发更快、更愉快。这些改进旨在简化您的构建方式。我们非常感谢每一位为本次发布贡献了辛勤工作和反馈意见的社区成员。

有关所有变更的完整列表，请务必查看详细的破坏性变更和发行说明。要免费提升您的开发效率，只需运行 flutter upgrade！

感谢阅读本文

如果有什么建议，请在评论中让我知道。我很乐意改进。

猫哥 APP

flutter 学习路径

end