FontAwesome Vue 3 使用教程 — 完整集成指南与组件化实践

安装依赖

Vue 3 项目需要安装 vue-fontawesome 的 v3 版本。核心 SVG 引擎与 React 版本相同，但 Vue 组件包独立维护。FontAwesome 的 Vue 组件将图标渲染为内联 <svg> 元素，与 Vue 的响应式系统和虚拟 DOM 深度集成，可以实现高效的图标更新和动画控制。

npm（Vue 3）

npm install @fortawesome/vue-fontawesome@latest @fortawesome/fontawesome-svg-core @fortawesome/free-solid-svg-icons

额外样式包

# Regular 风格（空心图标）
npm install @fortawesome/free-regular-svg-icons

# 品牌图标
npm install @fortawesome/free-brands-svg-icons

版本提醒：Vue 3 项目务必使用 @fortawesome/vue-fontawesome@3 或以上版本，Vue 2 请使用 @fortawesome/vue-fontawesome@2。两个版本的 API 有较大差异。

注册组件

FontAwesome Vue 组件支持全局注册和局部注册两种方式。全局注册后可在任意模板中直接使用 <font-awesome-icon> 标签，适合图标使用频率较高的中大型项目。局部注册则只在特定组件范围内生效，适合图标使用较少或对打包体积有严格要求的场景。在实际项目中，建议根据项目规模灵活选择注册策略，也可以两者结合使用——在插件中全局注册常用图标，在页面组件中局部注册专用的业务图标。

全局注册

在 main.js 或 main.ts 中完成全局注册，适合中大型项目。

import { createApp } from 'vue'
import App from './App.vue'
import { library } from '@fortawesome/fontawesome-svg-core'
import { faHome, faUser, faGear } from '@fortawesome/free-solid-svg-icons'
import { FontAwesomeIcon } from '@fortawesome/vue-fontawesome'

library.add(faHome, faUser, faGear)

createApp(App)
  .component('font-awesome-icon', FontAwesomeIcon)
  .mount('#app')

局部注册

在单个组件中局部注册，适合按需引入的小型项目或特定页面。

<script setup>
import { FontAwesomeIcon } from '@fortawesome/vue-fontawesome'
import { faStar } from '@fortawesome/free-solid-svg-icons/faStar'
</script>

<template>
  <div>
    <font-awesome-icon :icon="faStar" />
  </div>
</template>

基本用法

<font-awesome-icon> 组件的核心属性与 React 版本类似，支持 icon、size、spin、pulse、beat 等常用 Props。与直接使用 CSS 类名不同，组件方式可以更好地与 Vue 的数据绑定和条件渲染结合，实现灵活的动态图标展示。例如通过 :icon 动态绑定不同的图标对象，或者使用 :spin 绑定加载状态变量来控制动画启停。

<!-- 基本图标 -->
<font-awesome-icon icon="fa-solid fa-home" />

<!-- 设置尺寸 -->
<font-awesome-icon icon="fa-solid fa-star" size="2x" />

<!-- 旋转动画 -->
<font-awesome-icon icon="fa-solid fa-spinner" spin />

<!-- 脉冲动画 -->
<font-awesome-icon icon="fa-solid fa-circle-notch" pulse />

<!-- 自定义样式 -->
<font-awesome-icon
  icon="fa-solid fa-heart"
  beat
  style="color: red;"
  class="my-icon"
/>

字符串格式 "fa-solid fa-home" 要求图标已通过 library.add() 注册。也可以直接传入导入的图标对象。

Composition API 用法

在 <script setup> 中使用 Composition API 可以更灵活地管理图标导入，同时享受 tree-shaking 的优化优势。Composition API 是 Vue 3 的推荐开发模式，它将组件逻辑组织为可组合的函数，使得图标管理与业务逻辑的耦合度更低。通过 library.add() 结合单图标导入，每个组件的图标依赖关系清晰可见，便于后续维护和重构。

<script setup>
import { ref } from 'vue'
import { library } from '@fortawesome/fontawesome-svg-core'
import { FontAwesomeIcon } from '@fortawesome/vue-fontawesome'
import { faSun, faMoon, faCheck, faXmark } from '@fortawesome/free-solid-svg-icons'

// 添加到 library，支持字符串引用
library.add(faSun, faMoon, faCheck, faXmark)

const isDark = ref(false)

function toggleTheme() {
  isDark.value = !isDark.value
}
</script>

<template>
  <button @click="toggleTheme" class="btn btn-outline-secondary">
    <font-awesome-icon
      :icon="isDark ? 'fa-solid fa-moon' : 'fa-solid fa-sun'"
      class="me-1"
    />
    {{ isDark ? '暗色模式' : '亮色模式' }}
  </button>
</template>

通过 library.add() 注册的图标可以在模板中使用字符串引用，同时保留 tree-shaking 能力——library.add() 不会打包未使用的图标。

按需导入

为获得最佳打包体积，建议从单图标路径导入，确保 Webpack / Vite 的 tree-shaking 生效。Tree-shaking 是现代化构建工具的核心优化手段，它通过静态分析 import 语句，识别并删除未被引用的代码。FontAwesome 的图标库包含数万个图标，如果全部导入将使打包体积增加数兆字节。通过单图标路径导入，构建工具可以精准地只保留实际使用到的图标定义，这对于大型企业级项目尤为重要。

// ✅ 最佳实践：单图标导入，支持 tree-shaking
import { faHome } from '@fortawesome/free-solid-svg-icons/faHome'
import { faUser } from '@fortawesome/free-solid-svg-icons/faUser'
import { faBell } from '@fortawesome/free-solid-svg-icons/faBell'

import { library } from '@fortawesome/fontawesome-svg-core'
library.add(faHome, faUser, faBell)

// ❌ 避免全量导入（会显著增加打包体积）
// import { faHome, faUser, faBell } from '@fortawesome/free-solid-svg-icons'

// ❌ 避免使用 Font Awesome 的 JS 自动替换（dom.watch）
// 它与 Vue 的虚拟 DOM 机制存在兼容性问题

单图标路径格式为 @fortawesome/free-solid-svg-icons/faXxx，文件名采用 PascalCase 命名。Vite 和 Webpack 5 均能正确识别并进行 tree-shaking。

Vue 2 vs Vue 3 差异

对比项	Vue 3	Vue 2
组件包版本	`@fortawesome/vue-fontawesome@3`	`@fortawesome/vue-fontawesome@2`
组件标签	`<font-awesome-icon>`	`<font-awesome-icon>`（相同）
Composition API	原生支持 `<script setup>`	需使用 `@vue/composition-api` 插件
图标绑定方式	`:icon="faHome"` 或 `icon="fa-solid fa-home"`	同 Vue 3
Props 类型	TypeScript 类型完整	无原生 TS 支持
SSR 支持	原生支持（Nuxt 3）	需额外配置（Nuxt 2）
动画 Props	`spin`、`pulse`、`beat`、`fade` 等全部支持	基础旋转动画支持

迁移建议：新项目一律选择 Vue 3 + vue-fontawesome@3；现有 Vue 2 项目建议保持在 v2 版本，不要混用。

常见场景

按钮图标

在按钮中嵌入图标，配合加载状态实现更好的用户反馈。

<script setup>
import { ref } from 'vue'
import { library } from '@fortawesome/fontawesome-svg-core'
import { FontAwesomeIcon } from '@fortawesome/vue-fontawesome'
import { faSpinner, faDownload, faCheck } from '@fortawesome/free-solid-svg-icons'
library.add(faSpinner, faDownload, faCheck)

const loading = ref(false)

async function handleDownload() {
  loading.value = true
  await new Promise(r => setTimeout(r, 2000))
  loading.value = false
}
</script>

<template>
  <button
    @click="handleDownload"
    :disabled="loading"
    class="btn btn-primary"
  >
    <font-awesome-icon
      :icon="loading ? 'fa-solid fa-spinner' : 'fa-solid fa-download'"
      :spin="loading"
      class="me-1"
    />
    {{ loading ? '下载中...' : '开始下载' }}
  </button>
</template>

列表图标

在列表项前添加图标可以增强内容的可读性和视觉层次感。

<script setup>
import { library } from '@fortawesome/fontawesome-svg-core'
import { FontAwesomeIcon } from '@fortawesome/vue-fontawesome'
import { faCircleCheck, faCircleXmark, faCircleExclamation } from '@fortawesome/free-solid-svg-icons'
library.add(faCircleCheck, faCircleXmark, faCircleExclamation)

const items = [
  { text: '数据库连接成功', status: 'success' },
  { text: '配置文件验证通过', status: 'success' },
  { text: '缓存预热完成', status: 'warning' },
  { text: '邮件服务未配置', status: 'error' },
]

const statusMap = {
  success: { icon: 'fa-solid fa-circle-check', color: '#20c997' },
  warning: { icon: 'fa-solid fa-circle-exclamation', color: '#f59f00' },
  error:   { icon: 'fa-solid fa-circle-xmark', color: '#e03131' },
}
</script>

<template>
  <ul class="list-unstyled">
    <li v-for="item in items" :key="item.text" class="mb-2">
      <font-awesome-icon
        :icon="statusMap[item.status].icon"
        :style="{ color: statusMap[item.status].color }"
        fixed-width
        class="me-2"
      />
      {{ item.text }}
    </li>
  </ul>
</template>

条件渲染

根据组件状态切换图标是一种简单有效的交互反馈模式。

<script setup>
import { ref } from 'vue'
import { library } from '@fortawesome/fontawesome-svg-core'
import { FontAwesomeIcon } from '@fortawesome/vue-fontawesome'
import { faEye, faEyeSlash } from '@fortawesome/free-solid-svg-icons'
library.add(faEye, faEyeSlash)

const visible = ref(false)
const password = ref('')
</script>

<template>
  <div class="input-group">
    <input
      :type="visible ? 'text' : 'password'"
      v-model="password"
      class="form-control"
      placeholder="请输入密码"
    />
    <button class="btn btn-outline-secondary" @click="visible = !visible">
      <font-awesome-icon :icon="visible ? 'fa-solid fa-eye' : 'fa-solid fa-eye-slash'" />
    </button>
  </div>
</template>

Nuxt 3 集成

在 Nuxt 3 项目中，建议创建插件文件统一注册 FontAwesome 组件，避免在每个页面重复导入。Nuxt 3 的插件系统会在应用初始化时自动加载，因此注册的组件在整个应用范围内可用。对于使用了 Nuxt 3 服务端渲染的项目，这种方式可以确保图标在服务端和客户端渲染结果一致，避免因客户端 hydration 导致的布局偏移问题。

// plugins/fontawesome.js
import { library } from '@fortawesome/fontawesome-svg-core'
import { FontAwesomeIcon } from '@fortawesome/vue-fontawesome'
import { faHome, faUser, faGear } from '@fortawesome/free-solid-svg-icons'
import { faGithub, faTwitter } from '@fortawesome/free-brands-svg-icons'

library.add(faHome, faUser, faGear, faGithub, faTwitter)

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

<!-- 注册后可在任意页面直接使用 -->
<template>
  <div>
    <font-awesome-icon icon="fa-solid fa-home" size="2x" />
    <font-awesome-icon :icon="['fab', 'github']" size="2x" />
  </div>
</template>

Nuxt 3 的自动导入机制不会自动识别 <font-awesome-icon> 组件，因此必须通过插件手动注册。上述方式可以确保在服务端渲染（SSR）时正常输出图标。如果使用了 @nuxtjs/color-mode 等主题插件，还可以结合 FontAwesome 的图标实现明暗主题切换按钮，在 app.vue 或布局组件中响应式切换 sun 和 moon 图标。

FontAwesome Vue 3 集成指南