Flutter 项目配置工具使用指南

Posted Mar 2, 2026

12 min read

📖 目录

flutter_native_splash 启动页配置
flutter_launcher_icons 应用图标配置
change_app_package_name 包名修改
常见问题速查
最佳实践与自动化脚本

flutter_native_splash 启动页配置

📌 基本介绍

flutter_native_splash 用于自定义 Flutter 应用启动时的原生启动页。从点击应用图标到 Flutter 框架初始化完成之间，会显示这个启动页。

⚠️ 核心注意事项（经验总结）

1. Android 12+ 的特殊处理

❗最重要的问题：Android 12+ 使用全新的 SplashScreen API，原生不支持 **background_image** 全屏背景图，只支持"背景色 + 居中圆形图标"的设计规范。

如果你坚持需要全屏背景图，需要在每次生成后手动修改配置文件：

yaml

  
# pubspec.yaml 配置 flutter_native_splash: android: true android_12: background_image: assets/images/splash.png # 配置全屏背景 

手动修复步骤（必须！）：

bash

  
# 1. 生成启动页配置 dart run flutter_native_splash:create # 2. 编辑 android/app/src/main/res/values-v31/style.xml # 在 LaunchTheme 中添加关键行： 

xml

  
<style name="LaunchTheme" parent="@android:style/Theme.Light.NoTitleBar"> <!-- ⚠️ 必须添加这一行！否则 Android 12+ 会白屏 --> <item name="android:windowBackground">@drawable/launch_background</item> <item name="android:forceDarkAllowed">false</item> <item name="android:windowFullscreen">false</item> <!-- ... 其他配置 --> </style> 

2. Android 图片资源分布说明（常见误解）

✅正常现象：使用 background_image 或 image 配置后，插件会自动生成多分辨率适配的图片，不会全部放在 **drawable** 目录下。

text

android/app/src/main/res/
├── drawable-hdpi/
│   └── splash.png          # 高分辨率设备
├── drawable-mdpi/
│   └── splash.png          # 中分辨率设备
├── drawable-xhdpi/
│   └── splash.png          # 超高分辨率设备
├── drawable-xxhdpi/
│   └── splash.png          # 超超高分辨率设备
└── drawable/
    └── launch_background.xml  # 配置文件，引用 @drawable/splash

💡说明：drawable 目录下看不到 splash.png 是完全正常的，因为图片按分辨率分散在各个目录中，Android 系统会自动选择合适的版本。

3. iOS 的稳定实现方案

✅经验总结：iOS 上 color + image 使用的是 LaunchScreen.storyboard 的标准实现，比直接使用 background_image 更稳定。

yaml

  
# iOS 推荐配置（经过验证的稳定方案） flutter_native_splash: ios: true color: "#42a5f5" # 背景色作为后备（防止黑屏） image: assets/images/splash.png ios_content_mode: scaleAspectFill # 图片全屏显示 

💡为什么这个方案更好：

安全性：即使图片加载失败，也会显示背景色，不会黑屏
效果：scaleAspectFill 效果等同于全屏背景图
兼容性：使用系统的标准实现，与 iOS 版本无关

4. Android 图片拉伸控制

yaml

  
flutter_native_splash: android: true android_gravity: fill # 关键参数：让图片填满屏幕 # 可选值说明： # - fill: 填满屏幕（可能变形） # - center: 居中显示（可能有留白） # - center_crop: 居中裁剪填满（推荐） # - fill_horizontal: 水平填满 # - fill_vertical: 垂直填满 

📝 完整配置示例（经过验证）

yaml

  
flutter_native_splash: web: false # iOS 配置（稳定方案） ios: true color: "#42a5f5" image: assets/images/splash.png ios_content_mode: scaleAspectFill # Android 配置 android: true android_gravity: fill # Android 12+ 全屏（需要手动修复） android_12: background_image: assets/images/splash.png # ⚠️ 重要提醒：每次生成后必须手动在 values-v31/style.xml 添加： # <item name="android:windowBackground">@drawable/launch_background</item> 

🔧 常用命令

bash

  
# 创建启动页 dart run flutter_native_splash:create # 移除启动页 dart run flutter_native_splash:remove # 清理并重新生成（解决大部分问题） flutter clean dart run flutter_native_splash:remove dart run flutter_native_splash:create 

flutter_launcher_icons 应用图标配置

📌 基本配置

yaml

  
flutter_launcher_icons: android: true ios: true image_path: "assets/images/logo.png" # 自适应图标（Android 8.0+ 推荐） adaptive_icon_background: "#FFFFFF" # 或图片路径 adaptive_icon_foreground: "assets/images/logo_foreground.png" # iOS 去背景（避免黑底） remove_alpha_ios: true 

⚠️ 注意事项

1. 图片尺寸要求

Android：提供 192x192px 的图标即可，插件自动生成各种尺寸
iOS：需要 1024x1024px（App Store 要求）

2. Android 自适应图标

yaml

  
flutter_launcher_icons: android: true # 方案一：简单配置（自动处理背景） image_path: "assets/images/logo.png" # 方案二：自适应图标（推荐，避免变形） adaptive_icon_background: "#FFFFFF" adaptive_icon_foreground: "assets/images/logo_foreground.png" 

经验：如果 logo 有透明背景，强烈建议使用自适应图标配置，避免在某些设备上显示异常。

3. iOS 图标去背景

yaml

  
flutter_launcher_icons: ios: true image_path: "assets/images/logo.png" remove_alpha_ios: true # 移除透明背景，避免出现黑底 

🔧 命令

bash

# 生成图标 dart run flutter_launcher_icons # 如果图标不更新，先清理 flutter clean dart run flutter_launcher_icons 

change_app_package_name 包名修改

📌 基本用法

bash

# 修改 Android 包名 dart run change_app_package_name:main com.yourcompany.appname 

⚠️ 重要注意事项

1. 影响范围

只修改 Android：这个工具只修改 Android 的包名
iOS 需要手动：Bundle Identifier 需要自己在 Xcode 中修改

2. 修改后的完整流程

bash

  
# 1. 修改 Android 包名 dart run change_app_package_name:main com.xata.newapp # 2. 手动修改 iOS Bundle Identifier # 用 Xcode 打开 ios/Runner.xcworkspace # General → Identity → Bundle Identifier # 3. 清理项目 flutter clean rm -rf ios/Pods ios/Podfile.lock # 4. 重新获取依赖 flutter pub get cd ios && pod install && cd .. # 5. 更新第三方服务配置（如使用 Firebase） # - 重新下载 google-services.json 放到 android/app/ # - 重新下载 GoogleService-Info.plist 放到 ios/Runner/ 

常见问题速查

🚨 flutter_native_splash

🚨 flutter_launcher_icons

🚨 change_app_package_name

最佳实践与自动化脚本

📋 执行顺序建议

bash

  
# 新项目初始化顺序 1. dart run change_app_package_name:main com.company.appname # 先改包名 2. dart run flutter_launcher_icons # 再生成图标 3. dart run flutter_native_splash:create # 最后生成启动页 4. # 手动修复 Android 12+（如果需要） 

🤖 自动化脚本（推荐）

创建

setup_splash.sh 文件：

bash

  
#!/bin/bash # Flutter 启动页配置自动化脚本 echo "🚀 开始配置 Flutter 启动页..." # 1. 生成启动页 dart run flutter_native_splash:create # 2. 检查并修复 Android 12+ 配置 STYLES_FILE="android/app/src/main/res/values-v31/style.xml" if [ -f "$STYLES_FILE" ]; then # 检查是否已经包含 windowBackground if ! grep -q "android:windowBackground" "$STYLES_FILE"; then # 备份原文件 cp "$STYLES_FILE" "${STYLES_FILE}.bak" # 添加缺失的配置（兼容 macOS 和 Linux） if [[ "$OSTYPE" == "darwin"* ]]; then # macOS sed -i '' '/<style name="LaunchTheme"/,/<\/style>/s/<item name="android:forceDarkAllowed">/<item name="android:windowBackground">@drawable\/launch_background<\/item>\n &/' "$STYLES_FILE" else # Linux sed -i '/<style name="LaunchTheme"/,/<\/style>/s/<item name="android:forceDarkAllowed">/<item name="android:windowBackground">@drawable\/launch_background<\/item>\n &/' "$STYLES_FILE" fi echo "✅ 已添加 Android 12+ 启动页修复" else echo "✅ Android 12+ 配置已完整" fi fi # 3. 验证生成的文件 echo "📁 生成的图片资源：" ls -la android/app/src/main/res/drawable-*/splash.png 2>/dev/null || echo "⚠️ 请检查图片是否生成" echo "🎉 启动页配置完成！" 

使用方法： bash

chmod +x setup_splash.sh ./setup_splash.sh

📝 项目 README 模板

markdown

  
## 🎨 启动页配置说明 ### Android 12+ 特殊处理 每次运行 `dart run flutter_native_splash:create` 后，需要手动添加： - 文件：`android/app/src/main/res/values-v31/style.xml` - 在 `LaunchTheme` 中添加： `<item name="android:windowBackground">@drawable/launch_background</item>` ### 自动化脚本 运行 `./setup_splash.sh` 可自动完成生成和修复。 ### 验证清单 - [ ] iOS 启动页正常显示（背景色 + 全屏图片） - [ ] Android 低版本启动页正常显示（全屏图片） - [ ] Android 12+ 启动页正常显示（需手动修复） 

## 🎨 启动页配置说明

### Android 12+ 特殊处理
每次运行 `dart run flutter_native_splash:create` 后，需要手动添加：
- 文件：`android/app/src/main/res/values-v31/style.xml`
- 在 `LaunchTheme` 中添加：
  `<item name="android:windowBackground">@drawable/launch_background</item>`

### 自动化脚本
运行 `./setup_splash.sh` 可自动完成生成和修复。

### 验证清单
- [ ] iOS 启动页正常显示（背景色 + 全屏图片）
- [ ] Android 低版本启动页正常显示（全屏图片）
- [ ] Android 12+ 启动页正常显示（需手动修复）

教程

flutter flutter_native_splash

This post is licensed under CC BY 4.0 by the author.

📖 目录

flutter_native_splash 启动页配置

📌 基本介绍

⚠️ 核心注意事项（经验总结）

1. Android 12+ 的特殊处理

2. Android 图片资源分布说明（常见误解）

3. iOS 的稳定实现方案

4. Android 图片拉伸控制

📝 完整配置示例（经过验证）

🔧 常用命令

flutter_launcher_icons 应用图标配置

📌 基本配置

⚠️ 注意事项

1. 图片尺寸要求

2. Android 自适应图标

3. iOS 图标去背景

🔧 命令

change_app_package_name 包名修改

📌 基本用法

⚠️ 重要注意事项

1. 影响范围

2. 修改后的完整流程

常见问题速查

🚨 flutter_native_splash

🚨 flutter_launcher_icons

🚨 change_app_package_name

最佳实践与自动化脚本

📋 执行顺序建议

🤖 自动化脚本（推荐）

📝 项目 README 模板

Trending Tags