Flutter 项目配置工具使用指南

发表于 2026/03/02

作者 your_full_name

12 分钟阅读

Flutter 项目配置工具使用指南

📖 目录

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

  
# 新项目初始化顺序
dart run change_app_package_name:main com.company.appname  # 先改包名
dart run flutter_launcher_icons                             # 再生成图标
dart run flutter_native_splash:create                       # 最后生成启动页
# 手动修复 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+ 启动页正常显示（需手动修复）

教程, Flutter

flutter flutter_native_splash

本文由作者按照 CC BY 4.0 进行授权

📖 目录

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 模板

热门标签