React v6项目导入FontAwesome图标报模块未找到错误如何解决

问题描述 #

在React v6项目中引入FontAwesome图标，代码符合官方使用规范，自述已安装相关依赖，但运行时抛出模块解析错误：

Module not found: Error: Can't resolve '@fortawesome/react-fontawesome'

对应业务代码片段：

import { FontAwesomeIcon } from "@fortawesome/react-fontawesome"; 
import { faQuestionCircle, faExclamationCircle, faCog,} from "@fortawesome/free-solid-svg-icons";

<div className="action-btn">
  <FontAwesomeIcon className="icon-block" icon={faQuestionCircle} />
  <FontAwesomeIcon className="icon-block" icon={faExclamationCircle} />
  <FontAwesomeIcon className="icon-block" icon={faCog} />
</div>

排查解决步骤 #

按优先级从高到低逐一验证即可解决：

• 补全核心依赖
  90%以上的该类报错都是漏装核心依赖导致，React环境下使用FontAwesome必须安装3个基础包，在项目根目录执行对应包管理器的安装命令即可，禁止全局安装依赖：
  npm用户执行：

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

  yarn用户执行：

  yarn add @fortawesome/fontawesome-svg-core @fortawesome/free-solid-svg-icons @fortawesome/react-fontawesome
  

  pnpm用户执行：

  pnpm add @fortawesome/fontawesome-svg-core @fortawesome/free-solid-svg-icons @fortawesome/react-fontawesome
  

• 校验依赖安装完整性
  安装完成后打开项目下node_modules/@fortawesome目录，确认存在react-fontawesome、free-solid-svg-icons、fontawesome-svg-core三个子文件夹。如果文件夹缺失，直接删除node_modules目录和对应锁文件（package-lock.json/yarn.lock/pnpm-lock.yaml），重新执行全量依赖安装命令。
• 校验版本兼容性
  React v16及以上版本（含v18、搭配React Router v6的项目）需要搭配0.2.0及以上版本的@fortawesome/react-fontawesome，不要使用0.1.x的老旧版本。打开package.json查看对应依赖版本，版本不符合要求直接重新安装最新稳定版即可。
• 排查导入路径拼写错误
  检查代码中的导入路径，确保和官方包名完全一致，常见拼写错误包括多写横杠（比如错写为@fortawesome/react-font-awesome）、大小写错误（比如错写为@fortawesome/ReactFontAwesome）。
• 重启本地开发服务
  依赖安装完成后，停止当前运行的本地开发服务再重新启动。Vite、Webpack等打包工具在运行状态下不会自动识别新安装的依赖，热更新机制不会加载新安装的模块，重启服务即可解决这类偶发解析问题。

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