Flutter 3.47 核心更新全解析

△ Flutter 3.47 的新功能

Flutter 3.47 正式发布，带来一系列重要更新。最引人注目的是 material_ui 和 cupertino_ui 软件包独立发布 1.0 版本，标志着设计系统与核心 SDK 正式解耦。此外，该版本在桌面端默认启用 Impeller 渲染引擎，优化了 iOS/macOS 开发流程以适配 Xcode 27，并将 Flutter Widget Previews 升级为稳定版。

开发者可立即运行 flutter upgrade 进行升级，以下是本次更新的详细解读。

开启您的界面探索之旅

Material 和 Cupertino 组件库现已作为独立软件包提供，这是 Flutter 迈向解耦架构的关键一步。过去，这些设计库捆绑在核心 SDK 中，限制了更新频率和社区贡献效率。

在 Flutter 3.47 中，核心 SDK 仍包含这些组件，但开发者可选择使用已发布在 pub.dev 上的独立 material_ui 和 cupertino_ui 包。

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

采用独立设计系统意味着您可以摆脱 Flutter SDK 季度发布的限制，按每周节奏获取问题修复和新组件。其主要优势包括：

• 无需升级整个 Flutter SDK 即可使用最新的 Material 和 Cupertino 组件样式。

• 加快社区贡献合并与更新频率。

• 为构建风格中立的 Flutter 核心 Widget 目录奠定基础，便于未来定制设计系统。

如何迁移

可通过以下命令自动将项目迁移至新的独立软件包：

dart fix --apply --code=migrate_design_widgets

该工具会自动将导入路径从 package:flutter/material.dart 等更新为新包。若迁移工具在更新 pubspec.yaml 时遇到问题，可手动运行 flutter pub add material_ui（及 cupertino_ui），随后再次执行 dart fix --apply。

注意：核心 SDK 中原有的设计库预计将在 11 月发布的秋季稳定版中正式弃用。对于生态包维护者，此次迁移视为重大版本更新。

弥合迁移差距

为确保平稳过渡，新包提供了 MaterialUiCompatibilityBridge。即使部分依赖仍使用旧版核心 SDK 导入路径，应用也可通过该桥接器立即迁移。

示例代码：

import 'package:material_ui/material_ui.dart';
void main() {  runApp(const MyApp());}
class MyApp extends StatelessWidget {  const MyApp({super.key});
  @override  Widget build(BuildContext context) {    return MaterialApp(      theme: ThemeData(        colorScheme: ColorScheme.fromSeed(seedColor: const Color(0xFF6750A4)),      ),      builder: (BuildContext context, Widget? child) {        return MaterialUiCompatibilityBridge(child: child!);      },      home: const HomeScreen(),    );  }}

本地化解耦

flutter_localizations 也已拆分。Material 和 Cupertino 的本地化委托及翻译字符串现分别位于各自的独立包中。

迁移前：

dartimport 'package:flutter_localizations/flutter_localizations.dart';import 'package:flutter/material.dart';
// ...localizationsDelegates: const <LocalizationsDelegate<dynamic>>[  GlobalCupertinoLocalizations.delegate,  GlobalMaterialLocalizations.delegate,  GlobalWidgetsLocalizations.delegate,],

迁移后：

import 'package:material_ui/material_ui.dart';
// ...localizationsDelegates: GlobalMaterialLocalizations.delegates,

现在，设置 GlobalMaterialLocalizations.delegates 将同时包含 Cupertino 和 Widget 的委托，简化了配置。

△ 解耦本地化结构

开放贡献

今年 4 月冻结的 Material 和 Cupertino 库代码已解冻。新独立包将按周发布版本，并正式向社区开放贡献渠道。

为 Apple 更新做好准备

随着 Xcode 27、iOS 27 和 macOS 27 的发布，Flutter 已做好适配准备。建议开发者尽快使用测试版系统进行验证。同时，支持的最低操作系统版本有所提升：

UIScene 生命周期强制要求

iOS 27 SDK 强制要求所有基于 UIKit 的应用采用 UIScene 生命周期。未采用的应用在启动时将失败。大多数应用可通过 Flutter CLI 自动迁移，但若涉及自定义原生代码或旧版插件，需参考指南手动迁移。

逐步停止支持 Intel Mac

为配合 Apple 向 Apple Silicon 过渡，Flutter 正逐步停止支持 Intel Mac。目前已在 Intel 硬件上停用自动化测试，并在 CLI 中增加警告。未来这些警告将升级为错误。可通过 flutter config --enable-macos-arm64-only 构建仅支持 ARM64 的应用。

Swift Package Manager 进展

前 100 个 iOS 插件中已有 92 个迁移至 Swift Package Manager (SPM)。由于 CocoaPods 进入维护模式，未迁移插件将停止工作且评分降低。可通过 flutter config --enable-swift-package-manager 重新启用 SPM。

社区贡献者 @lukemmtt 通过优化 SwiftPM 构建流程，显著缩短了构建时间。

默认启用 Wasm

Flutter Web 正积极转向默认启用 WebAssembly (Wasm) 以提升性能。若尚未测试，可通过添加 --wasm 标志启用：

flutter build web --release --wasm

注意：Wasm 不再支持旧的 dart:html，需迁移至 package:web。此外，引入了实验性的 Wasm 延迟加载支持，可将应用拆分为更小模块以优化初始加载：

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

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

Flutter 3.47 中，Impeller 已成为 macOS、Windows 和 Linux 的默认渲染器。它针对 Metal 和 Vulkan 优化，通过预编译着色器消除首次动画卡顿。macOS 现默认启用广色域色彩。

如需临时停用 Impeller：

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

• Windows: 在 main.cpp 中添加禁用代码。

• Linux: 在 my_application.cc 中调用禁用函数。

注意：回退选项将在未来移除，如遇问题请提交报告。

实验性多窗口模式进展

Linux 和 Windows 现在支持弹出式窗口，可用于构建原生上下文菜单和工具面板。此外，可通过特定平台控制器查询 windowHandle 获取原生窗口指针，实现高级原生特性（如 Windows 可停靠面板）。

△ Win32 上的弹出式窗口

修复了 Windows 窗口焦点和实例化错误，以及 Linux 多窗口早期渲染警告。新增“根据内容自适应大小”API，允许窗口随内容自动调整尺寸。

桌面平台支持构建变体

Windows 和 Linux 现已支持 Flutter 构建变体 (Flavors)。可在 pubspec.yaml 中为不同变体配置资源，并通过 --flavor 选项构建。

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

更清晰的桌面文本

搭载 Impeller 的 Flutter 引擎在桌面端（macOS, Linux, Windows）采用符号距离函数 (SDF) 渲染，以提供更清晰的文本和矢量曲线.

GenUI 的稳定预览版与更新

Widget Preview 推出稳定版

Flutter Widget Preview 进入稳定版，支持即时渲染和迭代单个组件。新功能包括：

• 通过本地项目缓存加速启动。

• PreviewThemeData API 支持更灵活的主题分层测试。

• Web 预览时自动同步宿主项目资源。

GenUI 的持续改进

genui 0.10.0 版本发布，新增 a2ui_core 包管理协议相关类，并支持 A2UI 客户端函数，允许智能体执行验证等小型任务。

优化平台体验

本部分汇总了各平台的针对性改进。

Android

修复了虚拟键盘修饰键（如 Shift）“卡住”的问题，按键响应器现跳过虚拟键盘输入的物理按键合成，保持交互流畅。

Android 依赖项矩阵

Flutter 3.47 验证的 Android 依赖版本：

• Java: 17 (最低)

• Kotlin Gradle Plugin (KGP): 2.4.0

• Android Gradle Plugin (AGP): 9.1.0

• Gradle: 9.3.1

建议使用的 SDK 变量默认值：

• flutter.compileSdkVersion: API 36

• flutter.targetSdkVersion: API 36

• flutter.minSdkVersion: API 24

iOS 和 macOS

iOS 代码签名流程更加透明，CLI 选择证书时显示团队 ID 和名称。签名失败时提供更清晰的配置描述文件错误信息。

桌面设备

Windows 韩语文本输入光标定位问题已修复；Windows 插件支持将耗时任务移出平台线程。Linux 新增触控笔旋转和压感上报功能。

图形和引擎

OpenGLES 片段着色器读取纹理时不再需要条件坐标翻转，该操作已移至顶点着色器处理。

框架优化

• 无障碍功能和语义: 自动检测 Android 高对比度和颜色反转设置；Text.rich 嵌套 Span 按布局顺序排列；BlockSemantics 新增键盘焦点阻塞功能。

△ Android 无障碍设置

• 文本和选择: 移动端文本选择句柄在轻微滚动时保持稳定，支持键盘快捷键关闭菜单；Android 顶部附近的选择句柄不再遮挡上下文菜单。

更新之前	更新之后

• 修复了空可滚动容器中 SelectableRegion 崩溃及淡化文本高亮残留问题。

更新之前	更新之后

• 手势和滚动: 改进原生 iOS 视图嵌入的手势传播；EdgeDraggingAutoScroller 遵循活动滚动视图的 ScrollPhysics。

△ EdgeDraggingAutoScroller 演示

• 核心 Widget 增强: ImageIcon 支持保留原始颜色；AnimatedCrossFade 支持指定裁剪行为；ImageStreamListener 可直接跟踪图像流错误。

准备升级

请在本地设备运行以下命令应用升级：

flutter upgrade

升级期间，建议您观看 "Introducing: Flutter Notable Commits" 视频系列了解社区贡献，并查阅“重大变更”页面为独立界面包迁移做准备。

期待您使用全新 Flutter 版本打造精彩应用！