本文详解在 astro 框架中嵌入 a-frame 的关键步骤，重点解决因脚本加载机制不兼容导致的空白页问题，并提供可直接运行的配置方案与最佳实践。
本文详解在 astro 框架中嵌入 a-frame 的关键步骤，重点解决因脚本加载机制不兼容导致的空白页问题，并提供可直接运行的配置方案与最佳实践。
Astro 默认对 <script> 标签执行服务端预渲染优化，会移除或延迟执行外部 JS 脚本（如 A-Frame），从而导致 <a-scene> 等自定义元素未被解析、页面长期处于空白加载状态——这正是你遇到“loading screen, nothing happening”的根本原因。
要使 A-Frame 在 Astro 中正常初始化，必须显式告知 Astro：该脚本需内联执行（即跳过默认优化），否则 A-Frame 的 Web Component 注册逻辑无法触发，<a-scene> 将始终作为未识别的 HTML 元素被忽略。
✅ 正确做法是在引入 A-Frame 的 <script> 标签中添加 is:inline 属性：
---
// src/pages/index.astro
---
<head>
<script src="https://aframe.io/releases/1.5.0/aframe.min.js" is:inline></script>
</head>
<body>
<a-scene xr-mode-ui="enabled: false">
<a-sky
id="backgroundRotation"
src="/space2.png"
rotation="0 0 0"
transparent="true"
></a-sky>
<a-entity
camera
look-controls="enabled: false"
wasd-controls="enabled: false"
></a-entity>
</a-scene>
</body>⚠️ 注意事项：
- src="/space2.png" 路径需置于 public/ 目录下（如 public/space2.png），Astro 中静态资源必须放于 public/ 才能通过 / 前缀访问；
- transparent="true" 是标准布尔属性写法（非 enabled:true）；
- 若使用本地安装的 A-Frame（npm install aframe），请配合 is:inline + import 方式或通过 Astro 的 client:load 指令动态加载，避免 SSR 冲突；
- 不推荐使用 npx astro add aframe —— A-Frame 是纯客户端库，非 Astro 集成（Integration），该命令仅适用于官方支持的适配器。
? 进阶建议：为提升性能与可维护性，可将 A-Frame 场景封装为 .tsx 或 .svelte 组件，并通过 client:only 或 client:load 指令按需 hydrate，彻底隔离其运行时依赖于客户端环境。
至此，你的 360° 全景背景即可在 Astro 页面中稳定渲染，并与 Astro 的渐进式 hydration 和页面过渡能力无缝协同。
