This app uses deprecated Android embedding v1, causing build warnings.

Question

问题：This app uses deprecated Android embedding v1, causing build warnings. 是什么导致该警告，如何解决？ 当使用 Flutter 创建的 Android 应用在构建时出现“This app uses deprecated Android embedding v1, causing build warnings.”提示，说明项目仍在使用已弃用的 Android Embedding v1。自 Flutter 2.5 起，官方推荐使用更稳定、性能更好的 v2 embedding。该问题通常源于旧项目未升级 Android 入口代码。解决方法包括：更新 `AndroidManifest.xml` 中的 `io.flutter.app.FlutterApplication` 引用，确保 `MainActivity.kt` 或 `MainActivity.java` 使用 `FlutterActivity` 并继承自 v2 embedding，同时确认 `android/app/src/main/res/values/strings.xml` 等配置正确。完成迁移后，重建项目即可消除警告。

Answer 1

1. 警告的表层含义与触发条件

当你在构建 Flutter Android 应用时看到如下警告：

This app uses deprecated Android embedding v1, causing build warnings.

这表示你的项目仍在使用 Flutter 的旧版 Android Embedding（v1），而自 Flutter 2.5 起，官方已将其标记为弃用。该机制负责将 Flutter 引擎嵌入到原生 Android 容器中，v1 存在生命周期管理不完善、平台通道不稳定等问题。

v2 Embedding 提供了更清晰的组件化结构、更好的内存管理和插件兼容性，因此迁移是必要的。

2. 根本原因分析：为何仍使用 v1？

• 项目创建时间较早：在 Flutter 2.5 之前创建的项目默认使用 v1。
• 未执行迁移脚本：开发者可能忽略了升级指南或手动修改出错。
• 第三方插件依赖 v1：某些老旧插件尚未支持 v2，导致回退。
• 自定义 Application 类继承错误基类：如继续使用 io.flutter.app.FlutterApplication。

这些因素共同导致构建系统检测到过时的集成方式并发出警告。

3. 深度解析：v1 与 v2 Embedding 架构差异

对比维度	Embedding v1	Embedding v2
入口类	FlutterActivity / FlutterFragmentActivity	FlutterActivity（新实现）
Application 基类	io.flutter.app.FlutterApplication	无需显式继承（推荐移除）
插件注册时机	运行时反射注册	编译期静态注册（GeneratedPluginRegistrant）
生命周期控制	部分绑定 Activity	完整绑定 FlutterEngine
多引擎支持	困难	原生支持

4. 解决方案：从配置文件到代码全面升级

步骤一：更新 AndroidManifest.xml

检查并删除对旧 Application 的引用：

<application
    android:name="io.flutter.app.FlutterApplication"
    ...
>

若无自定义逻辑，可直接移除 android:name 属性；否则应确保自定义 Application 继承自 FlutterApplication 并适配 v2。

步骤二：升级 MainActivity

确保主 Activity 使用 v2 兼容的入口：

// MainActivity.kt
import io.flutter.embedding.android.FlutterActivity

class MainActivity: FlutterActivity() {
}

或 Java 版本：

// MainActivity.java
import io.flutter.embedding.android.FlutterActivity;

public class MainActivity extends FlutterActivity {
}

步骤三：验证 strings.xml 配置

确认 android/app/src/main/res/values/strings.xml 中包含：

<resources>
    <string name="app_name">Your App Name</string>
</resources>

虽然不直接影响 embedding，但缺失可能导致资源加载异常。

5. 自动化检测与修复建议

Flutter 团队提供了诊断工具帮助识别问题：

flutter doctor -v
flutter create --platforms=android .

后者可在当前项目重新生成 Android 入口代码（保留业务逻辑），自动完成 v2 迁移。

6. 流程图：v1 到 v2 升级决策路径

graph TD A[出现 v1 deprecation warning] --> B{是否为旧项目?} B -- 是 --> C[检查 MainActivity 是否继承 FlutterActivity] B -- 否 --> D[检查 flutter config] C --> E[更新 AndroidManifest.xml] E --> F[移除或重构自定义 Application] F --> G[运行 flutter pub get] G --> H[重建项目] H --> I[验证警告是否消失] I --> J{成功?} J -- 否 --> K[检查插件兼容性] K --> L[升级或替换不兼容插件] L --> G J -- 是 --> M[迁移完成]