Android Studio XML布局预览失败多因环境配置问题，需依次检查主题兼容性、Preview API版本、自定义View构造函数、第三方库兼容性，并清理缓存重启。
Android Studio 的 XML 布局预览失败，通常不是代码写错了，而是环境、配置或依赖层面的问题。先别急着重写布局，按下面几个方向逐一排查，90% 的情况能快速解决。
检查主题和 Theme.AppCompat 是否匹配
预览依赖当前 layout 所用的 theme。如果 layout 中设置了 android:theme="@style/MyCustomTheme"，但该 theme 继承自错误的父类（比如没继承 Theme.AppCompat 或其子类），预览就会空白或报错 “Rendering failed”。
- 打开
res/values/styles.xml，确认你的自定义 theme 父类是Theme.AppCompat、Theme.MaterialComponents或兼容版本（如Theme.AppCompat.Light.DarkActionBar） - 在布局文件顶部，检查
tools:context指向的 Activity 是否使用了兼容主题；如果没指定，预览会默认用AppTheme，确保它也继承自 AppCompat - 临时把 layout 的
android:theme属性删掉，看预览是否恢复——能恢复就说明是主题问题
更新 Preview API 和渲染版本
预览窗口右上角有个小齿轮图标（⚙️），点击后可切换渲染引擎（如 Android API 30、33、34）。选中的 API 版本若与项目 targetSdk 不匹配，或该版本存在已知渲染 bug，就容易失败。
- 点击预览区右上角的“API 版本选择器”，尝试切换到一个稳定版本，比如 API 33（Tiramisu）或 API 31（Sv2）
- 避免选 “Latest Platform” 或未发布的预览版（如 API 35 Beta），它们对第三方控件或自定义 View 支持不完善
- 如果项目用了
androidx.appcompat:appcompat，确保它是较新版本（如 1.6.1+），老版本在高 API 上可能无法正确 inflate 自定义属性
排查自定义 View 和第三方库
预览器无法运行 Java/Kotlin 逻辑，所有自定义 View 必须提供带 Context, AttributeSet 的构造函数，并且不能在构造中调用 requireContext()、findViewById()、启动线程等运行时操作。
- 检查布局里是否引用了自定义 View；如果有，打开它的 Java/Kotlin 文件，确认存在
public XxxView(Context c, AttributeSet a)构造方法 - 把自定义 View 的构造函数中所有可能触发运行时异常的代码（如获取 Resources、访问 Activity、初始化网络模块）用
if (isInEditMode()) return;包裹 - 第三方库（如 Coil、Lottie、ConstraintLayout 2.x）若版本过旧或与当前 AGP/Gradle 不兼容，也可能导致预览崩溃；尝试暂时注释掉相关控件，看预览是否恢复
清理缓存并重启预览
有时候预览进程卡住或资源索引损坏，会导致持续失败，但项目本身完全正常。
- 点击菜单 File → Invalidate Caches and Restart → Invalidate and Restart
- 重启后，打开布局文件，先别动代码，等右下角 “Building…” 完成后再看预览
- 如果仍失败，尝试关闭硬件加速：在
Help → Edit Custom VM Options…中添加-Dsun.java2d.opengl.fbobject=false，重启 AS（适用于 macOS/Linux 显卡驱动冲突场景）
预览本质是个轻量级渲染沙盒，不跑真正 Activity 生命周期，所以它敏感但可控。多数时候只需调对 theme、选稳 API、护住自定义 View 构造逻辑，就能回来。
