Flutter 构建错误解决方案：native assets 功能启用

原创已于 2025-11-25 16:40:00 修改 · 781 阅读

26 ·

CC 4.0 BY-SA版权

文章标签：

#flutter #android

于 2025-11-25 15:30:12 首次发布

Flutter 构建错误解决方案：native assets 功能启用

📋 问题描述

在构建 Flutter 项目时遇到以下错误：

Target dart_build failed: Error: Package(s) objective_c require the native assets feature to be enabled. 
Enable using `flutter config --enable-native-assets`.

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':app:compileFlutterBuildQaDebug'.
> Process 'command 'E:\Flutter\FlutterSDK\default\bin\flutter.bat'' finished with non-zero exit value 1

🔍 问题原因分析

根本原因

依赖包要求：objective_c 包（由 path_provider_foundation 间接依赖）需要启用 native assets 功能
通道限制：native assets 功能仅在 Flutter 的 master 和 beta 通道可用，在 stable 通道不可用
配置状态：即使启用了 native assets，在 stable 通道中也会显示为 (Unavailable)

依赖关系链

path_provider (直接依赖)
  └── path_provider_foundation (iOS 平台实现)
      └── objective_c (需要 native assets)

✅ 解决方案

方案一：切换到 Beta 通道（推荐）

这是最直接的解决方案，因为 beta 通道支持 native assets 功能。

步骤 1：启用 native assets 功能

flutter config --enable-native-assets

步骤 2：切换到 beta 通道

flutter channel beta

步骤 3：升级到最新 beta 版本

flutter upgrade

步骤 4：清理构建缓存

flutter clean

步骤 5：刷新依赖

flutter pub get

步骤 6：验证配置

flutter config --list

确认 enable-native-assets: true（不再显示 Unavailable）

方案二：切换到 Master 通道（仅限开发环境）

如果需要最新的功能，可以切换到 master 通道：

flutter channel master
flutter upgrade
flutter clean
flutter pub get

注意：master 通道是开发分支，可能不够稳定，不建议用于生产环境。

方案三：等待 Stable 通道支持（长期方案）

如果必须使用 stable 通道，需要等待 Flutter 团队将 native assets 功能合并到 stable 通道。可以关注 Flutter 的发布说明。

🔧 验证步骤

1. 检查 Flutter 通道

flutter channel

应该显示：

* beta (updated monthly, recommended for experienced users)

2. 检查 Flutter 版本

flutter --version

应该显示 beta 通道的版本，例如：

Flutter 3.39.0-0.1.pre • channel beta

3. 检查 native assets 配置

flutter config --list

应该显示：

enable-native-assets: true

（不再显示 (Unavailable)）

4. 尝试构建项目

flutter build apk
# 或
flutter build appbundle
# 或
flutter run

📝 注意事项

⚠️ 重要提醒

通道切换影响：
- 切换到 beta 通道后，Flutter SDK 版本会更新
- 可能需要重新同步项目依赖
- 某些 API 可能有变化，需要检查代码兼容性
团队协作：
- 如果团队其他成员也在开发，建议统一使用相同的 Flutter 通道
- 在项目文档中记录使用的通道和版本
生产环境：
- Beta 通道相对稳定，但建议在发布前充分测试
- 如果对稳定性要求极高，考虑等待 stable 通道支持
依赖更新：
- 切换通道后，某些依赖包可能需要更新
- 运行 flutter pub outdated 查看可更新的包

🔄 回退到 Stable 通道

如果需要回退到 stable 通道：

flutter channel stable
flutter upgrade
flutter clean
flutter pub get

注意：回退后 native assets 将不可用，构建错误会再次出现。

🐛 常见问题

Q1: 切换通道后构建仍然失败？

A: 尝试以下步骤：

完全清理项目：flutter clean
删除 .dart_tool 目录
删除 pubspec.lock 并重新运行 flutter pub get
检查是否有其他依赖冲突

Q2: 如何查看哪些包依赖了 objective_c？

A: 运行以下命令：

flutter pub deps | Select-String -Pattern "objective_c" -Context 5

Q3: 可以在 stable 通道使用其他版本的 path_provider 吗？

A: 可以尝试，但 path_provider_foundation 的新版本都依赖 objective_c。如果必须使用 stable 通道，可能需要：

使用较旧版本的 path_provider
降低 path_provider_foundation 版本以避免 objective_c 依赖（需要 native assets）
2.5.0 版本引入了 objective_c 依赖，2.4.2 版本不依赖 objective_c

dependency_overrides:
 path_provider_foundation: 2.4.2

或等待 stable 通道支持 native assets

Q4: Native assets 功能是什么？

A: Native assets 是 Flutter 的一个实验性功能，允许 Dart 包直接使用原生代码资源。它简化了原生代码的集成过程。

📚 相关资源

Flutter 官方文档 - Native Assets
[Flutter 通道说明](https://docs.flutter.dev/release/ channels)
path_provider 包文档
objective_c 包文档

Flutter 初始化失败：DisableMergedPlatformUIThread 错误

📋 问题描述

在运行 Flutter 应用时遇到以下错误：

E/FlutterLoader(31835): java.lang.IllegalArgumentException: io.flutter.embedding.android.DisableMergedPlatformUIThread is no longer allowed.

E/AndroidRuntime(31835): FATAL EXCEPTION: main
E/AndroidRuntime(31835): Process: com.sales.top.dev, PID: 31835
E/AndroidRuntime(31835): java.lang.RuntimeException: Unable to start activity ComponentInfo{com.sales.top.dev/com.sales.top.MainActivity}: java.lang.RuntimeException: java.lang.IllegalArgumentException: io.flutter.embedding.android.DisableMergedPlatformUIThread is no longer allowed.

🔍 问题原因分析

根本原因

废弃的配置项：DisableMergedPlatformUIThread 是 Flutter 的一个旧配置选项，在新版本的 Flutter 中已被移除
配置文件位置：该配置通常出现在 AndroidManifest.xml 文件中
版本兼容性：升级到新版本的 Flutter（特别是 beta 通道）后，这个配置不再被支持

错误位置

该配置通常出现在以下文件中：

android/app/src/debug/AndroidManifest.xml
android/app/src/main/AndroidManifest.xml
android/app/src/profile/AndroidManifest.xml

✅ 解决方案

步骤 1：查找并删除废弃配置

在所有 AndroidManifest.xml 文件中查找以下配置：

<meta-data
    android:name="io.flutter.embedding.android.DisableMergedPlatformUIThread"
    android:value="true" />

步骤 2：删除配置项

找到后，直接删除整个 <meta-data> 标签块。

示例（删除前）：

<meta-data
    android:name="com.aliyun.alivc_env"
    android:value="SEA"/>
<meta-data
    android:name="io.flutter.embedding.android.DisableMergedPlatformUIThread"
    android:value="true" />

示例（删除后）：

<meta-data
    android:name="com.aliyun.alivc_env"
    android:value="SEA"/>

步骤 3：清理并重新构建

flutter clean
flutter pub get
flutter run

🔧 验证步骤

1. 搜索是否还有残留配置

在项目根目录运行：

# Windows PowerShell
Select-String -Path "android\app\src\**\AndroidManifest.xml" -Pattern "DisableMergedPlatformUIThread"

# Linux/Mac
grep -r "DisableMergedPlatformUIThread" android/app/src/

如果没有输出，说明已完全删除。

2. 重新运行应用

flutter run

应用应该能够正常启动。

📝 注意事项

⚠️ 重要提醒

为什么这个配置被移除：
- Flutter 团队改进了平台 UI 线程的合并机制
- 这个配置选项不再需要，因为新的实现已经默认优化
影响范围：
- 删除此配置不会影响应用功能
- 实际上，新版本的 Flutter 已经自动处理了相关优化
检查所有构建变体：
- 确保检查 debug、profile 和 main 三个构建变体的 AndroidManifest.xml
- 通常只需要在 debug 变体中删除即可