如何在Next.js SSR中动态使用FontAwesome图标？

问题根源 #

开发模式下服务器端渲染时，FontAwesome图标库未提前完成注册，导致服务器找不到指定图标，进而引发Hydration不匹配错误；生产构建时代码被打包整合，库注册逻辑提前执行，所以渲染正常。

解决方案 #

1. 全局注册图标库 #

在Next.js的全局入口文件中注册所有需要的图标库，确保服务器端和客户端渲染时都能访问到图标资源：

对于Pages Router（pages/_app.js/_app.tsx）

import { library } from '@fortawesome/fontawesome-svg-core';
import { fas } from '@fortawesome/free-solid-svg-icons';
// 如果需要常规图标，可添加下面一行
// import { far } from '@fortawesome/free-regular-svg-icons';

// 全局注册图标库，服务器端和客户端都会执行此逻辑
library.add(fas);

export default function App({ Component, pageProps }) {
  return <Component {...pageProps} />;
}

对于App Router（app/layout.tsx）

import { library } from '@fortawesome/fontawesome-svg-core';
import { fas } from '@fortawesome/free-solid-svg-icons';

// 在根布局中注册，确保所有页面的SSR都能加载图标
library.add(fas);

export default function RootLayout({ children }) {
  return (
    <html lang="zh-CN">
      <body>{children}</body>
    </html>
  );
}

2. 正确传递图标参数 #

推荐直接使用数组格式传递图标信息（FontAwesome内部解析更高效，避免字符串解析问题）：

// 页面组件中调用
<MyComponent icon={['fas', 'cube']} />

如果必须使用字符串格式（如'fa-solid fa-cube'），可以在MyComponent中做格式转换：

import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';

export function MyComponent({ icon }) {
  // 将字符串格式转换为FontAwesome支持的数组格式
  const parsedIcon = typeof icon === 'string' 
    ? icon.split(' ').map(item => item.replace('fa-', '')).reverse()
    : icon;

  return <FontAwesomeIcon icon={parsedIcon} />;
}

3. 验证效果 #

完成上述配置后，开发模式下服务器端会提前注册图标库，渲染时能正确找到图标，Hydration错误会消失，同时生产环境也能保持正常运行。

注意：全量导入图标会增加打包体积，如果后续需求明确可使用的图标范围，可考虑按需导入优化体积，但当前场景下全量导入是满足运行时动态图标的必要方案。

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