#html.favicon

• 类型： string | Function
• 默认值： 自动读取 public 目录下的 favicon 文件

设置所有页面的 favicon 图标，Rsbuild 会根据配置值进行处理：

• URL 地址： 直接引用该 URL，不会下载文件。
• 本地文件路径： 在编译时将文件复制到输出目录。路径可以是绝对路径，也可以是相对于项目 root 的相对路径。

两种情况都会在 HTML 中添加对应的 favicon <link> 标签。

#默认值

在未显式配置 html.favicon 时，Rsbuild 会自动从 public 目录 中查找 favicon 文件。

Rsbuild 会按以下优先级依次搜索文件，并在找到第一个匹配项后将其作为默认 favicon：

• public/favicon.ico
• public/favicon.png
• public/favicon.svg

#示例

设置为相对路径：

export default {
  html: {
    favicon: './src/assets/icon.png',
  },
};

设置为绝对路径：

import path from 'node:path';

export default {
  html: {
    favicon: path.resolve(__dirname, './src/assets/icon.png'),
  },
};

设置为 URL：

export default {
  html: {
    favicon: 'https://foo.com/favicon.ico',
  },
};

重新编译后，HTML 中自动生成了以下标签：

<link rel="icon" href="https://foo.com/favicon.ico" />

#输出路径

默认情况下，favicon 文件会输出到构建产物目录的根路径下，比如：

• ./src/assets/icon.png 会输出到 ./dist/icon.png。
• ./src/assets/favicon.ico 会输出到 ./dist/favicon.ico。

你可以通过 output.distPath.favicon 选项来自定义 favicon 的输出路径：

export default {
  output: {
    distPath: {
      // 将 favicon 输出到 "./dist/static/favicon/" 目录
      favicon: 'static/favicon',
    },
  },
};

#函数用法

• 类型：

type FaviconFunction = (context: {
  value: string;
  entryName: string;
}) => string | void | Promise<string | void>;

当 html.favicon 为 Function 类型时，函数接收一个对象作为入参，对象的值包括：

• value：Rsbuild 的默认 favicon 配置。
• entryName: 当前入口的名称。

在 MPA（多页面应用）场景下，你可以基于入口名称返回不同的 favicon，从而为每个页面生成不同的标签：

export default {
  html: {
    favicon({ entryName }) {
      const icons = {
        foo: 'https://example.com/foo.ico',
        bar: 'https://example.com/bar.ico',
      };
      return icons[entryName] || 'https://example.com/default.ico';
    },
  },
};

#版本历史