Android Studio Jetpack Compose预览渲染失败求助

API 探路者

2026-6-20

Jetpack Compose预览无法渲染的排查方案

以下是针对你遇到的Compose预览不渲染问题的常见排查和解决步骤：

核对Compose依赖与Android Studio版本兼容性
Compose Compiler和Android Studio版本有严格的对应关系，版本不匹配是预览失败的常见原因。比如AS Hedgehog（2023.1.1）对应的Compose Compiler版本应为1.5.3，Compose BOM版本为2023.10.01。你可以在项目级build.gradle.kts和模块级app/build.gradle.kts中检查依赖配置，确保版本对应。
检查预览注解的正确性
确认预览函数使用了正确的@Preview注解，且函数符合要求：无参数、标记@Composable注解，示例代码如下：
```
@Preview(showBackground = true, name = "默认预览")
@Composable
fun SimpleScreenPreview() {
    YourAppTheme {
        SimpleScreen()
    }
}
```
避免在注解中使用无效参数，比如拼写错误的设备名等。
修复编译错误
即使代码看起来正常，隐性的编译错误（如变量未初始化、依赖缺失）也会导致预览失败。先执行Build -> Make Project，查看Build窗口的错误提示，修复所有编译问题后再尝试预览。
禁用实时运行功能
实时运行（Instant Run/Apply Changes）可能干扰预览渲染，进入AS设置搜索"Instant Run"，关闭相关选项后重启Android Studio。
清除Android Studio缓存
除了清理重建项目，还可以执行File -> Invalidate Caches... -> Invalidate and Restart，彻底清除AS缓存后再尝试预览。
检查预览设备配置
预览面板顶部的设备选择是否为有效配置，尝试切换到其他预设设备（如Pixel 7），或创建新的设备配置后再预览。
排查代码逻辑问题
检查你的Composable函数是否存在违规操作：比如调用非Composable的挂起函数、未正确使用Compose上下文（如错误获取Context）、布局参数错误等。