Nuxt3模块中如何正确添加bootstrap-icons字体至public目录

核心问题分析 #

你遇到的问题是Nuxt3的Vite构建默认会给静态资源添加哈希后缀，但通过nitro:config复制的bootstrap-icons字体文件未添加哈希，导致CSS中被处理后的带哈希路径找不到对应文件。以下是几个直接有效的解决方法：

方法1：修改Vite资源命名规则，排除字体文件哈希 #

在你的Nuxt模块中，通过vite:extendConfig钩子修改Rollup的资源输出规则，让bootstrap-icons的字体文件保留原文件名（不加哈希）：

export default defineNuxtModule({
  // 模块配置...
  setup(options, nuxt) {
    // 其他模块逻辑...
    
    nuxt.hook('vite:extendConfig', (viteConfig) => {
      viteConfig.build ??= {};
      viteConfig.build.rollupOptions ??= {};
      viteConfig.build.rollupOptions.output ??= {};

      // 自定义资源文件名规则
      viteConfig.build.rollupOptions.output.assetFileNames = (assetInfo) => {
        // 匹配bootstrap-icons的字体文件
        if (assetInfo.name?.match(/bootstrap-icons\.(woff2|woff|ttf)$/)) {
          return 'fonts/[name][extname]'; // 不添加哈希，直接放在fonts目录下
        }
        // 其他资源保留默认哈希规则
        return viteConfig.build.rollupOptions.output.assetFileNames || 'assets/[name]-[hash][extname]';
      };
    });
  }
});

方法2：动态修正CSS中的字体引用路径 #

如果方法1不生效，可以通过Vite插件在构建时修改bootstrap-icons的CSS内容，强制字体引用路径指向正确的无哈希文件名：

export default defineNuxtModule({
  setup(options, nuxt) {
    // 引入bootstrap-icons的CSS（确保路径正确）
    nuxt.options.css.push('bootstrap-icons/font/bootstrap-icons.min.css');

    nuxt.hook('vite:extendConfig', (viteConfig) => {
      viteConfig.plugins ??= [];
      viteConfig.plugins.push({
        name: 'fix-bootstrap-icons-font-path',
        transform(code, id) {
          // 只处理bootstrap-icons的CSS文件
          if (id.includes('bootstrap-icons.min.css')) {
            // 替换CSS中的字体引用路径为绝对路径，指向无哈希的字体文件
            return code.replace(/url\(['"]?([^'"]+\.(woff2|woff|ttf))['"]?\)/g, 'url("/fonts/$1")');
          }
          return code;
        }
      });
    });

    // 确保字体文件被复制到public/fonts目录
    nuxt.hook('nitro:config', (nitroConfig) => {
      nitroConfig.publicAssets ??= [];
      nitroConfig.publicAssets.push({
        dir: require.resolve('bootstrap-icons/font/fonts'),
        baseURL: '/fonts',
        options: { filename: '[name][extname]' } // 强制保留原文件名
      });
    });
  }
});

方法3：禁用特定资源的哈希处理（全局配置） #

如果你不想写自定义插件，也可以在模块中修改Nuxt的Vite配置，直接给字体文件禁用哈希：

export default defineNuxtModule({
  setup(options, nuxt) {
    nuxt.hook('nuxt:config', (config) => {
      config.vite ??= {};
      config.vite.build ??= {};
      config.vite.build.assetsDir = 'assets';
      // 针对字体文件设置不添加哈希
      config.vite.build.rollupOptions ??= {};
      config.vite.build.rollupOptions.output ??= {};
      config.vite.build.rollupOptions.output.assetFileNames = {
        font: 'fonts/[name][extname]',
        image: 'assets/[name]-[hash][extname]',
        css: 'assets/[name]-[hash][extname]'
      };
    });
  }
});

验证步骤 #

1. 重新构建项目：npm run build
2. 启动生产服务器：node playground/.output/server/index.mjs
3. 打开DevTools的网络面板，检查字体文件请求路径是否和实际文件一致
4. 确认图标显示正常，不再是方框

内容的提问来源于stack exchange，提问作者Oyedeji