iPad Safari 中 WebXR AR 模式需 HTTPS 协议、用户手势触发、iOS 16.4+、glTF 2.0 格式模型，file:// 协议因安全限制被禁用 navigator.xr 接口。
iPad 上无法直接用 HTML5 “导入” AR 素材——HTML5 本身不支持原生 AR 渲染，ARKit 和 WebXR 是两条互不兼容的技术路径。所谓“HTML5 导入 AR”，实际是通过 WebXR 在 Safari（iOS 16.4+）中加载基于 glTF 的 3D 模型，并启用 AR mode；但该能力受限极多，不是文件拖拽或本地 file:// 协议能触发的。
为什么 file:// 或本地 HTML 打不开 iPad 上的 WebXR AR？
iPad Safari 对 WebXR 的 AR 支持强制要求 HTTPS + 用户手势触发 + 设备权限 + 合规模型格式。本地打开的 HTML 文件走 file:// 协议，直接被 Safari 拦截 navigator.xr 接口，控制台报错：TypeError: navigator.xr is undefined 或 SecurityError: XR device access denied。
-
WebXRAR 模式只在 HTTPS 网站下可用（包括localhost，但需用http-server等工具起服务） - 必须由用户真实点击/触摸事件（如
button.onclick）调用requestSession('immersive-ar')，不能自动启动 - 模型必须是
glTF 2.0（推荐.glb二进制格式），且带draco压缩的需额外引入解码器 - iOS 16.4 是首个支持
immersive-ar的版本，旧系统返回not-supported
怎样让 HTML 页面在 iPad Safari 中真正唤起 AR 模式？
核心是绕过协议限制、满足启动条件、正确请求会话。以下是最小可行路径：
- 用
http-server（Node.js）或 Pythonpython3 -m http.server 8000启一个本地 HTTP 服务，访问http://localhost:8000 - 确保页面有明确按钮，例如：
<button id="ar-button">View in AR</button> - JS 中监听点击，调用
navigator.xr.requestSession('immersive-ar')，并处理session.updateRenderState()和参考空间 - 使用
@google/model-viewer可大幅简化（它封装了 WebXR 兼容逻辑）
<script type="module" src="https://unpkg.com/@google/model-viewer@latest/dist/model-viewer.min.js"></script>
<model-viewer
src="scene.glb"
ar
ar-scale="auto"
camera-controls
environment-image="neutral"
exposure="1.5"
poster="poster.jpg"
shadow-intensity="1"
style="width: 100%; height: 400px;">
<div slot="progress" style="font-size: 14px;">Loading...</div>
</model-viewer>
<script>
document.querySelector('model-viewer').addEventListener('load', () => {
console.log('Model loaded — AR button ready');
});
</script>
常见失败原因和对应检查点
即使代码正确，仍可能黑屏、无 AR 按钮、或提示“AR not available”。按顺序排查：
立即学习“前端免费学习笔记（深入）”；
-
console.log(navigator.xr)返回undefined→ 确认 iOS 版本 ≥ 16.4，且页面运行在 HTTPS 或localhost - AR 按钮不出现 → 检查
<model-viewer>是否含ar属性，且src指向可访问的.glb（非本地file://路径） - 点击后白屏或崩溃 → 模型含不支持材质（如透明度混合未关闭）、法线未烘焙、或超过 10MB 导致内存溢出
- AR 中模型比例失真 → 不要用
ar-scale="fixed"，改用ar-scale="auto"让设备自动匹配平面
真正难点不在写 HTML，而在于 Safari 的 WebXR 实现非常保守：它不支持 plane detection 的细粒度控制，不暴露 XRPlane API，也不允许自定义光照探针。所以“导入 AR 素材”本质是交由 Safari 内置 AR 渲染器接管，你只能配置入口参数，不能干预底层跟踪逻辑。这点和原生 Swift + ARKit 完全不同。
