React Native Vector Icons FontAwesomeFreeSolid 包演进史：从 FontAwesome 7 迁移到 Expo 配置插件的完整版本解读

• UI组件
• 移动开发

@react-native-vector-icons/fontawesome-free-solid是 react-native-vector-icons 仓库中负责封装 Font Awesome 免费版 Solid 字体的独立 npm 包，其 CHANGELOG.md 完整记录了该包自 2025 年 11 月随 FontAwesome 7 重构诞生、到 2026 年 5 月稳定在 1.1.2 的九个版本迭代。本文以该 CHANGELOG 为主体脉络，结合包内源码与 docs/SETUP-EXPO.md 配置指南，逐版本拆解每一次变更背后的实现机制，帮助你在升级依赖、排查字体加载问题时快速定位根因。

一、包定位：Font Awesome 7 时代的 Solid 字体子包

在 react-native-vector-icons 的包结构重组中，Font Awesome 免费字体被拆分到多个独立包中，fontawesome-free-solid对应其中的 Solid 风格子集。从 package.json 可以看到，该包依赖@react-native-vector-icons/common（workspace:^工作区依赖），字体文件为fa-solid-900.ttf，glyphmap 文件为FontAwesomeFreeSolid.json。

当前版本 1.1.2 对应的 Solid 图标集共收录2000 个 glyph（可通过Object.keys(require('./glyphmaps/FontAwesomeFreeSolid.json')).length验证），glyph 名称采用 Font Awesome 7 的命名方式，例如address-book、air-freshener、alarm-clock等，映射值为对应的 Unicode 码点。

与同仓库其他字体包一致，它提供了双入口：

• 默认入口 src/index.ts：通过createIconSet(glyphMap, { postScriptName, fontFileName, fontSource })创建组件，其中fontSource: require('../fonts/fa-solid-900.ttf')会把.ttf打进 JS bundle，配合动态字体加载机制在运行时注册；
• 静态入口 src/static.ts：同样的createIconSet调用但不携带fontSource，字体仅通过原生构建（autolinking 复制.ttf进二进制）提供，用于 Development Build 场景避免字体双份打包。

两者共享同一postScriptName: 'FontAwesome7Free-Solid'与fontFileName: 'fa-solid-900.ttf'，组件渲染逻辑完全由 create-icon-set.tsx 中的工厂函数createIconSet统一实现，包括 glyph 解析（数字码点转字符串）、getImageSource/getImageSourceSync图片源生成等能力。

二、版本演进全景：从 0.1.0 到 1.1.2

CHANGELOG 记录的九个版本可以划分为三个阶段：FontAwesome 7 迁移期（0.1.x）、能力补全期（0.2.0 → 1.0.0）、Expo 生态整合期（1.1.x）。整体时间线如下：

其中每一版变更都直接对应到当前包结构的某个文件，下面逐版本深入解读。

三、0.1.0：FontAwesome 7 迁移与包结构重组

0.1.0 是包的起点，变更内容为 "upgrade FontAwesome to version 7 with new package structure"，同时把@react-native-vector-icons/common依赖提升到 12.4.0。这次重构带来了两处可见的包结构变化：

1. 字体与元数据分离：fonts/fa-solid-900.ttf与glyphmaps/FontAwesomeFreeSolid.json分目录存放，并在 package.json 的exports字段中开放了./glyphmaps/*.json与./fonts/*.ttf子路径导出，方便上层按需引用字体文件和码点映射。
2. 组件代码生成化：index.ts与static.ts的文件头注释明确标注 "This is a generated file"，由packages/generator-react-native-vector-icons的模板生成，任何对包结构的修改都应发生在生成器而非本包内。

从源码结构推断，0.1.0 之前的旧版包（沿用 Font Awesome 6 时代的整体包）被拆分为 free-solid、free-regular、free-brands 等独立包，这正是 CHANGELOG 所称 "new package structure" 的直接体现。

四、0.1.1：Android targetSdkVersion 与 READ_PHONE_STATE 权限修复

0.1.1 的修复项为 "add targetSdkVersion to avoid READ_PHONE_STATE permission"，关联 PR #1866 与 issue #1861。这个修复的实质是：在旧版 Android 构建配置下，应用清单（Manifest）被隐式授予READ_PHONE_STATE权限，而该权限在商店审核与用户隐私层面都不受欢迎。

从当前 AndroidManifestNew.xml 与 AndroidManifest.xml 可以看到，该包的 Manifest 内容为空壳——package声明为com.reactnativevectoricons.fontawesome_free_solid，没有声明任何权限或组件。同时 VectorIconsFontAwesomeFreeSolidPackage.kt 中的getModule返回null、getReactModuleInfoProvider返回空映射，说明该包在 Android 侧是纯资源包（仅提供字体资源，由 autolinking 复制进 APK），并不注册任何原生模块——这进一步印证了权限问题的根因在于构建配置而非代码逻辑，通过显式设置targetSdkVersion即可让权限声明回归正常。

五、0.1.2：Font Awesome 7.2.0 升级与 generator 自动化

0.1.2 包含两项变更：

• 字体升级：将 Font Awesome 免费版从 7.1.0 升级到 7.2.0（PR #1874），字体文件与 glyphmap 同步更新；
• 生成器自动化：generator 在生成过程中自动更新.yo-rc.json中的上游版本号（PR #1873），避免手工维护版本信息造成遗漏。

该版本在 CHANGELOG 与 README 的版本对应表中有直接呼应（见下文第七节），同时@react-native-vector-icons/common也同步升级到 12.4.1。这也解释了为什么glyphmaps/FontAwesomeFreeSolid.json中会出现"ad": 63041这样的高码位映射——部分图标使用 Unicode 私有区（PUA）码点，字体升级时这些映射会随上游 metadata 重新生成。

六、0.2.0 与 1.0.0：静态导出能力与 API 稳定

0.2.0 的变更 "expose static export for icon families"（PR #1880）引入了当前包结构中的static.ts双入口设计。对比两个文件可以清晰看出设计意图：

在 create-icon-set.tsx 中，fontSource的有无直接决定动态加载是否可用：canUseDynamicLoading = !!fontSource && isDynamicLoadingEnabled()，静态入口因缺少fontSource而跳过dynamicLoader.loadFontAsync逻辑，字体引用直接落到原生已注册的postScriptName: 'FontAwesome7Free-Solid'上。

随后的 1.0.0（2026-03-26）把common依赖升级到 13.0.0，标志该包 API 正式稳定，进入语义化版本 1.x 阶段。

七、1.1.x：Expo 配置插件整合

1.1.0 引入 "add expo config plugins"（PR #1893），为包增加了 app.plugin.js。这是一个基于@expo/config-plugins的withInfoPlist插件，其核心逻辑是：

const fonts = ['fa-solid-900.ttf']; c.modResults.UIAppFonts = [...new Set([...(c.modResults.UIAppFonts || []), ...fonts])];

即把fa-solid-900.ttf追加到 iOSInfo.plist的UIAppFonts数组（自动去重），让 iOS 在启动时加载该字体。配合静态导入使用时，需要在app.json或app.config.js的plugins数组中注册：

{ "expo": { "plugins": ["@react-native-vector-icons/fontawesome-free-solid"] } }

随后执行npx expo prebuild重新生成原生工程。根据 docs/SETUP-EXPO.md 的说明，动态导入（默认入口）无需任何原生配置、兼容 Expo Go；而静态导入依赖原生构建，不支持 Expo Go，字体也无法通过 OTA 更新——这正是 1.1.0 增加配置插件的动机：让静态导入的 iOS 字体注册自动化。

1.1.1（2026-04-23）修复了 "expo plugin exports"（PR #1909），即此前插件模块的导出方式存在缺陷，导致部分构建工具解析app.plugin.js时失败；修复后插件作为 CommonJS 模块通过module.exports = (config) => withInfoPlist(...)正常导出。1.1.2（2026-05-24）则将common依赖升至 13.0.1，属于常规的依赖同步升级。

八、上游字体版本与包版本对应关系

该包 README 中专门说明了版本对应策略：12 之前的旧版字体包版本跟随上游 Font Awesome 版本号；包结构重组后改为独立版本号，并用一张对应表记录每个包版本内置的字体版本：

结合 CHANGELOG 可以精确对齐：0.1.0 首次引入 Font Awesome 7（7.1.0），0.1.2 的 "upgrade Font Awesome to 7.2.0" 变更即对应表中 7.2.0 的引入。也就是说，0.1.2 及以上版本内置的字体均为 7.2.0，当前 1.1.2 包内置的也正是该版本（见 package.json 中 devDependencies 的@fortawesome/fontawesome-free: 7.2.0）。升级包版本时，可通过该表快速判断字体资源是否发生了实质性变化。

九、版本升级实践建议

结合 CHANGELOG 与包源码，针对不同使用场景给出如下升级建议：

1. Expo 项目使用默认（动态）导入：无需关心 config plugin，直接升级包版本即可；字体通过expo-font在首次渲染时注册（Expo SDK ≥ 52 支持），并可随 OTA 更新。
2. Development Build 使用静态导入：升级到 1.1.x 后务必确认app.json的plugins数组已加入该包，并重新执行npx expo prebuild，否则 iOS 上字体不会出现在UIAppFonts中。
3. 关注 common 依赖版本：fontawesome-free-solid的所有逻辑都委托给@react-native-vector-icons/common，跨大版本升级（如 12.x → 13.x）时注意检查 common 的 CHANGELOG 是否有破坏性变更，并保持工作区内所有字体包与 common 版本对齐。
4. 校验 glyphmap 完整性：升级字体后可用Object.keys(glyphMap).length与官方 Solid 图标数对比，确认字体与码点映射未失配；本包 7.2.0 对应 2000 个 Solid 图标。
5. 不要直接修改生成文件：index.ts、static.ts、podspec、app.plugin.js均为生成器产物，如需自定义行为应修改packages/generator-react-native-vector-icons的模板后再生成。

从 0.1.0 到 1.1.2，fontawesome-free-solid走完了从 FontAwesome 7 迁移、静态导出补全、到 Expo 配置插件整合的完整路径。理解这份 CHANGELOG，等于同时掌握了该包的资源组织方式、双入口设计动机与原生构建集成要点，是排查字体加载与权限类问题的第一手参考资料。

• UI组件
• 移动开发