Flutter 3.38 最近发布了,带来了很多新功能和改进。这次发布包含了来自 145 位 独立贡献者的 825 次 总提交,其中有 37 位 是首次贡献者。让我们深入了解一下这次发布的内容。
Dot shorthands
在 Dart 3.10 + Flutter 3.38 中开始默认支持 Dot shorthands ,通过 Dot shorthands 可以使可以通过允许您省略 Dart 能够推断出来的类型,从而减少样板代码,例如使用 .start 而不是 MainAxisAlignment.start :
dart
// With shorthands
Column(
mainAxisAlignment: .start,
crossAxisAlignment: .center,
children: [ /* ... */ ],
),
// Without shorthands
Column(
mainAxisAlignment: MainAxisAlignment.start,
crossAxisAlignment: CrossAxisAlignment.center,
children: [ /* ... */ ],
),
这对于命名构造函数 也同样适用,如.all而不是EdgeInsets.all:
dart
Padding(
padding: .all(8.0),
child: Text('Hello world'),
),
💻 Web 开发配置与功能增强
Web 开发配置文件
flutter run 命令现在支持一个用于 Web 设置的配置文件 。您可以在项目根目录下的 web_dev_config.yaml 文件中指定 主机 (host)、端口 (port)、证书 (certificate) 和 请求头信息 (header)。将此文件提交到版本控制,确保团队中的所有成员都使用相同的设置进行调试。
yaml
server:
host: "0.0.0.0" # Defines the binding address <string>
port: 8080 # Specifies the port <int> for the development server
https:
cert-path: "/path/to/cert.pem" # Path <string> to your TLS certificate
cert-key-path: "/path/to/key.pem" # Path <string> to TLS certificate key
- 更多信息,请参阅设置 Web 开发配置文件。
Web 开发代理设置
除了现有的命令行标志外,Web 开发配置文件现在还支持新的代理设置 (proxy settings)。
- 代理设置允许将特定路径的请求转发到另一个服务器。这使得开发连接到同一主机上动态端点的 Web 客户端更加容易。
dart
server:
proxy:
- target: "http://localhost:5000/" # Base URL <string> of your backend
prefix: "/users/" # Path <string>
- target: "http://localhost:3000/"
prefix: "/data/"
replace: "/report/" # Replacement <string> of path in redirected URL (optional)
- target: "http://localhost:4000/"
prefix: "/products/"
replace: ""
- 有关代理设置的详细信息,也请参阅设置 Web 开发配置文件。
Web 上的热重载扩展支持
- 当使用
-d web-server运行并在浏览器中打开 Flutter 应用链接时,有状态热重载 (Stateful hot reload) 现在默认启用。这甚至可以同时连接多个浏览器。 - 与
-d chrome一样,此功能可以使用--no-web-experimental-hot-reload标志临时禁用。但此禁用功能将在未来版本中移除,因此,如果您在开发工作流程中遇到问题,请使用 Dart 的 web 热重载问题模板 提交 Bug。 - 更多信息,请参阅Web 上的热重载文档。
🏗️ Framework更新
本次发布包含了Framework中的许多强大的新功能和改进,使开发者能够对高级 UI、导航和平台交互有更精细的控制。
强大的 UI 浮层控制
开发者在使用 OverlayPortal 创建弹出窗口、对话框和其他浮动 UI 元素时,现在拥有更大的能力。
- 通过
OverlayPortal.overlayChildLayoutBuilder(#174239),现在可以在 Widget 树中任何向上的Overlay中渲染子 Widget,这使得显示应用范围的通知或需要跳出其父 Widget 布局限制的 UI 变得更容易。这可以更灵活地显示弹出、对话框、通知等 UI ,例如:
dart
class _OverlayPortalExampleState extends State<OverlayPortalExample> {
final OverlayPortalController _controller = OverlayPortalController();
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: Text('OverlayPortal')),
body: Center(
child: OverlayPortal.overlayChildLayoutBuilder(
controller: _controller,
/// ****可以配置 root****
overlayLocation: OverlayChildLocation.rootOverlay,
child: ElevatedButton(
onPressed: () => _controller.toggle(),
child: const Text('点我显示浮层'),
),
overlayChildBuilder: (context, info) {
return Material(
elevation: 6,
color: Colors.white,
shape: RoundedRectangleBorder(
borderRadius: BorderRadius.circular(8),
),
child: Container(
padding: const EdgeInsets.all(16),
child: const Text('这是一个浮层'),
),
);
},
),
),
);
}
}
- 底层方法
Overlay.of也得到了增强,使其更加健壮和高效 (#174315)。
现代化 Android 导航体验
- 为了提供更现代的 Android 导航体验,预测性返回手势路由过渡 (predictive back route transitions) 现在在
MaterialApp中默认启用 (#173860)。当用户执行返回手势时,他们会看到主屏幕的预览,当前路由则随之动画移出。 - 此外,默认的页面过渡效果已从 ZoomPageTransitionsBuilder 更新为 FadeForwardsPageTransitionsBuilder,以反映原生的行为。
桌面集成深化
- 在 Windows 上,开发者现在可以访问已连接显示器的列表,并查询每个显示器的详细属性,例如分辨率、刷新率和物理尺寸 (#164460)。这使得创建具有复杂窗口管理功能的应用程序成为可能。
框架稳定性与 Web UI 优化
- 框架本身现在更具弹性。Widget 生命周期回调(例如
didUpdateWidget)中发生的错误现在得到更优雅的处理,防止它们在元素树中引发连锁故障 (#173148)。 ResizeImage现在正确地实现了相等性 (equality),确保相同的ResizeImage提供者被视为相同,从而使图像缓存和比较更具可预测性 (#172643)。- 在 Web 上,UI 优化仍在继续:
RSuperellipse的一个 Bug 已修复,防止角半径大于 Widget 本身时出现渲染错误;在这种情况下,它将按预期被处理以生成药丸形状 (pill shape) (#172254)。
国际化支持增强
- 检测浏览器首选区域设置 (locale) 的功能现在更可靠。引擎现在使用标准的
Intl.LocaleWeb API 来解析浏览器语言,取代了先前手动且更脆弱的实现 (#172964)。这一变化为全球用户带来了更可靠的区域设置检测和更好的体验。
Android 特定 Bug 修复
- 一个主要影响带有硬件键盘的 Samsung 设备 的 Android 特定 Bug (#171973) 已解决。
- 此前,用户与
TextField交互后,Android 输入法编辑器 (IME) 可能会陷入陈旧状态。这导致 IME 错误地拦截 "Enter" 或 "Space" 键,阻止非文本 Widget(如Checkbox或Radio按钮)接收事件。 - 修复确保在文本连接关闭时,
InputMethodManager正确重置,清除 IME 的陈旧状态,并恢复用户可预测的硬件键盘交互。
- 此前,用户与
🎨 Material 和 Cupertino 更新
Material 和 Cupertino 库持续发展,侧重于 API 一致性和优化的用户体验。本次发布带来了重大的 API 迁移、新的 Widget 功能和众多改进,使构建美观、实用的 UI 更加简单。
WidgetState 迁移
- 在弃用
MaterialState的基础上,本次发布继续向更统一的WidgetState进行内部迁移。 - 这提供了一种一致、富有表现力的方式来定义 Widget 在不同交互状态(例如:按下、悬停或禁用)下的外观,对现有应用程序无需更改。
- 此迁移已应用于各种 Widget 及其主题,包括
IconButton、ElevatedButton、Checkbox和Switch(#173893)。 - 新的 API 还增加了功能和灵活性;例如,
IconButton现在包含一个statesController属性 (#169821),允许通过编程方式控制其视觉状态,为更自定义和交互式的设计打开了大门。
新功能和便捷 API
Badge.count构造函数现在包含一个maxCount参数 (#171054),可以轻松限制显示计数(例如,显示 "99+" 而不是 "100")。

👆 手势控制与平台优化
Material 和 Cupertino 组件改进
- 为了更精细的手势控制 ,
InkWellWidget 现在新增了一个onLongPressUp回调 (#173221),这对于触发仅在用户抬起手指时才完成的动作非常有用。 - Cupertino 库 继续致力于提高 iOS 的保真度:
- 核心组件的行为也得到了完善:
🔗 Material 与 Cupertino 解耦(Decoupling)规划
我们一直在规划将 Material 和 Cupertino 库从框架中解耦。以下是关于最近发布的设计文档的一些讨论:
| 主题 | 状态 | 详情 |
|---|---|---|
改进 flutter/packages 的发布流程 (包含解耦后的 Material 和 Cupertino) |
已决定 | First-Party Package Release Strategy Batch Release One Pager (PUBLICLY SHARED) |
颜色和点速记 (Colors and dot shorthands) |
已决定 | A Basic Color Set for Flutter (PUBLICLY SHARED) |
| 解耦测试 (Decoupling tests) | 进行中 | Decoupling Framework Tests (PUBLICLY SHARED) Issue #177028 |
| 文本 (Text) | 讨论中 | Flutter Decoupling Design From Text (PUBLICLY SHARED) |
📜 滚动 (Scrolling): 更健壮和可预测的 Slivers
本次发布带来了多项修复,使得构建复杂的滚动布局(尤其是使用 SliverMainAxisGroup 和 SliverCrossAxisGroup 的布局)更加健壮和可预测。
- 开发者在使用这些 Widget 对多个 Slivers 进行分组时,会发现手势处理现在更可靠 。对这些组内 Slivers 上的点击和其他指针事件的命中测试现在计算正确,确保用户交互按预期进行 (#174265)。
- 其他几项修复有助于
SliverMainAxisGroup内更精确的滚动行为: - 对于构建自定义滚动视图的开发者,新的
SliverGrid.list构造函数 (#173925) 提供了一种从简单子 Widget 列表创建网格的更清晰方法。 - 本次发布还改进了复杂布局中键盘和 D-pad 用户的焦点导航 。在具有不同滚动轴的嵌套滚动视图中(例如垂直列表中的水平轮播图),定向焦点导航现在更可预测,防止焦点意外地在不同部分之间跳转 (#172875)。
♿ Accessibility: 为所有用户提供更包容的体验
使应用程序对所有用户都可访问是 Flutter 框架的基石。本次发布通过提供更多的编程控制 、改善国际用户的体验 以及优化核心 Widget 的辅助功能,继续履行这一承诺。
- 对于构建复杂应用的开发者,本次发布引入了通过使用
WidgetsFlutterBinding.instance.ensureSemantics来在 iOS 上默认开启辅助功能 的能力 (#174163)。 - 调试辅助功能问题现在更容易了,因为
debugDumpSemanticsTree包含了额外的文本输入验证结果信息 ,有助于更快地诊断问题 (#174677)。 - 对于基于 Sliver 的滚动视图中的高级辅助功能,现在可以使用新的
SliverSemanticsWidget (#167300)。- 就像现有的
SemanticsWidget 一样,开发者可以在CustomScrollView中使用SliverSemantics来用特定的语义信息注解 (annotate) Sliver 树的一部分。 - 这对于为屏幕阅读器注解头部、分配语义角色和添加描述性标签特别有用,为用户提供更易理解和可访问的体验。
- 就像现有的
- 核心 Widget 的辅助功能也在继续完善:
🍏 iOS 平台支持与迁移
平台支持
我们很高兴地确认 Flutter 完全支持最新的平台版本 :iOS 26、Xcode 26 和 macOS 26(均于 9 月发布)。这确保您可以立即在 Apple 最新的操作系统和工具链上开始开发和测试您的应用。
部署流程改进
您可能已经注意到,Flutter 在上一个版本中为 iOS 开发者带来了重大的生活质量改进 (quality-of-life improvement) ,解决了长期困扰用户的一个问题:使用 flutter run 在真机上运行 Flutter 应用时,要求 Xcode 应用程序自动启动。
- 我们引入了一种新的部署方法,使用 Xcode 26 命令行工具
devicectl进行应用程序安装、启动和调试。 - 这一转变消除了在部署过程中调用 Xcode 应用程序的需要,在大多数情况下仅依赖于命令行 Xcode 构建工具。
- 此前,此功能依赖于 Xcode 自动化,但在 Xcode 26 上变得不稳定和不可靠,尤其是在连续执行命令时。如果您现在正在为最新的 Apple 版本进行开发,我们强烈建议 您将 Flutter 更新到 3.38 或更高版本。
- 如果您遇到问题,可以使用
flutter config --no-enable-lldb-debugging禁用此部署方法,并提交问题让我们知道!
UIScene 生命周期迁移
Flutter 3.38 包含了对 Apple 强制要求的 UIScene 生命周期的关键支持。
- 这是继 Apple 在 WWDC25 上宣布**"在 iOS 26 之后的版本中,任何使用最新 SDK 构建的 UIKit 应用都将被要求使用
UIScene生命周期,否则将无法启动"**之后,一项关键的、前瞻性的更新。 - 为了确保您的 iOS Flutter 应用程序在未来的 iOS 版本上保持兼容并成功启动,需要进行迁移。
📱 迁移 Flutter 应用
所有现有的 iOS Flutter 应用都必须迁移到新的生命周期。您有两种途径完成此迁移:
- 手动迁移: 遵循 Flutter 网站上提供的手动迁移说明。
- 自动迁移(实验性): 启用一个实验性功能来自动处理迁移。此功能将在未来版本中默认启用。运行以下命令: flutter config --enable-ios-scene-lifecycle-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 中引入)发生在 Activities 因开发者设置或系统低内存而被销毁时。
Android 依赖项更新
确定适用于您的应用的 Android 依赖项(包括 Gradle、Android Gradle Plugin (AGP)、Kotlin Gradle Plugin (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 Plugin 版本。
- 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) 或更高版本
⚙️ 引擎(Engine)更新
性能叠加层 (Performance overlay)
性能叠加层已重构以提高效率,减少了其在 Skia 和 Impeller 后端上的渲染时间 (#176364)。这意味着您可以获得更准确的性能数据,且开销更小。
Vulkan 和 OpenGL ES
对 Vulkan 和 OpenGL ES 后端进行了大量修复和改进,提高了在更广泛设备上的稳定性和性能。这包括更好地处理管线缓存 (#176322)、围栏等待器 (#173085) 和图像布局转换 (#173884)。
渲染器统一
继续努力统一 CanvasKit 和 Skwasm 渲染器。本次发布包括大量的重构,以在这两者之间共享更多代码 ,这将有助于未来带来更一致的体验和更快的开发速度 (#174588)。
线程合并
注意⚠️注意⚠️注意⚠️ 从 iOS 和 Android 中移除了退出线程合并的能力**(即不再支持可选退出)。
🛠️ DevTools 和 IDEs
实验性 Widget 预览 - 更新
Flutter 3.35 引入了 Widget 预览,这是一项准备好接受社区早期反馈的实验性功能。Flutter 3.38 版本带来了对 Widget 预览的重大改进,包括:
- IDE 集成: VSCode 和 IntelliJ / Android Studio 插件都已更新,初步支持 Widget 预览。您现在可以直接在 IDE 内查看预览,以获得更无缝的开发体验。
当在 IDE 中使用时,Widget 预览环境 默认配置为根据当前选定的源文件来过滤显示的预览:

-
Widget 预览环境主题和控制改进 : Widget 预览环境现在支持浅色和深色模式,以及自定义 IDE 配色方案,以匹配您的开发环境。Widget 预览环境中的控件也已调整为占用更少的空间,为渲染预览留出更多可用空间。

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

- 多重预览支持 (MultiPreview support): 一个新的
MultiPreview基类 允许您从单个自定义标注中创建多个预览变体。

- 预览分组(Preview groups):
Preview类中新增了一个group参数 ,允许将相关的预览进行分组。

-
减少
@Preview标注参数限制:- 私有常量 现在被支持作为
@Preview标注的参数。 - 函数参数 (如
wrapper和theme)仍然要求具有公共的、静态可访问的名称。
- 私有常量 现在被支持作为
🚧 Widget 预览(实验性)- 未来计划与反馈
Widget 预览仍然是一个实验性功能,您的反馈对于塑造其未来至关重要。API 和用户体验尚未稳定,将根据我们从您那里获得的学习进行更改。
基于早期的反馈,计划进行更多增强,以改进 Widget 预览体验,包括:
- Flutter DevTools Widget Inspector 支持: Widget Inspector 正在更新,以支持在 Widget 预览环境中检查预览。我们计划将 Inspector 直接嵌入到 Widget 预览器中,使其无论在何种开发环境中都易于访问。
- IDE 中的多项目支持: Widget 预览器目前仅支持显示包含在单个项目或 Pub 工作区中的预览。我们正在积极研究支持具有多个 Flutter 项目的 IDE 会话的选项(问题 [#173550])。
- 启动性能改进: 正在调查性能改进的机会,以减少初始启动时间,包括:
- 在首次运行后启动预编译的 Widget 预览环境。
- 并行化预览检测逻辑,以更好地处理大型项目。
开始使用:
- 阅读文档: Flutter Widget Previews 入门 (实验性)
- 提供反馈: 在 Flutter GitHub 仓库中提交问题和功能请求。
- 了解更多: 要进行技术深入探讨,请参阅 Flutter Widget Previews 架构文档。
重要提示: 存在一个已知问题,即在执行
flutter pub get后,Widget 预览器可能会崩溃或停止更新。如果您遇到此问题,请在您的项目中运行flutter pub get并重启您的 IDE 。详见 #178317。
💻 DevTools 更新
Flutter 3.38 包含了对用户在 2025 年 DevTools 用户调查中提出的一些主要痛点的修复,包括:
- 网络面板 (Network Panel) 改进:
- Flutter Inspector 修复:
🚫 弃用和破坏性更改
本次发布包括几项重要的弃用 和破坏性更改,作为持续现代化和改进 Flutter 框架努力的一部分。
- 构建和工具链关键更改: 可能会影响自定义构建脚本。
- Flutter SDK 根目录下的
version文件已被移除 ,取而代之的是位于bin/cache中的新文件flutter.version.json(#172793)。 - 此外,
AssetManifest.json文件不再默认生成 (#172594)。
- Flutter SDK 根目录下的
- 其他值得注意的更改包括:
- 为了更可预测的行为,包含 Action(操作)的
SnackBar将不再自动关闭 (#173084)。 OverlayPortal.targetsRootOverlay构造函数已弃用 ,取而代之的是更灵活的OverlayPortal(overlayLocation: OverlayChildLocation.rootOverlay)。CupertinoDynamicColor上的几个属性(例如withAlpha和withOpacity)现已弃用 ,推荐使用标准的Color方法 (#171160)。- Flutter 3.38 要求 Java 17 作为 Android 的最低版本 ,与
Gradle 8.14(2025 年 7 月发布)的最低要求相匹配。
- 为了更可预测的行为,包含 Action(操作)的
有关这些和其他更改的更多详细信息和迁移指南,请查阅破坏性更改页面。
结束语
Flutter 3.38 专注于让您的日常开发更快、更愉快。这些增强功能旨在简化您的构建方式。我们非常感谢为本次发布做出贡献的每一位社区成员的辛勤工作和反馈。
要获取所有更改的完整列表,请务必查看详细的破坏性更改和发布说明 。要免费提升您的生产力,只需运行 flutter upgrade!
您已经使用上了flutter 3.38了呢还是打算继续等等?反正我先用为敬。