Jetpack Compose预览不显示自定义Typeface（Material3）问题排查

数据老陈

2026-7-8

问题：Jetpack Compose预览无法显示自定义字体，运行应用正常

我在运行应用时能正常看到主题中的自定义字体，但在Jetpack Compose预览中无法显示。我已将预览组件包裹在自定义主题Composable中，代码如下：

@Preview(
    showBackground = true,
    widthDp = 480,
    heightDp = 960,
)
@Composable
fun PreviewAccessResultScreen() {
    CustomTheme {
        TestScreen()
    }
}

根据相关Stack Overflow线程，这种方式应该可行，但问题仍存在，请问可能遗漏了什么？

可能的原因及解决方法

字体加载逻辑不兼容预览环境：如果自定义主题中使用了异步方式加载字体（比如结合remember和协程异步读取），Compose预览不支持异步操作，会导致字体加载失败。建议改为同步加载，直接通过FontFamily(Font(R.font.your_custom_font))的方式定义字体族。
预览缓存或项目构建异常：点击预览面板右上角的垃圾桶图标清理预览缓存，然后执行Rebuild Project重新构建项目，确保字体资源被正确索引到预览环境中。
主题字体配置未全局生效：检查CustomTheme中的Typography配置，确认defaultFontFamily是否正确设置为自定义字体族，避免子组件（如Text）硬编码其他字体覆盖主题配置。
Android Studio版本兼容性问题：部分旧版本Android Studio对Compose预览的字体渲染存在bug，建议升级到最新稳定版Android Studio，确保预览功能的兼容性。
字体文件或资源配置错误：确认字体文件放置在res/font目录下，文件名符合Android资源命名规范（仅小写字母、下划线），且文件未损坏。如果是多字重字体，要确保每个字重的文件都正确配置到字体族中。