企业官网建设流程全解析

• 跨平台
• 移动开发
• 前端
• UI组件
• OpenHarmony
• 图形学

本文以 CPF-Flutter/flutter_flutter 开源仓库（Flutter SDK 与 Engine 的 OpenHarmony 适配版本）为基础，系统梳理 Flutter 3.27 到 3.35 三个大版本之间的全部破坏性变更（Breaking Changes）。文章覆盖变更来源版本、是否需要适配、具体 API 迁移方式，并逐项对照当前仓库源码给出实现层面的证据与迁移示例，帮助开发者在升级 SDK 或迁移存量项目时一次性完成适配评估。

从 Flutter 3.27 到 Flutter 3.35，框架层面的演进集中在性能优化、新功能引入与框架 API 规范化三方面。官方共发布 26 项破坏性变更，其中 3.29 引入 6 项、3.32 引入 10 项、3.35 引入 10 项；按适配要求划分，有 4 项"无需适配"（多为平台层内部行为或移除旧 API），其余 22 项均要求开发者调整代码。下文按版本分组逐项说明，并在每项后给出本仓库中的源码落点作为迁移依据。

一、变更总览：26 项变更的分组与适配优先级

先给出全部 26 项变更的速查总表。适配标记为"是"的项，在升级后大概率触发编译告警（deprecated注解）或行为变化，需要主动迁移；标记为"否"的项通常由 SDK/引擎侧自动处理，开发者只需知晓即可。

二、Flutter 3.29 引入的 6 项变更

2.1 删除 v1 Android 嵌入 Java API（无需适配）

Flutter 3.29 移除了 Android 第一代（v1）嵌入层的 Java API。v1 嵌入方案早已被基于FlutterEngine/FlutterEngineGroup的 v2 嵌入取代，因此移除对存量项目影响极小。仍在使用io.flutter.app.FlutterActivity（v1 基类）的宿主工程需要迁移到io.flutter.embedding.android.FlutterActivity。

在 CPF-Flutter 仓库中，v2 嵌入的配套示例可见于 dev/integration_tests/android_module_host_with_custom_build_v2_embedding，该目录展示了基于 v2 embedding 的宿主工程组织方式；仓库中大量 Android 宿主示例（如 examples/flutter_view/android）也都使用 v2 嵌入模型，可作为迁移参考。

2.2 弃用 WebGoldenComparator（需要适配）

Flutter 3.29 起 WebGoldenComparator 被弃用。Golden（黄金文件）测试在 Web 平台上原本依赖 WebGoldenComparator 这一专用比较器，弃用后其能力被统一的比较器体系收敛。

在 CPF-Flutter 仓库的 flutter_test 包中，黄金文件比较器的核心入口位于 packages/flutter_test/lib/src/goldens.dart，其中定义了全局的goldenFileComparator（默认值为占位的TrivialComparator，在运行flutter test时由测试框架替换为真实比较器）。该文件同时也提供了"临时替换比较器"的标准写法（保存旧比较器 → 赋新值 →addTearDown恢复），如果你的项目实现了自定义比较器，请按同样的模式迁移到非弃用 API，并在 Web 上使用与新默认行为兼容的比较器实现。

2.3 弃用 ThemeData.dialogBackgroundColor（需要适配）

ThemeData.dialogBackgroundColor在 3.29 被弃用，官方要求改用DialogThemeData.backgroundColor。这符合 Flutter 将散落在ThemeData上的组件属性逐步下沉到对应组件主题类的总趋势。

在 CPF-Flutter 仓库中，弃用注解与替代指引清晰可见：

• packages/flutter/lib/src/material/theme_data.dart 中dialogBackgroundColor参数被@Deprecated标注，提示迁移到DialogThemeData.backgroundColor；
• packages/flutter/lib/src/material/dialog_theme.dart 中DialogTheme.backgroundColor的文档明确说明："please use the [DialogThemeData.backgroundColor] property in [data] instead"（请改用data中的DialogThemeData.backgroundColor）。

迁移示例：

// 旧写法（3.29 起弃用） ThemeData( dialogBackgroundColor: Colors.white, ); // 新写法 ThemeData( dialogTheme: DialogThemeData(backgroundColor: Colors.white), );

2.4 ImageFilter.blur 默认瓦片模式自动选择（需要适配）

ImageFilter.blur的默认TileMode从固定值改为"自动选择"。此前模糊操作在图像边缘采用固定的采样模式，升级后引擎会根据模糊核的大小与作用区域自动挑选合适的瓦片模式（clamp / repeated / mirror 等），以改善边缘效果与性能。

在 CPF-Flutter 仓库的 framework 中，ImageFilter.blur在 widget 层的典型用法位于 packages/flutter/lib/src/widgets/basic.dart，例如imageFilter: ui.ImageFilter.blur(sigmaX: 6, sigmaY: 6)这类背影模糊（backdrop blur）场景；相关渲染实现参考 packages/flutter/lib/src/rendering/proxy_box.dart。如果应用对边缘模糊行为有严格预期，建议在调用blur时显式传入TileMode，避免依赖新默认值导致视觉效果变化。

2.5 更新 Material 3 滑块（需要适配）

Material 3 的Slider外观与交互被更新，涉及滑块轨道、手柄（thumb）尺寸与悬停/拖拽状态的表现。适配要点是确认基于SliderThemeData的自定义样式是否仍与新版默认样式兼容。

在 CPF-Flutter 仓库中，滑块相关实现位于 packages/flutter/lib/src/material/slider.dart（Slider类）与_SliderState（slider.dart）。从源码可见，滑块状态的解析已基于MaterialState集合（如disabled、hovered、focused、dragged，见 slider.dart）。如果你的主题里用MaterialStateProperty自定义了overlayColor等属性，需重新走查这些状态分支在新版默认样式下的表现。

2.6 更新 Material 3 进展指标（需要适配）

Material 3 的进展指示器（LinearProgressIndicator、CircularProgressIndicator）新增了轨道间距（track gap）与分段样式等能力。仓库源码 packages/flutter/lib/src/material/progress_indicator.dart 中_LinearProgressIndicatorPainter接收trackGap参数；LinearProgressIndicator本身也新增了trackGap与year2023两个兼容开关（progress_indicator.dart）：

• trackGap：轨道与进度条之间的间隙宽度，设 0 可隐藏间隙，默认取ProgressIndicatorThemeData.trackGap；
• year2023：为保持 2023 年旧版视觉而设的兼容开关，置false或ThemeData.useMaterial3为false时会关闭新分段/间隙样式。

迁移建议：接受新默认样式即可；若需恢复旧外观，可在LinearProgressIndicator或主题层显式设置year2023: true、trackGap: 0。

三、Flutter 3.32 引入的 10 项变更

3.1 弃用 SystemContextMenuController.show（无需适配）

3.32 弃用了SystemContextMenuController.show。该 API 用于在文本选择等场景显示系统级上下文菜单，弃用后由框架内部走新的调用路径，普通应用无需改动，因此标记为"无需适配"。

3.2 弃用 ExpansionTileController，改用 ExpansibleController（需要适配）

3.32 将ExpansionTileController迁移为更通用的ExpansibleController，同时新增了Expansible基础组件。ExpansionTile本身保留，但其控制器类被标记弃用。

在 CPF-Flutter 仓库中：

• packages/flutter/lib/src/widgets/expansible.dart 定义了ExpansibleController extends ChangeNotifier，提供isExpanded状态查询（L89）、expand()（L106）与collapse()等编程式控制方法；
• packages/flutter/lib/src/material/expansion_tile.dart 中ExpansionTileController已被@Deprecated标注，推荐使用ExpansibleController.of获取自动创建的控制器；
• 配套的自动修复规则位于 packages/flutter/lib/fix_data/fix_material/fix_expansion_tile.yaml。

迁移示例：

// 旧写法（3.32 起弃用） ExpansionTileController _controller = ExpansionTileController(); ExpansionTile(controller: _controller, ...); // 新写法 ExpansibleController _controller = ExpansibleController(); ExpansionTile(controller: _controller, ...); _controller.expand(); _controller.collapse();

3.3 弃用 RouteTransitionRecord.markFor，改用 markForComplete（需要适配）

RouteTransitionRecord的markForPop/markForRemove被统一收拢为markForComplete。该类型用于 Navigator 2.0 页面路由过渡的记录与决策（resolve/_transition流程），自定义路由过渡的开发者需要更新调用点。

仓库源码 packages/flutter/lib/src/widgets/navigator.dart 中清晰可见：markForComplete是新方法，而markForPop等旧方法被@Deprecated标注并提示 "Call markForComplete instead."；markForRemove也改为直接委托markForComplete()。框架内部（如resolve中对退出路由统一调用exitingPageRoute.markForComplete()，见 navigator.dart）已全部切换到新 API。

3.4 弃用 ThemeData.indicatorColor，改用 TabBarThemeData.indicatorColor（需要适配）

ThemeData.indicatorColor（TabBar 下划线指示器颜色）被弃用，改由TabBarThemeData.indicatorColor承担。仓库中弃用注解见 packages/flutter/lib/src/material/theme_data.dart（提示 "Use TabBarThemeData.indicatorColor instead."），对应的新属性定义在 packages/flutter/lib/src/material/tab_bar_theme.dart 中。

迁移示例：

// 旧写法（3.32 起弃用） ThemeData(indicatorColor: Colors.blue); // 新写法 ThemeData( tabBarTheme: TabBarThemeData(indicatorColor: Colors.blue), );

3.5 Material 主题系统更新（需要适配）

3.32 对 Material 主题系统做了一轮系统性调整，核心是把组件级属性继续从ThemeData迁移到各自的*ThemeData类，并统一部分组件的默认值。本仓库 packages/flutter/lib/src/material/theme_data.dart 中散布的@Deprecated注解（如dialogBackgroundColor、indicatorColor相关条目，见 L368-L382）即是这一轮"主题去中心化"的实例。建议升级后在flutter analyze输出中检索所有ThemeData属性告警，逐条迁移到对应组件主题类。

3.6 .flutter-plugins-dependencies 代替 .flutter-plugins（需要适配）

插件清单文件.flutter-plugins被.flutter-plugins-dependencies取代。新版清单以 JSON 格式描述插件的依赖关系（含平台插件注册信息），供工具链解析。该文件由flutter pub get自动生成，位于工程根目录。开发者通常无需手改，但若存在 CI 脚本或自定义工具读取.flutter-plugins，需要同步更新读取逻辑。

3.7 本地化消息生成在源端，而不是合成包（需要适配）

flutter gen-l10n的产物生成位置发生变化：本地化消息不再在"合成包（synthetic package）"中生成，而是直接生成在源端（工程内的lib/生成目录）。影响点是 import 路径：依赖合成包路径的 import 需要改为源端相对路径。CPF-Flutter 仓库中的本地化资源组织可参考 packages/flutter_localizations/lib（大量.arb文件与生成的 dart 文件共存），存量项目可参照其目录结构调整自己的生成目录与 import 声明。

3.8 更改默认 goldenFileComparator 以支持 integration_test（需要适配）

3.32 更改了默认的黄金文件比较器，使其支持在integration_test（集成测试）中运行 golden 测试。此前 golden 比较器主要面向单元测试环境；新默认比较器能在集成测试的宿主环境中正确读取与比较黄金文件。

仓库中 packages/flutter_test/lib/src/goldens.dart 定义了全局goldenFileComparator；相关使用与替换模式可参考 packages/flutter_test/test/goldens_test.dart 与 packages/flutter_test/lib/src/matchers.dart。集成测试场景下的 golden 用例，建议显式依赖matchesGoldenFile并在integration_test环境运行以验证新比较器的行为。

3.9 弃用 InputDecoration.maintainHintHeight，改用 maintainHintSize（需要适配）

InputDecoration.maintainHintHeight被重命名为maintainHintSize。语义上从"保持 hint 文本高度"扩展为"保持 hint 所占空间尺寸"，用于在无焦点/无内容时维持输入框高度稳定。

仓库源码 packages/flutter/lib/src/material/input_decorator.dart 中，_InputDecoratorState已改用maintainHintSize字段参与布局计算（如 L1069 的decoration.maintainHintSize分支），并在 L2763 等处以 "Use maintainHintSize instead." 提示弃用。自动修复规则见 packages/flutter/lib/fix_data/fix_material/fix_input_decoration.yaml。

迁移示例：

// 旧写法（3.32 起弃用） InputDecoration(maintainHintHeight: true); // 新写法 InputDecoration(maintainHintSize: true);

3.10 更改欠阻尼弹簧公式（需要适配）

欠阻尼（underdamped）弹簧的物理公式被更新，用于更准确地模拟真实弹簧。影响面是SpringDescription派生出的动画曲线（如SpringSimulation），自定义弹簧动画的时序与回弹幅度会略有变化。如果项目中有对弹簧动画的视觉断言或黄金帧测试，升级后需要重新校准。该变更与动画物理引擎相关，framework 侧无需改代码，但建议在升级后走查flutter analyze中与SpringDescription/Curves相关的测试基线。

四、Flutter 3.35 引入的 10 项变更

4.1 组件主题规范化更新（需要适配）

3.35 继续推进组件主题规范化：各组件*ThemeData的默认值、属性名与copyWith行为进一步统一。本仓库中可观察到这类"规范化"的痕迹，例如 packages/flutter/lib/src/material/app_bar_theme.dart 中color与backgroundColor被合并为同一语义，并在构造参数中做一致性断言（"The color and backgroundColor parameters mean the same thing. Only specify one."，见 L62-L63）。升级时建议对自定义主题做一次全面flutter analyze，逐条处理新增告警。

4.2 弃用 DropdownButtonFormField 的 value，改用 initialValue（需要适配）

DropdownButtonFormField.value被弃用，改用FormField.initialValue语义的initialValue。这一改动让 Dropdown 的"初始值"语义与其他FormField保持一致（初始值只作用于首次构建）。

仓库源码 packages/flutter/lib/src/material/dropdown.dart 中：DropdownButtonFormField的value参数带弃用注解 "Use initialValue instead."，内部通过initialValue: initialValue ?? value做兼容，并在didUpdateWidget中仅当initialValue变化时setValue（L1927-L1928）。同一模式的DropdownMenuFormField也已迁移到initialSelection→initialValue（见 packages/flutter/lib/src/material/dropdown_menu_form_field.dart）。

迁移示例：

// 旧写法（3.35 起弃用） DropdownButtonFormField<String>( value: 'one', items: [...], onChanged: ..., ); // 新写法 DropdownButtonFormField<String>( initialValue: 'one', items: [...], onChanged: ..., );

4.3 弃用应用栏颜色（需要适配）

3.35 弃用了 AppBar 主题与AppBarTheme上的color（以及与backgroundColor的并存使用）。仓库源码 packages/flutter/lib/src/material/app_bar_theme.dart 中，AppBarThemeData.color被@Deprecated标注并提示 "Use backgroundColor instead."；构造函数同时要求color与backgroundColor二选一。与此配套，ThemeData侧散落的 AppBar 颜色配置也需要收敛到appBarTheme。

迁移示例：

// 旧写法（3.35 起弃用） AppBarTheme(color: Colors.blue); // 新写法 AppBarThemeData(backgroundColor: Colors.blue);

4.4 重新设计 Radio 部件（需要适配）

3.35 重新设计了Radio部件的 API：groupValue与onChanged从Radio自身迁移到新的祖先组件RadioGroup<T>，由RadioGroup统一管理组内选中值与变更回调。

仓库中的实现证据：

• packages/flutter/lib/src/widgets/radio_group.dart 定义了RadioGroup<T>，构造参数为groupValue、onChanged与child；
• packages/flutter/lib/src/material/radio.dart 中Radio.groupValue与Radio.onChanged均带弃用注解（提示 "Use a RadioGroup ancestor to manage group value instead." / "Use RadioGroup to handle value change instead."）；
• RadioGroup额外带来了符合 ARIA APG 规范的键盘导航（Tab/方向键/Space，见 radio_group.dart）与无障碍语义支持。

迁移示例：

// 旧写法（3.35 起弃用） Radio<String>( value: 'a', groupValue: _selected, onChanged: (v) => setState(() => _selected = v), ); // 新写法 RadioGroup<String>( groupValue: _selected, onChanged: (v) => setState(() => _selected = v), child: Row( children: [ Radio<String>(value: 'a'), Radio<String>(value: 'b'), ], ), );

4.5 删除语义（Semantics）的 elevation 与 thickness（需要适配）

Semantics节点上的elevation（海拔）与thickness（厚度）属性被删除。这两项原本服务于无障碍层对组件"凸起感"的描述，因实际消费场景有限被移除。使用到Semantics(elevation: ...)或相关语义属性的代码需要删除对应参数。

4.6 Form 组件不再支持作为 sliver 使用（需要适配）

Form不再支持以 sliver 形式出现在滚动视图（如CustomScrollView）中。此前Form依赖的语义合并行为与 sliver 懒加载机制冲突，官方决定移除该用法。如果你的布局中把Form直接作为SliverList/CustomScrollView的 sliver child，需要改为在普通Column/ListView中承载Form，或将语义合并逻辑下沉到具体字段组件。

4.7 Android 构建默认设置 abiFilters（无需适配）

3.35 起，Android 构建默认设置了abiFilters（ABI 过滤），默认只打包构建目标设备/任务对应的 ABI，从而缩小 APK 体积。该变更由 Gradle 插件自动处理，应用无需改动；仅当你的工程在build.gradle中显式覆盖了abiFilters时，需确认覆盖值仍符合发布要求。

4.8 macOS 与 Windows 上的合并线程（无需适配）

3.35 在 macOS 与 Windows 平台将部分引擎线程合并（如将 UI 线程与平台线程合并调度），以减少线程切换开销。该变更由引擎侧处理，Dart 侧代码无需改动。对于使用平台通道（platform channel）高频通信的桌面应用，可以关注帧率与延迟表现；仓库中桌面平台的相关宿主工程可参考 examples/flutter_view/macos 与 examples/flutter_view/windows。

4.9 Visibility 在 maintainState 下默认不再可聚焦（需要适配）

行为变更：当Visibility.maintainState为true时，隐藏的子组件默认不再保持可聚焦（focusable）。此前即使组件不可见，只要maintainState开启，焦点仍可落入隐藏子树，导致键盘/读屏焦点"掉进"不可见区域。

仓库实现 packages/flutter/lib/src/widgets/visibility.dart 中，可见性通过ExcludeFocus(excluding: !visible && !maintainFocusability, child: child)控制焦点排除；新增的maintainFocusability参数（L70）默认false，即maintainState开启时默认排除焦点。若确实需要隐藏后仍可聚焦，需显式设置maintainFocusability: true（注意其依赖maintainState）。

迁移示例：

// 3.35 起默认行为：隐藏后不可聚焦 Visibility(visible: false, maintainState: true, child: child); // 需要隐藏后仍可聚焦时 Visibility( visible: false, maintainState: true, maintainFocusability: true, // 必须同时开启 maintainState child: child, );

4.10 $FLUTTER_ROOT/version 被 bin/cache/flutter.version.json 取代（需要适配）

Flutter SDK 根目录下的version文本文件被bin/cache/flutter.version.json取代。读取 SDK 版本号的脚本、CI 与本地化工具需要改为解析 JSON 文件中的flutterVersion字段。

仓库源码 packages/flutter_tools/lib/src/version.dart 中，getVersionFile明确返回flutterRoot/bin/cache/flutter.version.json；SDK 版本解析逻辑（version.dart 处GitTagVersion.parse(manifest['flutterVersion'])）也从该 JSON 读取版本信息。如果你的脚本此前读取$FLUTTER_ROOT/version，请改为：

# 旧方式（3.35 起失效） cat $FLUTTER_ROOT/version # 新方式 python3 -c "import json;print(json.load(open('$FLUTTER_ROOT/bin/cache/flutter.version.json'))['flutterVersion'])"

五、升级与适配路线图

综合 26 项变更，建议按以下顺序完成 CPF-Flutter 仓库对应 SDK 版本的升级适配：

1. 先升级后分析：切换 SDK 后立刻运行flutter analyze，利用@Deprecated注解一次性定位第 2.2～4.9 节中所有"需要适配"的 API 调用点；
2. 借助自动修复：本仓库 flutter 包中提供了多处 fix_data 规则（如 fix_expansion_tile.yaml、fix_input_decoration.yaml），IDE 会提示一键迁移 ExpansionTileController→ExpansibleController、maintainHintHeight→maintainHintSize 等机械性改动；
3. 重点回归三类行为：主题视觉（2.3/2.5/2.6/3.4/4.1/4.3）、表单与选择控件（3.2/3.9/4.2/4.4/4.6）、焦点与无障碍（4.5/4.9）；
4. 更新外部依赖：插件清单（3.6）、本地化生成路径（3.7）、版本读取脚本（4.10）属于工程级配置改动，需在 CI 中同步验证；
5. 确认无需适配项：2.1、3.1、4.7、4.8 四项由 SDK/引擎自动处理，仅需在 Release Notes 中记录，供团队知晓行为变化即可。

完成上述步骤后，项目即可平滑过渡到 Flutter 3.35 语义，并充分利用该版本在性能（合并线程、ABI 过滤）、组件规范（RadioGroup、Expansible、主题收敛）与开发体验（integration_test golden、统一版本文件）上的改进。

• 跨平台
• 移动开发
• 前端
• UI组件
• OpenHarmony
• 图形学