简介Font Awesome是经典的网页矢量图标字体库这份4.6.3版本资源包面向需要快速在网站或应用界面中集成图标的网页设计师与前端开发者通过配置CSS类名即可调用社交、通用操作、方向指示等众多分类的矢量图标也可借助Unicode方式嵌入。压缩包共37个文件涵盖css样式表、eot/ttf/woff/woff2/svg字体文件以及less/scss源文件和说明文档整体约587KB目录划分清晰。基于Web Font技术图标在不同分辨率下能保持清晰同时支持堆叠、旋转翻转、CSS3动画等扩展效果并为Firefox、Chrome、Safari、IE9及Edge做了兼容处理适合响应式布局与自定义颜色、尺寸。目前已有796人学习下载对于需要离线部署、按源码二次定制或系统理解图标字体机制的开发者这份精简资源包具有不错的实用价值。 维护一个旧版管理后台页面左侧菜单的图标突然全变成方框。打开网络请求一看写死的 CDN 地址失效页面里二十几处classfa fa-...全部失去字符映射。这类老系统最后落地基本就一个动作把 font-awesome-4.6.3 资源包下载到本地重新接上页面复活。font-awesome-4.6.3 是 Font Awesome 4.x 系列的稳定版本提供 600 多个图标包内带预编译 CSS、字体文件和 less/scss 源码不依赖运行框架这是存量后台到今天还在用它的大前提。需要它的人大致三类维护写死 fa 前缀的老代码、在内网隔离环境做离线部署、想在老版本基础上定制前缀或做图标子集化都需要一份能自己掌控的资源包。后文按解包、接入、定制、避坑、验证的顺序走。新手从第 3 章接入方式直接抄熟手直接看第 5 章那几条是高频踩坑位。2. 拆开 font-awesome-4.6.3 资源包文件清单、字体格式与加载顺序2.1 解压后的目录结构与一份关键文件清单下载到的 4.6.3 资源包解压后是一个标准目录。我一般建议先别急着丢进项目先花两分钟确认目录是不是完整。一份正常的包应当包含以下内容font-awesome-4.6.3/ ├── css/ │ ├── font-awesome.css │ └── font-awesome.min.css ├── fonts/ │ ├── FontAwesome.otf │ ├── fontawesome-webfont.eot │ ├── fontawesome-webfont.svg │ ├── fontawesome-webfont.ttf │ ├── fontawesome-webfont.woff │ └── fontawesome-webfont.woff2 ├── less/ ├── scss/ └── README.mdcss 目录里两个文件是别人帮你编译好的成品直接link引用就能用less 和 scss 是给需要改前缀、改字体路径、做二次编译的人准备的源码fonts 目录才是这套资源包的本体。很多人在这一步只拷了 css 忘了拷 fonts页面引出来全是方框却不报错这种问题最难看——后面专门讲。font-awesome.css 是非压缩版本适合开发和 debugfont-awesome.min.css 是压缩版本体积更小适合生产。两者内容等价不要两个都引也不要引混。2.2 打开 css 看 font-face双 src 写法与字体格式的加载顺序4.6.3 的资源包能跨过这么多年还能稳定工作核心在css/font-awesome.css顶部的font-face声明。打开文件看到的结构大致如下font-face { font-family: FontAwesome; src: url(../fonts/fontawesome-webfont.eot?v4.6.3); src: url(../fonts/fontawesome-webfont.eot?#iefixv4.6.3) format(embedded-opentype), url(../fonts/fontawesome-webfont.woff2?v4.6.3) format(woff2), url(../fonts/fontawesome-webfont.woff?v4.6.3) format(woff), url(../fonts/fontawesome-webfont.ttf?v4.6.3) format(truetype), url(../fonts/fontawesome-webfont.svg?v4.6.3#fontawesomeregular) format(svg); font-weight: normal; font-style: normal; }这段声明是理解 4.x 系图标字体工作的钥匙。第一行src只给了 eot是专门写给 IE8/IE9 的兼容写法否则这些老浏览器会忽略后面的声明。第二行的顺序是有讲究的浏览器会从左到右找它能用的第一个格式现代浏览器直接命中 woff2老一点的环境退回 woff 或 ttfsvg 是更老的 iOS 时代留下的后路。?v4.6.3只是缓存刷新参数去掉也不影响加载但别手动去改它保持原样是最省事的。url 里的../fonts/说明 css 与 fonts 必须保持相对路径关系拷贝资源包时一旦把 css 单独挪到深层目录这里就会 404。2.3 版本对比4.6.3、4.7.0 与 5.x 该选谁对比项4.6.34.7.05.x 及以上class 写法fa fa-homefa fa-homefas fa-home/far/fab图标数量较多比 4.6.3 稍多明显更多但类别被拆分代码迁移成本基准几乎零成本全局替换类名体力活老 IE 兼容保留 eot/svg 路径同左官方基本放弃定制前缀less/scss 变量同左机制变了不能照搬如果你手上的页面全是fa fa-开头最稳妥的选择就是在 4.x 里挑一个版本。4.6.3 与 4.7.0 差异不算大4.7.0 多了一些图标但如果存量代码里没用到新增的图标且页面还有老浏览器需要兼容继续用 4.6.3 完全合理。升 5.x 不是换个 css 文件那么简单所有fa fa-xxx要改成fas fa-xxx品牌类还要改成fab加上图标字体内部编码也有调整等于把页面重扫一遍。3. 把资源包装进项目静态目录、webpack 与 Vite 三条接入路径3.1 不构建的静态页面保持 css 与 fonts 相对关系其他什么都别动常见做法是把资源包里的 css 和 fonts 两个目录直接拷到项目静态目录下保持它们的同级关系。以my-admin为例my-admin/ ├── static/ │ ├── css/ │ │ └── font-awesome.min.css │ ├── fonts/ │ │ └── fontawesome-webfont.* │ └── index.html页面里这样引用!DOCTYPE html html langzh-CN head link relstylesheet hrefstatic/css/font-awesome.min.css /head body i classfa fa-home/i i classfa fa-user/i /body /html这段代码的关键在于static/css/与static/fonts/的层级关系。css 里的url(../fonts/...)会向上退一级再进 fonts所以 css 和 fonts 必须共享同一个父目录。如果你非要把 css 放到更深的目录那就必须自己改font-face里的字体路径这一步很容易漏。改法的原则是以 css 文件所在位置为起点计算到 fonts 目录的相对路径写进 url。页面打开后优先看 Network 面板里字体请求是否 200而不是先看图标长什么样。3.2 webpack 打包字体规则要匹配?v查询参数publicPath 决定最终 URL在 webpack 工程里接 4.6.3常见做法是先通过 npm 装一份到本地再在入口处引入 cssnpm install font-awesome4.6.3入口文件里加一行import font-awesome/css/font-awesome.min.csswebpack 打包时 css-loader 会把 css 里的字体 url 交给资源处理规则。关键在于 webpack 配置里对字体的 test 正则必须把?v4.6.3这种查询参数算进去// webpack.config.js { module: { rules: [ { test: /\.(eot|svg|ttf|woff|woff2|otf)(\?.*)?$/, type: asset/resource, generator: { filename: fonts/[name].[hash:8][ext] } } ] } }(\?.*)?$这段是整个规则里最容易翻车的地方。4.6.3 的 css 里字体地址普遍带?v4.6.3如果正则只写\.(woff2?|ttf)$带查询参数的文件匹配不上webpack 会把字体请求原样留在 css 里部署后依然是相对路径去找外部字体等于没打包。asset/resource会把字体复制到输出目录并自动改写 URL。之后还要检查output.publicPath如果部署时站点跑在子目录publicPath 写成/会把字体 URL 拼到域名根下直接 404改成相对路径或按实际情况指定。3.3 Vite 工程assetsInlineLimit 与 base 两个配置决定字体以文件还是 base64 存在Vite 处理 4.6.3 的字体入口引入方式和 webpack 类似// main.js import font-awesome/css/font-awesome.min.css但 Vite 有一个默认行为小于assetsInlineLimit默认 4096 字节的资源会被内联成 base64。woff2 压缩后通常略大于这个阈值ttf、eot 则比较大于是经常出现“woff2 生成了文件、ttf 被打进 css”的混合情况。想让字体统一以文件形式输出建议在 vite.config.js 里做两处配置// vite.config.js import { defineConfig } from vite export default defineConfig({ base: ./, build: { assetsInlineLimit: 0 } })assetsInlineLimit: 0的含义是超过 0 字节的资源一律输出文件不做内联这样字体 URL 是独立文件浏览器可以走缓存而不是跟着 css 一起加载。base: ./解决的是部署路径问题默认 base 是/构建出的资源引用会以根路径开头站点部署在子目录时字体请求全部指向域名根目录那自然是 404。生产环境如果有独立的 CDN 域名base 也可以写成 CDN 完整地址但内网部署场景下写相对路径是最稳的。4. 定制这个版本改前缀、核对 Unicode 表、按需子集化4.1 把 fa 前缀改成自己的命名空间改变量再编译别全局替换 css有些项目为了和业务类名避开或为了风格统一想把这套图标从fa改成icon、ui之类的短前缀。常见做法是改 less/scss 里的变量再重新编译而不是拿 css 做字符串全局替换。以 less 为例# 先备份一份自己的副本别动原包 cp font-awesome-4.6.3/less/variables.less font-awesome-4.6.3/less/variables.less.bak # 修改前缀变量 sed -i s/fa-css-prefix: fa;/fa-css-prefix: icon;/ font-awesome-4.6.3/less/variables.less # 重新编译 lessc font-awesome-4.6.3/less/font-awesome.less font-awesome-custom.csslessc 需要 Node 环境全局安装 less命令是npm i -g less。编译完成后页面 HTML 里原来的i classfa fa-home要同步改成i classicon icon-home。为什么强调不要直接全局替换 css 里的.fa-因为 4.x 的图标渲染依赖两类规则一类是基类.fa负责font-family: FontAwesome和基础字号另一类是.fa-home:before负责写入content编码。如果只替换前缀这两处会漏其中一处结果就是类名命中但字体不生效。用变量编译能保证基类、伪元素、还有.fa-lg、.fa-2x这类尺寸类全部一致替换。scss 版本同理改_variables.scss里的$fa-css-prefix。4.2 核对图标是否存在用 variables.less 或 css 查 Unicode 映射4.6.3 的图标数虽然不少但不是今天 5.x、6.x 里所有名字都能找到。比如fa-gem、实心款的fa-snowflake这类后加图标在 4.6.3 里是查不到的。遇到“类名写对了但图标不显示”不要先怀疑字体加载先查这个图标在这个版本里到底存不存在。# 在 less 变量里查一个图标名是否有对应码位 grep fa-var-snowflake font-awesome-4.6.3/less/variables.less # 或者在编译好的 css 里查 grep -c fa-snowflake:before font-awesome-4.6.3/css/font-awesome.css第一条命令返回空说明这个图标不在 4.6.3 的变量表里第二条命令返回0进一步确认它在已编译 css 中也没有对应规则。4.6.3 的图标清单以less/variables.less里的fa-var-*变量为准这个文件本质是一张 Unicode 映射表fa-var-home: \f015;表示类fa-home的伪元素会写入字符\f015。想确认某个图标到底有没有查这张表是最权威的做法比在页面里猜快得多。4.3 按需子集化只留项目真正用到的几十个图标老资源包整套字体文件虽然不算大但在追求首屏体积的场景里只保留用得到的图标是更专业的做法。常见做法是基于 fontTools 对 ttf 做子集化。先安装工具pip install fonttools brotli然后从 4.6.3 的 ttf 里抽出指定码位。以保留首页、用户、设置三个图标为例pyftsubset fontawesome-webfont.ttf \ --unicodesUF015,UF007,UF013 \ --flavorwoff2 \ --output-filefontawesome-subset.woff2 pyftsubset fontawesome-webfont.ttf \ --unicodesUF015,UF007,UF013 \ --flavorwoff \ --output-filefontawesome-subset.woff--unicodes接受逗号分隔的码位码位值来自 variables.less 里对应的\f...编码--flavorwoff2与--flavorwoff分别生成目标格式现代浏览器用 woff2旧环境退到 woff。生成后把 css 里font-face的 src 改成这两个子集文件的路径即可。需要注意子集化之后 eot 和 svg 就没了意味着 IE8、非常老的 iOS 环境不再支持图标显示这是精简体积的代价取舍时想清楚访问者是谁。5. 4.6.3 接入避坑指南请求 404、类名映射、打包重写与跨域5.1 先定位问题在哪一层四步检查把玄学变科学字体不显示时多数人第一反应是“这图标库是不是有问题”实际上大部分问题集中在四层。第一步打开浏览器 Network 面板刷新页面看字体请求的状态码200 说明文件到了404 说明路径或部署有问题状态是 (failed) 则多半是跨域或 mime 类型问题。第二步把字体请求的 URL 复制到新标签直接打开看返回的是字体二进制还是 HTML 报错页能区分到底是路径错还是服务器配错。第三步在 Elements 面板选中一个i classfa fa-home看右侧样式里有没有命中font-family: FontAwesome与伪元素内容。第四步看 Console 有没有 CORS 报错或 MIME 类型警告。走完这四步绝大多数“图标不显示”都能被定位到具体层而不是靠瞎改 class 碰运气。5.2 四个高频坑现象、原因与解决坑一字体文件 404页面一片方框。现象是 HTML 和 css 都加载了但 Network 里fontawesome-webfont.woff2请求 404。原因大多是 css 文件和 fonts 目录的相对层级被破坏。比如你只把 css 拷到了static/css/而字体还在static/fonts/如果页面 URL 是static/pages/index.html那么 css 里的../fonts/会被浏览器解析成pages/fonts/自然找不到。解决方式是算清楚层级把 css 和 fonts 恢复为同级或者按实际位置改写font-face中的 url。判断标准只有一个让 Network 里请求的最终 URL 与实际文件路径完全一致。坑二字体加载成功但图标显示为空心方框或直接空白。现象是 Network 一切正常font-face也命中了但字符没渲染。原因通常是两个一种是类名写错比如把 5.x 的fas fa-home抄成了fa fa-home4.6.3 里没有对应的 content 映射于是方框另一种是自定义前缀时只改了 HTML 没改 css或只改了 css 里的基类没改伪元素类。解决方式是先用 5.2 里说的方法确认图标在 4.6.3 的 variables.less 中是否存在再看控制台里元素的伪元素 content 是否写入了正确的 Unicode 值。图标字体显示成方框绝大多数是映射表对不上不是字体文件损坏。坑三打包接入后开发正常生产环境字体 404。现象是本地npm run dev一切正常构建部署后字体找不到。原因出在打包器对字体 URL 的重写策略上webpack 的output.publicPath是/开头而站点部署在子目录或者 Vite 的base是绝对根路径或者资源规则没匹配到带?v4.6.3的地址导致字体压根没参与打包。解决方式是把 publicPath / base 改成相对路径并确认构建产物中 css 里字体 URL 指向的是带 hash 的实际文件名。有一条经验可以少走弯路构建后直接看生成的 css搜woff2它的 URL 指向哪里就是最终浏览器会请求的地址。坑四字体从 CDN 加载被浏览器 CORS 策略拦截。现象是 Console 出现类似“font from origin ... has been blocked from loading”的报错。原因是页面与字体不在同一域服务器又没有返回Access-Control-Allow-Origin响应头。4.6.3 的字体文件如果放在没有配置跨域头的对象存储或静态服务器上很容易触发这个限制。解决方式有两个给字体所在目录加上允许跨域的头或者干脆把字体同域化——这也是我推荐的做法内网或生产环境尽量自托管字体文件不依赖外部域。Nginx 里对字体目录加上一句即可location /fonts/ { add_header Access-Control-Allow-Origin *; }如果是本资源包里的 svg 字体还要关注响应头的 Content-Type 是否为image/svgxml有些服务器默认当文本类型返回也会导致渲染异常。6. 用命令验证装的是真 4.6.3字体名、cmap 与页面覆盖检查6.1 用 fontTools 读取字体真实 family 名与字符数装完资源包后验证一份字体是否完整可用我习惯先用 python 直接读它的内部表而不是只看文件名。文件名可以被随意改字体内部的 name 表和 cmap 表才是真身。from fontTools.ttLib import TTFont font TTFont(fontawesome-webfont.ttf) print(family:, font[name].getDebugName(1)) cmap font.getBestCmap() print(glyph count:, len(cmap)) print(0xF015 -, cmap.get(0xF015))getDebugName(1)返回字体族名4.6.3 应当是 FontAwesomegetBestCmap()返回的是 Unicode 到字形名的映射字典len(cmap)能看出这套字体里到底注册了多少个码位。最后一行cmap.get(0xF015)如果返回了字形名说明fa-home对应的字符确实在字体中。6.2 在页面里收集实际出现的 fa 类与字体映射比对验证最终效果可以把页面上真实用到的图标类名汇总出来拿这份清单去和 4.6.3 的变量表核对。浏览器控制台执行const used new Set( [...document.querySelectorAll([class*fa-])] .flatMap(el [...el.classList]) .filter(cls cls.startsWith(fa-) cls.length 3) ); console.log([...used].sort());flatMap把多个元素的 classList 摊平成数组filter去掉fa基类和无关项得到一个去重后的图标清单。把这份清单逐条对照 variables.less缺哪个就说明项目里写了 4.6.3 不存在的图标名。做子集化时这份清单也是--unicodes参数的直接来源从 variables.less 查出每个名字对应的\f...码位再拼接成UF015,UF007...的格式。6.3 一条铁律生产环境的字体文件必须和页面同源用这套老资源包最省心的习惯是无论页面来自公共 CDN 还是自己服务器最终生产环境都让字体文件与实际页面同源。外部引用的字体一旦节点失效、跨域头变更你连页面代码都不用改就全部变成方框这种问题最难排查因为代码什么都没动。我自己接手的模拟项目里凡是这种旧资源包第一件事都是把它从外部引用变为本地静态资源再验证一遍字体请求状态。资源包的下载渠道不少重要的是拿到的包要文件齐全、版本锁死、内部表一致。验证过、确认过再用到生产里才不心虚。希望帮到你。本文还有配套的精品资源点击获取