创建 Android 自适应图标

前景层加背景层，由启动器统一裁剪

自适应图标是两张尺寸相同的正方形 PNG，像贴纸叠在卡片上一样分层放置：

• 背景层（ic_launcher_background）——纯色、渐变或图案。填满整个 108×108dp 画布。启动器会将这一层裁剪成其偏好的形状。
• 前景层（ic_launcher_foreground）——你的 logo 或图形，叠在上方，除图案外全部透明。

启动器随后用自己的遮罩合成这两层：Pixel 用圆形，Samsung 用圆角方形，Nothing 用水滴形，廉价平板的内置启动器用正方形。你的图标需要在这四种形状下都看起来正确，这正是安全区域规则（第二步）所保护的。

画布大部分会被裁剪——设计时需考虑在内

两层图片均为 108×108dp，但在启动器遮罩应用后，只有内部 66×66dp 的区域才能保证可见。四周各 21dp 的外圈是"出血区"——它的存在是为了让视差动画和动效有足够的移动空间，而不至于露出边缘。

┌──────────────────────────────┐
│  bleed zone (gets clipped)   │  21dp
│   ┌──────────────────────┐   │
│   │                      │   │
│   │   SAFE ZONE          │   │  66dp × 66dp
│   │   (your art lives    │   │  guaranteed visible
│   │    here)             │   │
│   │                      │   │
│   └──────────────────────┘   │
│                              │  21dp
└──────────────────────────────┘
            108dp × 108dp

由此得出：你的 logo 边界框绝对不能超过 66×66dp。一旦超出，Pixel 启动器的圆形遮罩就会裁掉角落。关键元素（文字、细节）应充分保持在安全区域内。那些即便被激进遮罩裁掉也无所谓的装饰性元素，可以延伸到出血区。

具体到 PNG 导出：设计时使用 432×432px（xxxhdpi 密度下 dp 的 4 倍）。66dp 安全区对应画布中心 264×264px 的正方形区域。

res/ 中各文件的位置

一套完整的自适应图标共六个文件，分布在四个目录中：

app/src/main/res/
├── mipmap-anydpi-v26/
│   ├── ic_launcher.xml              ← adaptive icon (foreground + background ref)
│   └── ic_launcher_round.xml        ← same, for circle launchers
├── drawable/
│   └── ic_launcher_foreground.xml   ← vector drawable for foreground
├── values/
│   └── ic_launcher_background.xml   ← color resource for background
└── mipmap-{m,h,xh,xxh,xxxh}dpi/
    ├── ic_launcher.png              ← legacy fallback PNGs
    └── ic_launcher_round.png        ← same, round variant

mipmap-anydpi-v26/ic_launcher.xml 中的自适应 XML 是入口文件，内容如下：

<?xml version="1.0" encoding="utf-8"?>
<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
    <background android:drawable="@color/ic_launcher_background" />
    <foreground android:drawable="@drawable/ic_launcher_foreground" />
</adaptive-icon>

这就是整个接口：指向一个背景（颜色或 drawable）和一个前景 drawable。目录名中的 -v26 后缀告诉构建系统"仅在 API 26 及以上使用此目录"。旧版设备会回退到 mipmap-{density}/ 中的 PNG。

Mobile 菜单 → App Icon Generator… → Android 目标 → 生成

LingCode 的 App Icon Generator 面板——通过菜单栏 Mobile → App Icon Generator… 打开——在处理 iOS 的同一流程中也可生成 Android 自适应图标。如果只需要 Android，关闭 iOS 选项，将 Android 目标指向 app/src/main/res/，然后放入一张 1024×1024 的主图，或者输入提示词让内置图像生成器来创建。

Android 流程会为每个密度桶写入三个文件——ic_launcher.png（旧式正方形）、ic_launcher_round.png（旧式圆形回退）以及 ic_launcher_foreground.png（自适应前景）——覆盖从 mipmap-mdpi 到 mipmap-xxxhdpi 的所有密度。面板会列出每个写入的文件，让你在关闭前确认无误。

面板不会自动完成的两件事：它不会写入自适应 XML（mipmap-anydpi-v26/ic_launcher.xml），也不会写入背景颜色资源。这两个文件都很短——各只需几行（见第三步）——代理可以通过一行对话提示来生成："add the adaptive-icon XML wrappers for ic_launcher and ic_launcher_round, background color #5B6CFF"。两步合并，即可获得完整的自适应图标集。

一条提示词，全套文件

在你的 Android 项目根目录中打开 Claude 对话，然后输入：

Add an adaptive launcher icon to this Android project.
- Foreground: ~/Desktop/logo.svg (already sized for the 66dp safe zone)
- Background color: #5B6CFF
Generate the adaptive XML, the foreground vector drawable, and PNG
fallbacks for mdpi through xxxhdpi.

代理大约会生成八个文件：两个自适应 XML 文件（正方形和圆形）、前景矢量 drawable、背景颜色资源，以及十个 PNG 回退文件（五种密度各一个正方形和一个圆形）。如有需要，它还会修改 AndroidManifest.xml——不过项目模板中通常已经有默认的 android:icon="@mipmap/ic_launcher"。

还没有 logo？先用对话中的 generate_image 工具——"generate a 1024×1024 icon foreground: minimalist letter L glyph in white on transparent background, flat, no shadow, centered with 25% padding"——代理会通过 Gemini 将其保存到 <project>/assets/。满意后，再让它以该文件为基础搭建自适应图标结构。两条提示词，完整图标集到手。

验证方法：打开 app/src/main/res/mipmap-anydpi-v26/ic_launcher.xml，确认 <adaptive-icon> 块引用了你预期的资源。然后构建并安装——参见第六步。

构建、安装并查看启动器效果

在项目中按 ⌘R。运行目标选择器会打开，其中 Android 模拟器部分列出了所有已配置的 AVD——选中后离线 AVD 会自动启动。选择你的 AVD，LingCode 会构建项目、运行 adb install 并启动应用。

按下主屏幕按钮（或根据 AVD 启动器向上滑动），查看应用的启动器图标。你应该能看到前景图标居中叠加在背景上，并被 AVD 启动器裁剪成相应形状。如果图标边缘出现裁剪，说明前景层超出了出血区——将其收缩回 66×66dp 安全区域内。

若想在不重新构建的情况下查看图标在多种启动器遮罩下的效果，可以在 AVD 内从 Play 商店安装一款"启动器图标预览"应用。比维护四台实体设备经济多了。

三种常见故障