求助：Font.loadAsync调用持续报错的实现与排错咨询

常见报错排查方向 #

• 依赖版本不匹配
  优先执行npx expo install expo-font expo-splash-screen安装和当前项目Expo SDK版本完全匹配的依赖，不要单独用npm/yarn安装不匹配的高版本/低版本包，裸RN项目还要确认已经完成原生端相关link配置。
• 加载时机错误
  必须等待Font.loadAsync执行完成、字体资源全部加载完毕后，再渲染引用了自定义字体的业务组件，加载过程中保持启动页显示、不要提前渲染页面内容，否则会直接触发字体找不到的报错。
• 配置细节错误
  • 字体文件的require路径要和实际存储路径完全一致，真机环境对文件名大小写完全敏感，大小写写错、路径层级错都会导致加载失败
  • Font.loadAsync中定义的字体key，和组件样式里写的fontFamily值必须完全一致，多空格、拼写错误、大小写不匹配都会触发报错
  • 优先使用无损坏的ttf格式字体文件，部分裁剪过的otf字体、损坏的字库文件在移动端无法正常加载
  • 使用Expo Router的项目，字体加载逻辑要写在根布局文件中全局执行，不要写在子页面里重复加载或者延迟加载

可直接复用的标准实现代码 #

import React, { useState, useEffect } from "react";
import { View, Text } from "react-native";
import * as Font from "expo-font";
import * as SplashScreen from "expo-splash-screen";

// 阻止启动页自动隐藏，等资源加载完再关闭
SplashScreen.preventAutoHideAsync();

export default function App() {
  const [appReady, setAppReady] = useState(false);

  useEffect(() => {
    const loadResources = async () => {
      try {
        await Font.loadAsync({
          // key为后续样式中引用的fontFamily名称，可自定义
          "CustomSans": require("./assets/fonts/CustomSans-Regular.ttf"),
          "CustomSans-Bold": require("./assets/fonts/CustomSans-Bold.ttf"),
        });
      } catch (e) {
        console.warn("资源加载异常：", e);
      } finally {
        setAppReady(true);
        await SplashScreen.hideAsync();
      }
    };

    loadResources();
  }, []);

  // 资源未加载完成时不渲染业务页面
  if (!appReady) return null;

  return (
    <View style={{ flex: 1, justifyContent: "center", alignItems: "center" }}>
      <Text style={{ fontFamily: "CustomSans", fontSize: 18 }}>
        自定义字体测试内容
      </Text>
    </View>
  );
}

快速定位技巧 #

如果报错信息提示fontFamily 'xxx' is not a system font and has not been loaded through Font.loadAsync，直接核对三个点即可：字体是否在页面渲染前加载完成、fontFamily名称拼写是否和加载时定义的key一致、字体文件路径是否正确，这类报错90%以上都是这三个问题导致的。

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