谷歌Flutter 3.47核心更新全解析

烽融爱财阅读：12368 2026-10-10

Flutter 3.47 的正式发布带来了一系列激动人心的更新。

近期我们迎来了独立的material_ui和cupertino_ui软件包 1.0 版本。这是一个重要里程碑，意味着设计系统正式与核心 SDK 解耦。

此外，我们还全面提升了性能和工具。此版本默认在桌面端启用 Impeller，并针对 iOS、macOS 和 Xcode 27 的开发流程做好了准备，同时将 Flutter Widget Previews 升级到了稳定版。

欢迎您即刻在终端运行flutter upgrade开始体验，或继续阅读，详细了解此版本的主要变更。

开启您的界面探索之旅

Material 和 Cupertino 现在都已作为独立软件包提供，这正是迈向 Flutter 解耦架构的第一步！

Flutter 最大的优势之一是其渲染像素级精准的 Material 和 Cupertino 组件。不过，由于这些设计库过去直接捆绑在核心 SDK 中，拖慢了它们的开发速度，也增加了社区贡献和及时更新的难度。

在本次版本中，核心 SDK 仍然包含这些组件库，但现在您也可以选择使用独立的material_ui和cupertino_ui软件包，1.0 版本已经正式在pub.dev上发布。

解耦设计路线图 (选择使用)

选择使用解耦后的设计系统，您就能更好地掌控自己的设计路线图。material_ui和cupertino_ui现在可以按照各自的每周节奏发布问题修复和新组件，而不再受限于 Flutter SDK 季度版本发布周期。

解耦设计系统将带来以下优势:

您可以使用最新的 Cupertino 和 Material widget 样式，而无需升级整个 Flutter SDK 版本。

我们可以更快、更频繁地合并贡献和更新。

为构建风格中立的 Flutter 核心 widget 目录奠定基础，未来可以更轻松地打造自定义设计系统。

如何迁移

您可以运行以下命令将您的项目迁移到新的独立软件包:

dartfix --apply --code=migrate_design_widgets

此工具会自动将您的导入从package:flutter/material.dart和package:flutter/cupertino.dart更新为新的独立软件包。

注意:如果迁移工具在更新pubspec.yaml时遇到问题 (已知早期错误)，您可以手动运行flutter pub add material_ui(如果项目使用了 Cupertino，还需运行cupertino_ui)，然后再运行一次dart fix --apply来修复该问题。

核心 SDK 中原有的设计库预计在 11 月发布的秋季稳定版中正式弃用。如果您正在迁移生态系统中的某个软件包，请将此次迁移到独立软件包视为一次重大版本更新。

弥合迁移差距

为了帮助生态系统顺利过渡到新的独立设计库，material_ui和cupertino_ui都提供了迁移工具。MaterialUiCompatibilityBridge允许应用立即迁移到独立软件包，即使部分软件包依赖仍在使用旧版核心 SDK 的导入路径，也不会受到影响。

例如，您可以使用 Compatibility Bridge 封装整个应用:

import'package:material_ui/material_ui.dart';


voidmain(){
 runApp(constMyApp());
}


classMyAppextendsStatelessWidget{
constMyApp({super.key});


 @override
Widgetbuild(BuildContext context){
 returnMaterialApp(
   theme: ThemeData(
    colorScheme: ColorScheme.fromSeed(seedColor:constColor(0xFF6750A4)),
   ),
   builder: (BuildContext context, Widget? child) {
   returnMaterialUiCompatibilityBridge(child: child!);
   },
   home:constHomeScreen(),
  );
 }
}

本地化解耦

作为此次过渡的一部分，flutter_localizations也已拆分出来。Material 和 Cupertino widget 的本地化委托和翻译字符串现在分别位于package:material_ui和package:cupertino_ui中。

处理之前:

dart
import'package:flutter_localizations/flutter_localizations.dart';
import'package:flutter/material.dart';


// ...
localizationsDelegates:const
 
  >[
 GlobalCupertinoLocalizations.delegate,
 GlobalMaterialLocalizations.delegate,
 GlobalWidgetsLocalizations.delegate,
],

处理之后:

import'package:material_ui/material_ui.dart';


// ...
localizationsDelegates:GlobalMaterialLocalizations.delegates,

现在，将localizationsDelegates设置为GlobalMaterialLocalizations.delegates也会同时包含 Cupertino 和 Widget 的委托，从而简化您的配置。

△ 解耦本地化结构

开放贡献

通过在今年 4 月冻结了 Material 和 Cupertino 库的代码贡献，material_ui和cupertino_ui中提供的库与大家目前正在使用的库是一致的，可以确保迁移过程顺利进行。

现在，我们已准备好解除冻结，敬请期待新软件包中定期推出的更多修复和功能，目前计划每周发布一个版本。我们也很高兴正式向社区开放这些软件包，欢迎大家献策献力。

为 Apple 更新做好准备

Xcode 27、iOS 27 和 macOS 27 已于今年秋季发布，我们投入了大量精力，确保 Flutter 能够适配更新，建议您现在就使用 Apple 的测试版系统对应用进行测试。

此外，我们提升了支持的最低操作系统版本以适配 Xcode 27:

平台

之前的最低版本

新的最低版本

(Flutter 3.47+)

iOS

macOC

10.15

UIScene 生命周期强制要求

iOS 27 SDK 现在强制要求所有基于 UIKit 的应用采用UIScene生命周期。使用 Xcode 27 构建但未采用UIScene的应用将在启动时失败，无法正常运行。

对于大多数应用，Flutter CLI 会在构建过程中自动完成迁移。但是，如果您在AppDelegate中包含自定义原生代码，或者使用了仍然依赖于旧版应用生命周期的插件，则需要手动迁移。在这种情况下，您必须按照UIScene/Delegate 采用指南完成手动迁移:。

逐步停止支持 Intel Mac

为了配合 Apple 向 Apple Silicon 的过渡，Flutter 正逐步停止支持基于 Intel 芯片的 Mac。我们已停用在 Intel 硬件上运行的自动化测试，同时当 Flutter CLI 检测到您在 Intel 主机上构建，或构建面向双架构的应用时，会输出警告。这些警告将在未来版本中升级为错误。

您可以通过运行flutter config --enable-macos-arm64-only来选择构建仅支持 ARM64 架构的 macOS 应用。

Swift Package Manager 进展

社区在过渡到 Swift Package Manager 方面取得了巨大的进展，目前排名前 100 的 iOS 插件中已有 92 个完成迁移。如果您之前关闭了 Swift Package Manager，可以通过运行flutter config --enable-swift-package-manager重新启用。

由于 CocoaPods 目前处于维护模式，未迁移到 SwiftPM 的插件最终将停止工作。未迁移的插件也会获得较低的pub.dev评分。如果您是插件的维护者，请参阅迁移指南并阅读我们之前的博文，了解更多详情。

此次版本还优化了构建时间，这要感谢社区贡献者@lukemmtt，他通过在构建过程早期过滤掉不必要的 SwiftPM Package Scheme，改进了构建流程 (#186006)。

默认启用 Wasm

我们正积极致力于在 Flutter Web 应用中默认启用 WebAssembly (Wasm)，来为浏览器带来媲美原生应用的性能表现。如果您尚未使用 Wasm 测试您的 Web 应用，现在可以通过在发布 build 命令中添加--wasm标志来启用 Wasm:

flutter build web--release--wasm

在为此过渡做准备时，请注意: 由于旧版的dart:html库不再受支持，Wasm 需要将您的代码库迁移到新的 JS 互操作软件包 (package:web)。通过升级项目的软件包依赖项即可自动解决这些旧版互操作问题。

为了帮助扩展大型 Web 应用，本次发布还引入了对 Wasm 延迟加载的实验性支持。在 main 分支中通过标志启用后，您可以将 Wasm 应用拆分为更小的延迟加载模块，从而优化初始加载时间:

flutter build web--release--wasm--enable-wasm-deferred-loading

Impeller 为桌面端带来现代图形渲染

我们致力于将桌面平台打造成为高性能图形的一流平台。在 Flutter 3.47 中，Impeller 已成为 macOS、Windows 和 Linux 的默认渲染器。

Impeller 是 Flutter 从底层构建的下一代渲染引擎，旨在取代 Skia。Impeller 针对现代硬件 API (例如 macOS 上的 Metal 以及 Windows 和 Linux 上的 Vulkan) 进行优化，在构建时编译一组固定的着色器，而不是在运行时动态编译。这消除了动画首次播放时出现的短暂卡顿 (称为着色器编译卡顿)，从而从第一帧开始就提供始终如一的流畅过渡。更多信息请参阅Impeller 渲染引擎文档。

如果您需要临时停用 Impeller，请按以下步骤操作:

macOS: 在Info.plist中将FLTEnableImpeller设置为false。

Windows: 在main.cpp中添加project.set_impeller_switch(flutter::Disabled)。

Linux: 在my_application.cc中调用fl_dart_project_set_enable_impeller(project, FALSE)。

回退选项将在未来的版本中被移除，因此如果您必须回退使用 Skia，请提交错误报告。此外，macOS 现在默认启用广色域色彩，可在支持的硬件上提供更加丰富、鲜艳且精准的色彩渲染效果。

实验性多窗口模式进展

通过与 Canonical 的合作，并感谢维护者@robert-ancell和@mattkae的贡献，我们正在扩展实验性的桌面窗口化 API。Linux 和 Windows 现在支持弹出式窗口 (#185866、#184516)，您可借此构建原生的上下文菜单和工具面板。

△ Win32 上的弹出式窗口

现在，您还可以通过特定平台的控制器查询windowHandle，以获取底层原生窗口的直接指针 (HWND、NSWindow或GtkWindow)。这使得您可以调用高级原生特性，例如 Windows 上的可停靠面板，下面就是由@orestesgaolin提供的可停靠面板演示:

△ 可停靠面板演示

我们还修复了几个窗口焦点和实例化方面的错误。在 Windows 系统中，激活窗口不再会将后台窗口拉到前面，也不会在应用恢复时抢占焦点，这一修复由创作贡献者@9AZX提供 (#188016):

△ 窗口焦点与实例化问题修复

在 Linux 上，多窗口创建现在会在窗口接收到来自合成器的首帧画面前，显式完成窗口实例化，从而修复早期渲染警告和合成器断言错误。

我们还新增了一个 "根据内容自适应大小" API，您可以借此创建能够根据自身内容自动调整尺寸的常规窗口与对话框窗口。

桌面平台支持构建变体

Windows 和 Linux 现已支持 Flutter 的构建变体。

例如，您可以在pubspec.yaml文件中为不同的构建变体配置不同的资源:

flutter:
 assets:
  - path: assets/flavor_a/images
   flavors:
    - flavor_a
  - path: assets/flavor_b/images
   flavors:
    - flavor_c

请使用--flavor选项指定构建变体。例如:

flutter build windows --flavor flavor_a

flutter build linux --flavor flavor_a

感谢@AngeloAvv做出的卓越贡献 (#187034，#187029)！

更清晰的桌面文本

桌面设备的屏幕像素密度通常低于移动设备，但具有更强的图形计算能力。为了在桌面设备上提供更清晰的文本和更干净的矢量曲线，搭载 Impeller 的 Flutter 引擎现已在 macOS、Linux 和 Windows 上采用符号距离函数 (SDF) 渲染。

GenUI 的稳定预览版与更新

Widget Preview 推出稳定版

Flutter Widget Preview 现已正式进入稳定版。开发者无需构建或启动整个应用，就可以即时渲染、检查并迭代单个界面组件。

此稳定版本新增功能包括:

由于在.widget_preview/文件夹中进行本地项目缓存，启动速度更快，无需重复设置。

借助抽象的PreviewThemeData API，测试更加灵活，支持为复杂的矩阵测试提供顺序主题分层能力。

预览 Web widget 时自动同步 Web 资源，直接复制宿主项目的web/资源，并在使用 Flutter Web 时自动应用任何自定义主题或自定义index.html文件。

GenUI 的持续改进

Flutter 生态系统持续演进，以满足开发者使用 GenUI 为用户创建新型智能体验的需求。genui软件包 0.10.0 版本于近期发布，带来了一系列修复和新特性，其中包括:

新增a2ui_core软件包，集中管理与协议相关的类，例如表达式、目录条目等。

支持 A2UI 的客户端函数，您可以向智能体提供一些函数，智能体可以指示客户端使用这些函数进行验证、获取派生值以及其他一些无需往返通信的小型任务。

优化平台体验

本部分重点介绍了社区和 Flutter 团队贡献的一些针对性改进，旨在进一步提升各个平台上的开发者体验和用户体验。

Android

在 Android 平台上，我们修复了一个虚拟键盘问题，此前修饰键 (例如 Shift) 在处理事件时可能会 "卡住"。现在，按键响应器会跳过虚拟键盘输入的物理按键合成，从而保持键盘交互的流畅性。

Android 依赖项矩阵

为确保构建稳定，Flutter 3.47 已针对以下 Android 依赖项版本进行验证:

Java: 17 (最低要求版本)

Kotlin Gradle Plugin (KGP): 2.4.0

Android Gradle Plugin (AGP): 9.1.0 (与 KGP 2.4.0 兼容的最新版本)

Gradle: 9.3.1 (AGP 9.1.0 的最低要求版本)

为了确保应用能够在未来的 Flutter 版本中顺利构建，我们建议您在构建文件中使用 Flutter SDK 提供的标准 API 级别变量。在当前版本中，这些变量的默认值如下:

flutter.compileSdkVersion(API 36)

flutter.targetSdkVersion(API 36)

flutter.minSdkVersion(API 24)

iOS 和 macOS

对于 iOS 开发者而言，代码签名流程现在变得更加透明。感谢社区成员@alex-medinsh，CLI 在选择证书时会同时显示团队 ID 和团队名称 (#184665)。

此外，社区成员@mozammal-hossain还改进了问题排查体验: 当签名失败时，系统现在会提供更加清晰的配置描述文件错误信息 (#184051)。

桌面设备

桌面设备平台也得到了针对性的改进。Windows 上韩语文本输入的光标定位问题已得到解决 (感谢@CHOIgoung，#186353)；Windows 插件现在可以使用FlutterEngine::PostPlatformThreadTask将耗时任务移出平台线程。在 Linux 上，@CodeDoctorDE添加了触控笔旋转和压感上报功能 (#186831)。

图形和引擎

在引擎中，面向 OpenGLES 的片段着色器在读取纹理时不再需要条件坐标翻转。现在，这一操作已由顶点着色器处理。更多详情请参阅"OpenGLES 渲染到纹理的重大变更" 页面。

框架优化

最后，框架本身也更加流畅，改进涵盖了各个关键组件:

无障碍功能和语义:得益于@xxxOVALxxx的贡献，现在可以自动检测 Android 的高对比度和颜色反转设置 (MediaQueryData.highContrast和MediaQueryData.invertColors，#182263)。Text.rich中嵌套的 Text Span 现在会在语义树中按照其布局顺序排列，并且BlockSemantics新增了键盘焦点阻塞功能。

文本和选择:感谢@JhonaCodes(#182663) 的贡献，现在移动端的文本选择句柄在轻微滚动时可以保持稳定，并且支持通过键盘快捷键关闭已打开的选择菜单。在 Android 系统上，位于屏幕顶部附近的选择句柄不再遮挡上下文菜单。

更新之前	更新之后

我们还修复了在空的可滚动容器中开始选择时SelectableRegion发生崩溃的问题，并解决了淡化的可选文本上的视觉高亮残留问题，特此感谢@ikramhasan(#183628)。

更新之前	更新之后

手势和滚动:改进了通过平台视图嵌入的原生 iOS 视图的手势传播。EdgeDraggingAutoScroller现在会遵循活动滚动视图的ScrollPhysics，防止锁定的列表自动滚动。

△ EdgeDraggingAutoScroller 演示

核心 Widget 增强功能:ImageIcon现在支持通过useOriginalColors: true保留图像的原始颜色 (#180491)；AnimatedCrossFade新增了显式指定裁剪行为的能力 (#184545)；此外，还可以通过ImageStreamListener直接跟踪图像流错误。

准备升级

现在您只需在本地设备中应用这些升级: