Flutter 修改应用桌面图标 flutter\_launcher\_icons 完整教程

Flutter 修改应用桌面图标 flutter_launcher_icons 完整教程

开发 Flutter 项目的时候，需要改默认的 Android、iOS 图标，手动去各个目录替换不同尺寸图标非常麻烦。flutter_launcher_icons 是社区成熟的命令行工具，只需要准备一张原图，一行命令自动生成 Android /iOS/ Web / Windows / MacOS 多平台全套图标资源，不用手动切图。

一、安装依赖

两种方式任选其一添加依赖：

方式 1：命令添加（推荐）

# 推荐：--dev 指定添加到开发依赖
flutter pub add --dev flutter_launcher_icons

# Dart
dart pub add --dev flutter_launcher_icons
  1. flutter pub add --dev flutter_launcher_icons（传统写法）
  2. flutter pub add dev:flutter_launcher_icons（新版 pub 语法，效果完全一样，支持一行混合添加业务依赖与开发依赖）

执行完成后，会自动在 pubspec.yaml 添加 dev_dependencies：

dev_dependencies:
  flutter_launcher_icons: ^0.14.4

⚠️ 注意：这个是开发依赖 dev_dependencies，不是项目业务依赖，打包时不会打进 App。

二、准备图标素材

在线图标生成工具：https://appicongenerator.org/app-logo-maker

  1. 上传 Logo，生成 1024×1024px PNG 原图

  2. 图标主体不要贴边，预留内边距，避免桌面裁切后显示不全

  3. iOS 图标不能带透明通道，后面配置 remove_alpha_ios: true 自动去除透明

在项目根目录新建文件夹，放入图标： assets/icon/icon.png

不要忘记在 pubspec.yaml 中声明 assets（如果项目其他地方已经声明过可忽略）

flutter:
  assets:
    - assets/icon/

三、配置 flutter_launcher_icons

两种配置方案：新建独立 yaml 文件，或者直接写在 pubspec.yaml 里。

方案 A：自动生成独立配置文件（推荐）

执行命令自动生成 flutter_launcher_icons.yaml

dart run flutter_launcher_icons:generate

  • 自定义配置文件名：dart run flutter_launcher_icons:generate -f my_icon_config.yaml

  • 强制覆盖已有配置文件：dart run flutter_launcher_icons:generate -o

打开 flutter_launcher_icons.yaml，写入配置。

重点：不需要的平台一定要注释或者删掉，否则会阻塞生成，只产出安卓图标 例如只需要 Android + iOS + Web + Windows，把 macos 配置注释：

flutter_launcher_icons:
  android: "launcher_icon"
  ios: true
  image_path: "assets/icon/icon.png"
  min_sdk_android: 21 # android最小sdk，范围16~
  remove_alpha_ios: true # iOS必须关闭透明通道，否则打包报错

  web:
    generate: true
    image_path: "assets/icon/icon.png"
    background_color: "#ffffff"
    theme_color: "#2196F3"

  windows:
    generate: true
    image_path: "assets/icon/icon.png"
    icon_size: 48 # 范围48~256

# macos: # 当前项目不需要mac就注释掉！
#   generate: true
#   image_path: "assets/icon/icon.png"

方案 B：直接写在 pubspec.yaml（简单小项目）

dev_dependencies:
  flutter_launcher_icons: ^0.14.4

flutter_launcher_icons:
  android: "launcher_icon"
  ios: true
  image_path: "assets/icon/icon.png"
  min_sdk_android: 21
  remove_alpha_ios: true

  web:
    generate: true
    image_path: "assets/icon/icon.png"
    background_color: "#ffffff"
    theme_color: "#2196F3"

  windows:
    generate: true
    image_path: "assets/icon/icon.png"
    icon_size: 48

# macos:
#   generate: true
#   image_path: "assets/icon/icon.png"

四、执行命令生成图标

flutter pub get
dart run flutter_launcher_icons

如果你的配置文件不是默认名称，需要通过 -f 指定文件：

dart run flutter_launcher_icons -f my_icon_config.yaml

执行成功后，插件会自动写入：

  • Android：android/app/src/main/res/mipmap-* 系列文件夹

  • iOS：ios/Runner/Assets.xcassets/AppIcon.appiconset

  • Web / Windows / MacOS：对应平台资源目录

五、测试验证 & 常见坑

  1. 模拟器 / 真机看不到新图标：卸载旧 App，重新 flutter run，模拟器 App 图标有缓存，热重载不会更新桌面图标。

  2. 只生成安卓图标，iOS 不生成：检查配置，不需要的平台（macos 等）必须注释，不能空配置占位。

  3. iOS 打包报错，提示图标透明：开启 remove_alpha_ios: true，自动填充背景去除透明通道。

  4. 原图尺寸不对：必须使用 1024×1024 正方形 PNG，不要用长方形图片。

  5. 清理缓存（遇到奇怪问题时执行）

flutter clean
flutter pub get

总结

flutter_launcher_icons 解决 Flutter 多平台 App 图标手动切图的痛点，流程一句话概括： 在线工具导出 1024×1024 图标 → 添加依赖 → 配置 yaml（不需要的平台注释） → 一行命令自动生成全平台图标。

项目地址：https://pub.dev/packages/flutter_launcher_icons 问题反馈：https://github.com/fluttercommunity/flutter_launcher_icons/issues

posted @ 2026-10-08 19:45  FatedCode  阅读(2)  评论(0)    收藏  举报