Font Awesome升级失败主因是未理清版本映射与类名前缀规则：FA 4.x用fa fa-home，FA 5+须用fas/fa-user/fab等前缀，漏写或错配导致图标变方块；CDN与本地混用、字体路径错误、font-family被覆盖或伪元素渲染干扰亦常见。
别删旧 CSS 文件，也别直接改 class 名——Font Awesome 图标库升级或换源，90% 的失败源于没理清版本映射和类名前缀规则。
确认当前 Font Awesome 版本再动手
FA 4.x 和 FA 5+ 的类名体系不兼容：FA 4.x 用 fa fa-home，FA 5+ 免费版必须带前缀 fas fa-home（实心）、far fa-user（线框）或 fab fa-github（品牌）。直接把旧 class 改成新名字，图标会变方块。
- 打开 HTML 源码，搜
fontawesome.min.css或use.fontawesome.com，看 URL 是否含/v4/或/v6/ - 查 CDN 链接末尾是否有
?v=5.15.4这类版本号；没有就打开控制台 Network 标签页，过滤fontawesome，看响应头里的x-version - 本地引入的，打开
fontawesome.css，第一行注释通常写明版本
FA 5+ 替换图标时 class 前缀不能省
FA 5+ 把图标拆成三个字体文件，fas、far、fab 分别对应不同 @font-face 声明。漏掉前缀，浏览器找不到 glyph 映射，只显示空格或方块。
-
<i class="fa fa-home"></i>→ 必须改成<i class="fas fa-home"></i>（不是fa-home单独用） - 部分图标只存在于某个风格中，比如
fa-bell在 FA 5+ 里只有fas和far，没有fab版本；换错前缀会失效 - FA 6 已弃用
fa-前缀，统一用fa-solid/fa-regular，但类名主体不变（fa-house替代fa-home），需查新版图标页确认
CDN 切本地、本地切 CDN 的路径陷阱
FA 官方 CDN（use.fontawesome.com）默认走 JS 注入模式，而本地 .css + .woff2 是纯 CSS 方式，混用会导致图标加载两次或冲突。
立即学习“前端免费学习笔记（深入）”；
- 如果原模板用的是 CDN JS 方式（
<script src="https://use.fontawesome.com/xxx.js"></script>），想切本地，必须删掉该 script，并确保@font-face中的url()路径指向正确的webfonts/fa-solid-900.woff2等文件 - 本地字体文件路径写错是高频问题：
url('./webfonts/fa-solid-900.woff2')对应 CSS 文件所在目录，不是 HTML 所在目录 - Vite / Next.js 项目里，别把
fontawesome.css放进public/后用@import引入——构建器不会解析 public 下的@import，字体路径必然 404
图标不显示？先盯住 computed font-family
右键图标 → “检查元素” → 右侧 Styles 面板点“Computed”，下拉找 font-family。如果最终生效的是 "Helvetica" 或 "PingFang SC"，说明图标字体根本没加载成功，或被更高优先级 CSS 覆盖了。
- 常见覆盖源：
body { font-family: "Inter"; }会继承到<i>上，除非显式重置i { font-family: "Font Awesome 6 Free"; } - FA 6 的字体族名是
"Font Awesome 6 Free"（注意空格和大小写），不是"FontAwesome"或"fa" - 若 computed 里 font-family 正确但仍是方块，打开 Network 查
fa-solid-900.woff2是否返回 404 或 CORS 错误
最易被忽略的一点：FA 图标依赖 :before 伪元素注入 Unicode 字符，如果父容器设了 font-feature-settings: "liga" off 或 text-rendering: optimizeLegibility，某些浏览器会干扰伪元素渲染——临时关掉这些样式，能快速验证是不是渲染链路的问题。
