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
——在检测到的静态资源目录中查找现有清单文件，提取
```
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.

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

[STATIC_DIR]

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

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

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

bash

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

bash

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

favicon-96x96.png

bash

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

bash

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

apple-touch-icon.png (180x180)

apple-touch-icon.png（180x180）

bash

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

bash

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

web-app-manifest-192x192.png

bash

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

bash

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

web-app-manifest-512x512.png

bash

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

bash

magick "$1" -resize 512x512 -background none -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 = {
  // ... 保留现有元数据字段
  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，从图标数组中省略
```
{ url: '/favicon.svg', type: 'image/svg+xml' }
```
这一项
如果不存在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

完成后报告以下内容：

检测到的项目类型与框架
使用的静态资源目录
生成的文件列表
清单文件和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代码