Nuxt3+Tailwind集成FontAwesome6遇图标报错与hydration不匹配问题

图标能正常显示，但服务器控制台抛出错误：

✔ Vite server hmr 12 files in 446.295ms                                                        18:11:42
Could not find one or more icon(s) { prefix: 'fab', iconName: 'facebook' } {}

浏览器控制台出现Hydration不匹配警告：

[Vue warn]: Hydration node mismatch:

- Client vnode: svg 
- Server rendered DOM: <!---->  
  at <FontAwesomeIcon icon= (2) ['fab', 'facebook'] > 
  at <Index onVnodeUnmounted=fn<onVnodeUnmounted> ref=Ref< undefined > > 
  at <RouteProvider key="/" routeProps= {Component: {…}, route: {…}} pageKey="/"  ... > 
  at <FragmentWrapper > 
  at <RouterView name=undefined route=undefined > 
  at <NuxtPage> 
  at <Default > 
  at <LayoutLoader key="default" name="default" hasTransition=false > 
  at <FragmentWrapper > 
  at <NuxtLayout> 
  at <App key=2 > 
  at <NuxtRoot>

按官方步骤操作后，所有免费图标都存在相同问题，项目配置如下：

package.json #

{  
  "private": true,  
  "scripts": {  
    "dev": "nuxi dev",  
    "build": "nuxi build",  
    "start": "node .output/server/index.mjs",  
    "lint": "eslint --ext .ts,.js,.vue .",  
    "test": "vitest",  
    "coverage": "vitest run --coverage"  
  },  
  "devDependencies": {  
    "@headlessui/vue": "^1.7.12",  
    "@nuxt/devtools": "^0.2.5",  
    "@nuxtjs/color-mode": "^3.2.0",  
    "@nuxtjs/eslint-config-typescript": "^12.0.0",  
    "@pinia/nuxt": "^0.4.7",  
    "@tailwindcss/aspect-ratio": "^0.4.2",  
    "@tailwindcss/container-queries": "^0.1.0",  
    "@tailwindcss/forms": "^0.5.3",  
    "@tailwindcss/line-clamp": "^0.4.2",  
    "@tailwindcss/typography": "^0.5.9",  
    "@vitest/coverage-c8": "^0.29.2",  
    "@vueuse/nuxt": "^9.13.0",  
    "eslint": "^8.35.0",  
    "nuxt": "^3.2.3",  
    "nuxt-headlessui": "^1.1.1",  
    "nuxt-icon": "^0.3.2",  
    "nuxt-vitest": "^0.6.6",  
    "pinia": "^2.0.33",  
    "tailwindcss": "^3.2.7",  
    "typescript": "^4.9.5"  
  },  
  "dependencies": {  
    "@fortawesome/fontawesome-svg-core": "^6.3.0",  
    "@fortawesome/free-brands-svg-icons": "^6.3.0",  
    "@fortawesome/vue-fontawesome": "^3.0.3",  
    "pnpm": "^7.29.1",  
    "vitest": ">=0.29.0 <1",  
    "vue": "3.2.47"  
  }  
}

plugins/fontawesome.js #

import { library, config } from '@fortawesome/fontawesome-svg-core'
import { FontAwesomeIcon } from '@fortawesome/vue-fontawesome'
import { faFacebook } from '@fortawesome/free-brands-svg-icons'
library.add(faFacebook)

// This is important, we are going to let Nuxt worry about the CSS
config.autoAddCss = false

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.component('font-awesome-icon', FontAwesomeIcon, {})
})

nuxt.config.ts #

export default defineNuxtConfig({
  modules: [
    '@vueuse/nuxt',
    '@pinia/nuxt',
    '@nuxtjs/color-mode',
    'nuxt-icon',
    'nuxt-headlessui',
    'nuxt-vitest'
    // '@nuxt/devtools'
  ],
  experimental: {
    reactivityTransform: true
  },
  css: [
    '~/assets/css/tailwind.css',
    '@fortawesome/fontawesome-svg-core/styles.css'
  ],
  postcss: {
    plugins: {
      tailwindcss: {},
      autoprefixer: {}
    }
  },
  colorMode: {
    classSuffix: ''
  },
  headlessui: {
    prefix: ''
  },
  plugins: [
    { src: "~/plugins/fontawesome.js", ssr: false} 
  ]
})

模板中图标使用代码 #

<font-awesome-icon :icon="['fab', 'facebook']" />

问题原因与解决方法 #

问题出在nuxt.config.ts中给fontawesome插件设置了ssr: false，这意味着插件只在客户端执行：

• 服务端渲染时没有注册FontAwesomeIcon组件，也没有加载图标库，所以服务端找不到图标抛出错误，同时渲染出空注释节点<!---->
• 客户端渲染时插件正常执行，生成正确的SVG节点，导致服务端和客户端DOM不匹配，触发Hydration警告

解决步骤：

1. 修改nuxt.config.ts的plugins配置，移除ssr: false，让插件在服务端和客户端都运行：

plugins: [
  "~/plugins/fontawesome.js"
]

2. 重启开发服务，此时服务端会正确加载图标库并渲染SVG节点，和客户端保持一致，错误和警告都会消失。

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