app-icon

应用图标生成工作流

概述

使用 AI 生成专业的应用图标，并在 Expo 应用中将其配置为适用于 iOS（支持 iOS 26 Liquid Glass）和 Android 平台。

步骤 0：验证 SnapAI 设置（至关重要——请先执行）

SnapAI 是由 Code with Beto 团队开发的免费开源 CLI。它使用用户的 API 密钥，直接调用所选图像提供商。密钥可以本地存储在 ~/.snapai/config.json 中，也可以通过环境变量提供。SnapAI 不收集遥测数据，也没有后端服务。

尝试生成图标之前，请检查 SnapAI 是否已配置：

1. 检查 SnapAI 是否已配置：

npx snapai config --show

2. 如果配置检查失败或未显示 API 密钥：

   • SnapAI 需要 OpenAI API 密钥才能生成图标
   • 询问用户：“SnapAI 需要 OpenAI API 密钥。您有密钥吗？或者需要我帮您设置吗？”

3. 如果用户有 API 密钥：

   • 绝不要要求用户在聊天中、源代码中或将要运行的命令中粘贴密钥
   • 请用户在自己的终端中本地配置：

   npx snapai config --openai-api-key "<their-api-key>"
   

   • 也可以让他们在 shell 或密钥管理器中设置 SNAPAI_API_KEY 或 OPENAI_API_KEY
   • 用户确认设置完成后，在不输出密钥的情况下验证配置：

   npx snapai config --show
   

4. 如果用户需要获取 API 密钥：

   • 指引他们访问：https://platform.openai.com/api-keys
   • 说明：“您需要：
     1. 如果还没有 OpenAI 账户，请先创建一个
     2. 前往 API 密钥部分
     3. 点击“Create new secret key”
     4. 复制密钥（以“sk-”开头）
     5. 在本地完成配置，不要在聊天中分享密钥”

重要说明：

• SnapAI 是开源的。API 请求会直接发送到所选提供商；该工具没有中间后端。
• 该工具本身免费；提供商 API 的使用费用由用户的提供商账户承担。
• 如果 SnapAI 尚未配置，请勿继续生成图标
• 不要在聊天、命令输出、日志或已提交的文件中暴露凭据

步骤 1：了解应用背景

• 阅读 app.json，了解应用名称和当前的图标配置
• 如果上下文不清楚，询问用户应用的用途
• 确定应用的主题、用途和目标美学风格

步骤 2：了解风格偏好

询问用户希望图标采用什么风格。可选风格：

• minimalism - 简洁、受 Apple 启发的极简主义（最多使用 2-3 种颜色）
• glassy - 高级玻璃质感，搭配半透明元素
• gradient - 鲜艳渐变，受 Instagram 启发
• neon - 赛博朋克、未来主义风格，搭配发光效果
• material - Google Material Design
• ios-classic - 传统 iOS 风格，搭配微妙渐变
• pixel - 复古 8 位/16 位游戏美术风格
• geometric - 大胆、棱角分明的构图

也可以让用户提供自定义风格描述。

步骤 3：使用 SnapAI 生成图标

**运行前检查：**运行前确认 SnapAI 已配置（参见步骤 0）

生成一张 背景透明 的 1024x1024 图标（这对两个平台都至关重要）：

npx snapai icon --prompt "YOUR_PROMPT_HERE" --background transparent --output-format png --style STYLE_NAME

重要参数：

• --background transparent - iOS 26 和 Android 自适应图标必须使用
• --output-format png - 确保输出为 PNG 格式
• --style - 可选，用于增强视觉风格
• --quality high - 可选，用于生成最终生产环境图标

图标将保存到 ./assets/icon-[timestamp].png

步骤 4：创建 iOS 26 .icon 文件夹结构

创建新版 iOS 26 Liquid Glass 图标格式：

1. 创建文件夹结构：

mkdir -p assets/app-icon.icon/Assets

2. 复制生成的 PNG：

cp assets/icon-[timestamp].png assets/app-icon.icon/Assets/icon.png

3. 使用以下基本配置创建 assets/app-icon.icon/icon.json：

{
  "fill": "automatic",
  "groups": [
    {
      "layers": [
        {
          "glass": false,
          "image-name": "icon.png",
          "name": "icon"
        }
      ],
      "shadow": {
        "kind": "neutral",
        "opacity": 0.5
      },
      "translucency": {
        "enabled": true,
        "value": 0.5
      }
    }
  ],
  "supported-platforms": {
    "circles": ["watchOS"],
    "squares": "shared"
  }
}

步骤 4.5：创建适配 Android 优化的自适应图标

与 iOS 相比，Android 自适应图标的安全区域更小（约为画布的 66%）。SnapAI 生成的主图标针对 iOS 安全区域进行了优化，因此在使用圆形或圆角方形遮罩的 Android 设备上，图标可能显得过大并被裁切。

为确保图标在所有 Android 设备形状（圆形、圆角方形、圆角矩形）上都能正确显示，请创建一个缩小版：

使用 ImageMagick（推荐）：

# Scale the icon to 66% and center it on a 1024x1024 transparent canvas
magick assets/icon-[timestamp].png \
  -resize 66% \
  -gravity center \
  -background transparent \
  -extent 1024x1024 \
  assets/android-icon.png

替代方案 - 使用 sips + ImageMagick（macOS）：

# Step 1: Resize to 66% (676x676)
sips -Z 676 assets/icon-[timestamp].png --out /tmp/icon-resized.png

# Step 2: Create the final centered image
magick -size 1024x1024 xc:transparent /tmp/icon-resized.png \
  -gravity center -composite assets/android-icon.png

**注意：**如果尚未安装 ImageMagick，请使用以下命令安装：

brew install imagemagick

步骤 5：更新 app.json

更新 app.json，为两个平台配置图标：

对于 iOS：

{
  "expo": {
    "ios": {
      "icon": "./assets/app-icon.icon"
    }
  }
}

对于 Android：

使用步骤 4.5 中创建的 Android 优化图标：

选项 1：简单（使用纯色背景）

{
  "expo": {
    "android": {
      "adaptiveIcon": {
        "foregroundImage": "./assets/android-icon.png",
        "backgroundColor": "#ffffff"
      }
    }
  }
}

选项 2：完整（推荐） 由于图标背景透明，可将其用于全部三个 Android 自适应图标字段：

{
  "expo": {
    "android": {
      "adaptiveIcon": {
        "foregroundImage": "./assets/android-icon.png",
        "backgroundImage": "./assets/android-icon.png",
        "monochromeImage": "./assets/android-icon.png"
      }
    }
  }
}

选项 2 的优点：

• foregroundImage - 显示的主图标
• backgroundImage - 在 Android 8.0+ 上提供分层深度效果
• monochromeImage - 用于 Android 13+ 上的主题图标（由系统自动重新着色）

注意：

• 对于选项 1，请询问用户偏好的 backgroundColor，或默认使用白色（#ffffff）
• 对于选项 2，同一个透明 PNG 可完美用于全部三个字段
• 选项 2 与 Android 的 Material You 主题集成效果更好

步骤 6：验证和测试

1. 验证文件夹结构是否存在：

ls -la assets/app-icon.icon/

2. 验证 app.json 是否为有效的 JSON：

cat app.json | jq .

3. 告知用户使用以下命令测试应用：

npx expo prebuild --clean
npx expo run:ios
npx expo run:android

重要说明

• 透明背景至关重要 - 图标必须具有透明背景，才能同时支持 iOS Liquid Glass 效果和 Android 自适应图标
• iOS 26 .icon 格式 - .icon 文件夹可在 iOS 26+ 上启用 Liquid Glass 效果
• 双资源工作流 - 此技能会生成两个图标资源：
  • icon-[timestamp].png - 针对 iOS 安全区域优化的主图标（用于 .icon 文件夹）
  • android-icon.png - 缩小至 66% 并居中，以适配 Android 自适应图标安全区域
• 为何需要两个资源？ - iOS 和 Android 的安全区域不同。iOS 允许内容靠近边缘（约 80-85%），而由于遮罩较严格（圆形、圆角方形等），Android 自适应图标只能保证中心约 66% 的区域可见
• Android 自适应图标的灵活性 - android-icon.png 可用于 foregroundImage、backgroundImage 和 monochromeImage 字段
• Material You 支持 - 使用 monochromeImage 可启用 Android 13+ 主题图标，使其适配用户的配色方案
• 文件命名 - .icon 文件夹名称可以自定义（例如，app-icon.icon、myapp.icon）

故障排除

SnapAI 配置问题

• “未找到 API 密钥” - 请用户在本地运行 npx snapai config --openai-api-key "<key>"，或设置 SNAPAI_API_KEY / OPENAI_API_KEY
• “API 密钥无效” - 请用户在其 OpenAI 账户中验证或轮换密钥，不要在聊天中分享密钥
• 身份验证错误 - 检查 API 密钥是否已撤销，或在 platform.openai.com 上是否有足够的额度
• 找不到命令 - 确保使用的是 npx snapai（而不只是 snapai）

图标显示问题

• 如果图标没有显示，请检查 app.json 中的路径是否与实际文件夹位置一致
• 确保 .icon 文件夹中的 PNG 尺寸恰好为 1024x1024
• 对于 Android，请确保所有图像路径（foregroundImage、backgroundImage、monochromeImage）都正确，并指向现有文件
• 更改图标后，运行 npx expo prebuild --clean 以重新生成原生项目

ImageMagick 问题（用于 Android 图标）

• “convert: command not found” - 使用 brew install imagemagick 安装 ImageMagick
• 权限被拒绝 - 确保你拥有 assets 文件夹的写入权限
• Android 上的图标仍然显示不全 - 尝试将缩放比例从 66% 降至 60%，以更严格地符合安全区域要求