favicon

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Generate a complete set of favicons from the source image at

$1

and update the project's HTML with the appropriate link tags.

从路径为

$1

的源图片生成一套完整的网站图标（Favicon），并更新项目的HTML文件，添加对应的链接标签。

Prerequisites

前置条件

First, verify ImageMagick v7+ is installed by running:

bash

which magick

If not found, stop and instruct the user to install it:

macOS:
```
brew install imagemagick
```
Linux:
```
sudo apt install imagemagick
```

首先，运行以下命令验证是否已安装ImageMagick v7+版本：

bash

which magick

如果未找到，请停止操作并指导用户安装：

macOS：
```
brew install imagemagick
```
Linux：
```
sudo apt install imagemagick
```

Step 1: Validate Source Image

步骤1：验证源图片

Verify the source image exists at the provided path:
```
$1
```
Check the file extension is a supported format (PNG, JPG, JPEG, SVG, WEBP, GIF)
If the file doesn't exist or isn't a valid image format, report the error and stop

Note whether the source is an SVG file - if so, it will also be copied as

favicon.svg

验证提供的路径
```
$1
```
下是否存在源图片
检查文件扩展名是否为支持的格式（PNG、JPG、JPEG、SVG、WEBP、GIF）
如果文件不存在或格式无效，报错并停止操作

注意源文件是否为SVG格式——如果是，还需要将其复制为

favicon.svg

。

Step 2: Detect Project Type and Static Assets Directory

步骤2：检测项目类型与静态资源目录

Detect the project type and determine where static assets should be placed. Check in this order:

Framework	Detection	Static Assets Directory
Rails	`config/routes.rb` exists	`public/`
Next.js	`next.config.*` exists	`public/`
Gatsby	`gatsby-config.*` exists	`static/`
SvelteKit	`svelte.config.*` exists	`static/`
Astro	`astro.config.*` exists	`public/`
Hugo	`hugo.toml` or `config.toml` with Hugo markers	`static/`
Jekyll	`_config.yml` with Jekyll markers	Root directory (same as `index.html` )
Vite	`vite.config.*` exists	`public/`
Create React App	`package.json` has `react-scripts` dependency	`public/`
Vue CLI	`vue.config.*` exists	`public/`
Angular	`angular.json` exists	`src/assets/`
Eleventy	`.eleventy.js` or `eleventy.config.*` exists	Check `_site` output or root
Static HTML	`index.html` in root	Same directory as `index.html`

Important: If existing favicon files are found (e.g.,

favicon.ico

apple-touch-icon.png

), use their location as the target directory regardless of framework detection.

Report the detected project type and the static assets directory that will be used.

When in doubt, ask: If you are not 100% confident about where static assets should be placed (e.g., ambiguous project structure, multiple potential locations, unfamiliar framework), use

AskUserQuestionTool

to confirm the target directory before proceeding. It's better to ask than to put files in the wrong place.

检测项目类型，确定静态资源的存放位置。按以下顺序检查：

框架	检测方式	静态资源目录
Rails	存在 `config/routes.rb`	`public/`
Next.js	存在 `next.config.*`	`public/`
Gatsby	存在 `gatsby-config.*`	`static/`
SvelteKit	存在 `svelte.config.*`	`static/`
Astro	存在 `astro.config.*`	`public/`
Hugo	存在 `hugo.toml` 或带有Hugo标记的 `config.toml`	`static/`
Jekyll	存在带有Jekyll标记的 `_config.yml`	根目录（与 `index.html` 同级）
Vite	存在 `vite.config.*`	`public/`
Create React App	`package.json` 中包含 `react-scripts` 依赖	`public/`
Vue CLI	存在 `vue.config.*`	`public/`
Angular	存在 `angular.json`	`src/assets/`
Eleventy	存在 `.eleventy.js` 或 `eleventy.config.*`	检查 `_site` 输出目录或根目录
静态HTML	根目录下存在 `index.html`	与 `index.html` 同级目录

重要提示：如果发现已存在的图标文件（如

favicon.ico

、

apple-touch-icon.png

），无论框架检测结果如何，都将其所在位置作为目标目录。

报告检测到的项目类型以及将使用的静态资源目录。

存疑时请询问：如果对静态资源的存放位置没有100%把握（例如项目结构模糊、存在多个潜在位置、不熟悉的框架），请使用

AskUserQuestionTool

确认目标目录后再继续操作。宁可询问也不要将文件放错位置。

Step 3: Determine App Name

步骤3：确定应用名称

Find the app name from these sources (in priority order):

Existing
site.webmanifest
- Check the detected static assets directory for an existing manifest and extract the
```
name
```
field
package.json
- Extract the
```
name
```
field if it exists
Rails
config/application.rb
- Extract the module name (e.g.,
```
module MyApp
```
→ "MyApp")
Directory name - Use the current working directory name as fallback

Convert the name to title case if needed (e.g., "my-app" → "My App").

按以下优先级顺序查找应用名称：

已存在的
site.webmanifest
——在检测到的静态资源目录中查找已存在的manifest文件，提取
```
name
```
字段
package.json
——如果存在，提取
```
name
```
字段
Rails的
config/application.rb
——提取模块名称（例如
```
module MyApp
```
→ "MyApp"）
目录名称——将当前工作目录名称作为备选

必要时将名称转换为标题格式（例如"my-app" → "My App"）。

Step 4: Ensure Static Assets Directory Exists

步骤4：确保静态资源目录存在

Check if the detected static assets directory exists. If not, create it.

检查检测到的静态资源目录是否存在。如果不存在，则创建该目录。

Step 5: Generate Favicon Files

步骤5：生成图标文件

Run these ImageMagick commands to generate all favicon files. Replace

[STATIC_DIR]

with the detected static assets directory from Step 2.

Important: The

-background none

flag must come BEFORE the input file to properly preserve transparency when rendering SVGs. Placing it after the input will result in a white background.

运行以下ImageMagick命令生成所有图标文件。将

[STATIC_DIR]

替换为步骤2中检测到的静态资源目录。

重要提示：

-background none

参数必须放在输入文件之前，才能在渲染SVG时正确保留透明度。如果放在输入文件之后，会导致背景变为白色。

favicon.ico (multi-resolution: 16x16, 32x32, 48x48)

favicon.ico（多分辨率：16x16、32x32、48x48）

bash

magick -background none "$1" \
  \( -clone 0 -resize 16x16 \) \
  \( -clone 0 -resize 32x32 \) \
  \( -clone 0 -resize 48x48 \) \
  -delete 0 -alpha on \
  [STATIC_DIR]/favicon.ico

bash

magick -background none "$1" \
  \( -clone 0 -resize 16x16 \) \
  \( -clone 0 -resize 32x32 \) \
  \( -clone 0 -resize 48x48 \) \
  -delete 0 -alpha on \
  [STATIC_DIR]/favicon.ico

favicon-96x96.png

bash

magick -background none "$1" -resize 96x96 -alpha on [STATIC_DIR]/favicon-96x96.png

bash

magick -background none "$1" -resize 96x96 -alpha on [STATIC_DIR]/favicon-96x96.png

apple-touch-icon.png (180x180)

apple-touch-icon.png（180x180）

bash

magick -background none "$1" -resize 180x180 -alpha on [STATIC_DIR]/apple-touch-icon.png

bash

magick -background none "$1" -resize 180x180 -alpha on [STATIC_DIR]/apple-touch-icon.png

web-app-manifest-192x192.png

bash

magick -background none "$1" -resize 192x192 -alpha on [STATIC_DIR]/web-app-manifest-192x192.png

bash

magick -background none "$1" -resize 192x192 -alpha on [STATIC_DIR]/web-app-manifest-192x192.png

web-app-manifest-512x512.png

bash

magick -background none "$1" -resize 512x512 -alpha on [STATIC_DIR]/web-app-manifest-512x512.png

bash

magick -background none "$1" -resize 512x512 -alpha on [STATIC_DIR]/web-app-manifest-512x512.png

favicon.svg (only if source is SVG)

favicon.svg（仅当源文件为SVG时）

If the source file has a

.svg

extension, copy it:

bash

cp "$1" [STATIC_DIR]/favicon.svg

如果源文件的扩展名为

.svg

，则复制该文件：

bash

cp "$1" [STATIC_DIR]/favicon.svg

Step 6: Create/Update site.webmanifest

步骤6：创建/更新site.webmanifest

Create or update

[STATIC_DIR]/site.webmanifest

with this content (substitute the detected app name):

json

{
  "name": "[APP_NAME]",
  "short_name": "[APP_NAME]",
  "icons": [
    {
      "src": "/web-app-manifest-192x192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "maskable"
    },
    {
      "src": "/web-app-manifest-512x512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "maskable"
    }
  ],
  "theme_color": "#ffffff",
  "background_color": "#ffffff",
  "display": "standalone"
}

site.webmanifest

already exists in the static directory, preserve the existing

theme_color

background_color

, and

display

values while updating the

name

short_name

, and

icons

array.

使用以下内容创建或更新

[STATIC_DIR]/site.webmanifest

（替换为检测到的应用名称）：

json

{
  "name": "[APP_NAME]",
  "short_name": "[APP_NAME]",
  "icons": [
    {
      "src": "/web-app-manifest-192x192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "maskable"
    },
    {
      "src": "/web-app-manifest-512x512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "maskable"
    }
  ],
  "theme_color": "#ffffff",
  "background_color": "#ffffff",
  "display": "standalone"
}

如果静态资源目录中已存在

site.webmanifest

，保留现有的

theme_color

、

background_color

和

display

值，同时更新

name

、

short_name

和

icons

数组。

Step 7: Update HTML/Layout Files

步骤7：更新HTML/布局文件

Based on the detected project type, update the appropriate file. Adjust the

href

paths based on where the static assets directory is relative to the web root:

If static files are in
```
public/
```
or
```
static/
```
and served from root → use
```
/favicon.ico
```
If static files are in
```
src/assets/
```
→ use
```
/assets/favicon.ico
```
If static files are in the same directory as HTML → use
```
./favicon.ico
```
or just
```
favicon.ico
```

根据检测到的项目类型，更新对应的文件。根据静态资源目录相对于网站根目录的位置调整

href

路径：

如果静态文件位于
```
public/
```
或
```
static/
```
并从根目录提供服务 → 使用
```
/favicon.ico
```
如果静态文件位于
```
src/assets/
```
→ 使用
```
/assets/favicon.ico
```
如果静态文件与HTML文件在同一目录 → 使用
```
./favicon.ico
```
或直接使用
```
favicon.ico
```

For Rails Projects

对于Rails项目

Edit

app/views/layouts/application.html.erb

. Find the

<head>

section and add/replace favicon-related tags with:

html

<link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96" />
<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
<link rel="shortcut icon" href="/favicon.ico" />
<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png" />
<meta name="apple-mobile-web-app-title" content="[APP_NAME]" />
<link rel="manifest" href="/site.webmanifest" />

Important:

If the source was NOT an SVG, omit the

<link rel="icon" type="image/svg+xml" href="/favicon.svg" />

line

Remove any existing

<link rel="icon"

<link rel="shortcut icon"

<link rel="apple-touch-icon"

, or

<link rel="manifest"

tags before adding the new ones

Place these tags near the top of the
```
<head>
```
section, after
```
<meta charset>
```
and
```
<meta name="viewport">
```
if present

编辑

app/views/layouts/application.html.erb

。找到

<head>

部分，添加/替换与图标相关的标签：

html

<link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96" />
<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
<link rel="shortcut icon" href="/favicon.ico" />
<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png" />
<meta name="apple-mobile-web-app-title" content="[APP_NAME]" />
<link rel="manifest" href="/site.webmanifest" />

重要提示：

如果源文件不是SVG格式，省略

<link rel="icon" type="image/svg+xml" href="/favicon.svg" />

这一行

在添加新标签之前，删除所有已存在的

<link rel="icon">

、

<link rel="shortcut icon">

、

<link rel="apple-touch-icon">

或

<link rel="manifest">

标签

将这些标签放在
```
<head>
```
部分的顶部，位于
```
<meta charset>
```
和
```
<meta name="viewport">
```
（如果存在）之后

For Next.js Projects

对于Next.js项目

Edit the detected layout file (

app/layout.tsx

src/app/layout.tsx

). Update or add the

metadata

export to include icons configuration:

typescript

export const metadata: Metadata = {
  // ... keep existing metadata fields
  icons: {
    icon: [
      { url: '/favicon.ico' },
      { url: '/favicon-96x96.png', sizes: '96x96', type: 'image/png' },
      { url: '/favicon.svg', type: 'image/svg+xml' },
    ],
    shortcut: '/favicon.ico',
    apple: '/apple-touch-icon.png',
  },
  manifest: '/site.webmanifest',
  appleWebApp: {
    title: '[APP_NAME]',
  },
};

Important:

If the source was NOT an SVG, omit the
```
{ url: '/favicon.svg', type: 'image/svg+xml' }
```
entry from the icon array
If metadata export doesn't exist, create it with just the icons-related fields
If metadata export exists, merge the icons configuration with existing fields

编辑检测到的布局文件（

app/layout.tsx

或

src/app/layout.tsx

）。更新或添加

metadata

导出，包含图标配置：

typescript

export const metadata: Metadata = {
  // ... 保留现有的metadata字段
  icons: {
    icon: [
      { url: '/favicon.ico' },
      { url: '/favicon-96x96.png', sizes: '96x96', type: 'image/png' },
      { url: '/favicon.svg', type: 'image/svg+xml' },
    ],
    shortcut: '/favicon.ico',
    apple: '/apple-touch-icon.png',
  },
  manifest: '/site.webmanifest',
  appleWebApp: {
    title: '[APP_NAME]',
  },
};

重要提示：

如果源文件不是SVG格式，从icon数组中省略
```
{ url: '/favicon.svg', type: 'image/svg+xml' }
```
这一项
如果不存在metadata导出，则仅创建包含图标相关字段的metadata
如果已存在metadata导出，将图标配置与现有字段合并

For Static HTML Projects

对于静态HTML项目

Edit the detected

index.html

file. Add the same HTML as Rails within the

<head>

section.

编辑检测到的

index.html

文件。在

<head>

部分添加与Rails项目相同的HTML标签。

If No Project Detected

如果未检测到项目

Skip HTML updates and inform the user they need to manually add the following to their HTML

<head>

html

<link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96" />
<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
<link rel="shortcut icon" href="/favicon.ico" />
<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png" />
<meta name="apple-mobile-web-app-title" content="[APP_NAME]" />
<link rel="manifest" href="/site.webmanifest" />

跳过HTML更新步骤，并告知用户需要手动将以下内容添加到HTML的

<head>

部分：

html

<link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96" />
<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
<link rel="shortcut icon" href="/favicon.ico" />
<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png" />
<meta name="apple-mobile-web-app-title" content="[APP_NAME]" />
<link rel="manifest" href="/site.webmanifest" />

Step 8: Summary

步骤8：总结

Report completion with:

Detected project type and framework
Static assets directory used
List of files generated
App name used in manifest and HTML
Layout file updated (or note if manual update is needed)
Note if any existing files were overwritten

操作完成后报告以下内容：

检测到的项目类型和框架
使用的静态资源目录
生成的文件列表
在manifest和HTML中使用的应用名称
更新的布局文件（或注明需要手动更新）
说明是否覆盖了任何现有文件

Error Handling

错误处理

If ImageMagick is not installed, provide installation instructions and stop
If the source image doesn't exist, report the exact path that was tried and stop
If ImageMagick commands fail, report the specific error message
If the layout file cannot be found for HTML updates, generate files anyway and instruct on manual HTML addition

如果未安装ImageMagick，提供安装说明并停止操作
如果源图片不存在，报告尝试的具体路径并停止操作
如果ImageMagick命令执行失败，报告具体的错误信息
如果找不到用于HTML更新的布局文件，仍生成图标文件，并指导用户手动添加HTML标签