引言

在 Flutter 项目里，启动页（Splash Screen）几乎是必做项。

但真正落地到工程时，你会发现如果用“手搓原生方式”去改，各个平台都是一大堆配置文件：

• Android：

• AndroidManifest.xml
• styles.xml
• launch_background.xml

• iOS：

• LaunchScreen.storyboard

• Web：

• index.html
• web/splash/* 相关资源

这些文件不仅繁琐，而且不同平台差异很大。
想要“统一配置、多端自动生成”，基本不可能全靠人手写。

因此在实际 Flutter 开发中，flutter_native_splash 就成了最省心、最主流、也最实战的解决方案：

你只需要在 pubspec.yaml 写一段 Dart 配置，它就会自动帮你生成
Android / iOS / Web 三端的原生启动页。

（桌面端不支持，这一点后文也会讲。）

本文将从零开始，讲透 flutter_native_splash 的所有关键点。

1. flutter_native_splash 是什么？

它是一个 构建期插件（dev_dependencies），作用是：

用 Dart 配置 → 自动生成各平台的启动页资源。

而它会修改的原生内容包括：

平台	修改内容
Android	Manifest、styles.xml、launch_background.xml
iOS	LaunchScreen.storyboard
Web	index.html、web/splash/

你完全无需手写原生端代码，通过配置即可跨平台同步启动页设计。

2. 平台支持情况（非常重要）

平台	支持？	说明
Android	✅ 支持	支持 Android 12+ 强制 SplashScreen API
iOS	✅ 支持	自动生成 LaunchScreen.storyboard
Web	✅ 支持	自动修改 index.html 和生成 splash 资源
Windows	❌ 不支持	桌面端无统一 splash 机制
macOS	❌ 不支持	不支持
Linux	❌ 不支持	不支持

👉 如果你写：

.yaml 文件：

windows: true
macos: true
linux: true

是无效的，插件会忽略。

3. 安装 flutter_native_splash

pubspec.yaml：

dev_dependencies:
  flutter_native_splash: ^2.4.7

然后：

flutter pub get

4. 准备启动图片

例如放在：

assets/images/splash_logo.png
 

要在 pubspec.yaml 声明：

flutter:
  assets:
    - assets/images/splash_logo.png

建议：

• PNG 格式
• 透明背景
• 尺寸 512×512 / 1024×1024
• Logo 居中

5. 最基础的 splash 配置（Android + iOS）
 

flutter_native_splash:
  android: true
  ios: true
  web: false

  color: "#101010"
  image: assets/images/splash_logo.png

执行：

flutter pub run flutter_native_splash:create

即可生成。

6. Android 12+ 必须配置（重点）

Android 12+ 系统强制采用 SplashScreen API：

• 背景色
• 中间一张图标
• 不允许自定义布局
• 不允许整张图铺满屏幕

必须加：

android_12:
  color: "#101010"
  image: assets/images/splash_logo.png

否则 Android 12 很可能出现白底圆形图标（很丑）。

7. Web 端如何使用 flutter_native_splash（支持）

Web 端启动页通过：

• 修改 index.html

• 生成 web/splash 资源

配置：

flutter_native_splash:
  web: true
  color: "#101010"
  image: assets/images/splash_logo.png

  # Web 图像模式
  web_image_mode: cover  # center / contain / stretch / cover

其中：

• center：不缩放（默认 → 小图在中间）
• contain：完整缩放，通常较小
• cover：裁剪铺满（最接近全屏）
• stretch：变形铺满

Web 想图更大 → 推荐 cover。

8. 桌面端为什么不支持？

原因非常明确：

• Windows / macOS / Linux 没有统一的 Splash API

• 桌面端启动速度极快，Splash 场景不强

• Runner 代码差异巨大，无法统一生成启动页

• flutter_native_splash 官方明确不支持桌面端

如果你确实需要桌面启动页：

✔ 只能自己写 Flutter 内部的 SplashPage（App 内部）
✔ 或者自己改 Windows Runner / macOS Runner（成本高，不推荐）

9. 每次改配置后一定要重新生成

只要你动到：

• 图片
• 颜色
• android_12
• web_image_mode
• image_web
• 所有 splash 相关字段

都必须执行：

否则不会更新原生工程。

10. 最终可直接复制使用的配置（推荐模板）

flutter_native_splash:
  android: true
  ios: true
  web: true   # 桌面端不支持，不要写 windows/macos/linux

  # 通用样式
  color: "#101010"
  image: assets/images/splash_logo.png

  # 深色模式
  color_dark: "#000000"
  image_dark: assets/images/splash_logo.png

  # Android 12+ 强制模式
  android_12:
    color: "#101010"
    image: assets/images/splash_logo.png

  # Web 设置图像显示模式
  web_image_mode: cover

11. 文章总结

• flutter_native_splash = 跨平台自动生成原生启动页的工具

• 支持 Android / iOS / Web，不支持桌面端

• Android 12+ 启动页只能“背景色 + 居中图标”

• Web 端可用 web_image_mode 调整图像显示方式

• 每次改配置要重新执行 flutter_native_splash:create