文章

Flutter项目配置工具使用指南

Flutter 项目配置工具使用指南

发表于 更新于
作者 独行的风
11 分钟阅读
Flutter项目配置工具使用指南

Flutter 项目配置工具使用指南

📖 目录

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

flutter_native_splash 启动页配置

📌 基本介绍

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

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

1. Android 12+ 的特殊处理

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

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

1
2
3
4
5

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

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

1
2
3
4
5

# 1. 生成启动页配置
dart run flutter_native_splash:create

# 2. 编辑 android/app/src/main/res/values-v31/style.xml
# 在 LaunchTheme 中添加关键行：

1
2
3
4
5
6
7
8

<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 更稳定。

1
2
3
4
5
6

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

💡****为什么这个方案更好：

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

4. Android 图片拉伸控制

1
2
3
4
5
6
7
8
9

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

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>

🔧 常用命令

1
2
3
4
5
6
7
8
9
10

# 创建启动页
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 应用图标配置

📌 基本配置

1
2
3
4
5
6
7
8
9

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 自适应图标

1
2
3
4
5
6
7
8

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 图标去背景

1
2
3
4

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

🔧 命令

1
2
3
4
5
6

# 生成图标
dart run flutter_launcher_icons

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

change_app_package_name 包名修改

📌 基本用法

1
2

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

⚠️ 重要注意事项

1. 影响范围

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

2. 修改后的完整流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# 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

问题现象可能原因解决方案
Android 12+ 白屏values-v31/style.xml 缺少关键配置手动添加 @drawable/launch_background
iOS 黑屏使用了不稳定的 background_image改用 color + image + scaleAspectFill
Android 图片找不到误解了资源分布检查 drawable-hdpi
等目录，drawable
目录下没有是正常的
图片显示不全或有留白android_gravity
设置不当		添加 android_gravity: fill
或 android_gravity: center_crop
启动页一闪而过正常现象如果需要在启动页停留更久，使用 preserve()
方法

🚨 flutter_launcher_icons

问题现象可能原因解决方案
图标有黑底（iOS）透明背景未处理添加 remove_alpha_ios: true
图标变形（Android）未使用自适应图标配置 adaptive_icon_background
和 adaptive_icon_foreground
图标不更新缓存问题执行 flutter clean
后重新生成

🚨 change_app_package_name

问题现象可能原因解决方案
iOS 包名未变工具只修改 Android手动在 Xcode 中修改 Bundle Identifier
Firebase 服务失效配置文件不匹配重新下载对应包名的配置文件
编译失败缓存未清理执行 flutter clean
后重试

最佳实践与自动化脚本

📋 执行顺序建议

1
2
3
4
5

# 新项目初始化顺序
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 文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

#!/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 "🎉 启动页配置完成！"

使用方法：

1
2

chmod +x setup_splash.sh
./setup_splash.sh

📝 项目 README 模板

markdown

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

## 🎨 启动页配置说明

### 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
本文由作者按照 CC BY 4.0 进行授权