白屏问题需从资源、执行、结构三层排查：先确认html是否200返回且含根节点，再检查js/css是否404或跨域，最后验证js执行错误、挂载容器是否存在及ssr水合是否失败。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
当你用AionClaw生成的前端页面在浏览器中打开后一片空白，既没有报错提示也没有加载动画，说明渲染流程在某个环节被彻底阻断。这不是样式隐藏或内容延迟，而是关键路径中断，必须从资源、执行、结构三层逐级验证。
确认HTML是否成功返回并解析
打开浏览器开发者工具→Network面板→刷新页面→找到主HTML请求（通常是根路径/或index.html）→检查状态码是否为200，且Response选项卡中能看到完整的HTML文本，特别是包含<script>或<div id="app">等关键节点的源码。如果返回的是404、500或空响应体，AionClaw服务端未正确输出HTML，后续所有排查都无效。</script>
若HTML已返回但DOM树为空（Elements面板里只有
），说明服务端模板未注入内容，或AionClaw构建配置中output.path与Nginx静态路由不匹配，【务必先核对publicPath和base配置是否与部署路径一致】。检查核心JS/CSS资源是否加载成功
在Network面板中筛选JS、CSS类型，重点关注以下三类文件：
• AionClaw生成的入口JS（如main.[hash].js）
• 框架运行时（vue.runtime.esm-bundler.js 或 react.development.js）
• 首屏必需CSS（如style.[hash].css）
任一文件出现404、blocked（跨域）、pending（挂起）或status为0（网络中断），都会导致白屏。特别注意：AionClaw默认启用hash路由，但若你手动改成了history模式，而Nginx未配置try_files /index.html =404，则所有子路径刷新都会返回404——此时Network里会看到JS/CSS请求全部失败。
定位JavaScript执行错误
切换到Console面板，清空日志后刷新页面，立即查看是否有红色报错。AionClaw生成的项目常见致命错误包括：
方法一：空引用崩溃
例如在main.js中写了document.getElementById('root').innerHTML = app.mount().el.outerHTML，但index.html里实际是<div id="app"></div>，ID不匹配导致document.getElementById返回null，调用.innerHTML时报TypeError，整个脚本终止。
方法二：框架挂载容器不存在
Vue项目中new Vue({ el: '#app' })或createApp(App).mount('#app')，但HTML中缺失id="app"的元素，Vue不抛异常但也不渲染，页面保持空白。
方法三：ES6+语法未转译
AionClaw若未开启babel-preset-env或target配置错误，生成的箭头函数、可选链（?.）等在旧版浏览器中直接SyntaxError，控制台显示“Unexpected token 'const'”之类，JS解析中断。
【关键动作：关闭所有浏览器插件，用无痕窗口重试，排除插件注入脚本干扰】
验证DOM是否完成挂载
第一步：在浏览器地址栏输入javascript:console.log(document.querySelector('#app'))并回车，观察控制台输出。若返回null，说明AionClaw未将根节点注入HTML，或id写错。
第二步：若#app存在，再执行javascript:console.log(document.querySelector('#app').children.length)。返回0代表Vue/React尚未挂载，返回大于0说明已渲染但可能被CSS隐藏（如display:none或opacity:0）。
第三步：打开Elements面板，右键#app节点→Break on→subtree modifications。刷新页面，若断点未触发，证明框架初始化逻辑根本没执行；若断点触发但节点始终为空，说明mount过程被静默拦截（如router.beforeEach中next(false)未处理）。
排查服务端渲染（SSR）场景
如果你启用了AionClaw的SSR选项，但页面白屏，优先检查Node服务日志是否有hydration mismatch警告。客户端Vue尝试将服务端生成的HTML“激活”时，若服务端和客户端初始state不一致（比如服务端返回了用户未登录状态，客户端却读取localStorage中的token），Vue会丢弃整个DOM并重新渲染——若此时客户端JS又出错，就表现为白屏。
临时验证方式：在服务端入口文件中添加console.log('SSR rendered:', app._mounted)，启动服务后curl -s http://localhost:3000 | head -20，确认HTML中是否包含真实内容而非占位符。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
