html本身不支持ar渲染，需依赖webxr api与three.js或model-viewer等库实现；必须https部署（localhost除外），ios仅支持.usdz/.reality+quick look，安卓需arcore支持且chrome 81+。
HTML里直接做商品AR预览？不行，得靠WebXR + 3D库
纯HTML本身不支持AR渲染——它没有三维坐标系、摄像头访问、空间锚点或光照计算能力。所谓“HTML商品AR预览”，实际是用HTML容器承载基于WebXR API的JavaScript逻辑，配合three.js或model-viewer等库驱动AR体验。
常见错误现象：model-viewer在iOS上点“View in AR”没反应、安卓Chrome提示“AR not supported”、模型加载后漂浮错位。
- 必须部署在HTTPS环境（本地
localhost除外），否则navigator.xr为undefined - iOS仅支持
model-viewer+ Quick Look（需.usdz或.reality格式），不支持通用WebXR - 安卓需Chrome 81+且设备支持ARCore；部分中低端机型即使系统提示支持，也可能因传感器精度不足导致追踪抖动
用model-viewer快速实现基础商品AR（推荐新手）
这是目前兼容性最好、接入成本最低的方案，适合电商详情页嵌入单个高精度商品模型（如球鞋、耳机、家具）。
关键配置项：
-
ar属性必须显式开启：<model-viewer ar></model-viewer> -
src需指向.glb（通用）或.usdz（iOS专属），不能是.obj+.mtl组合 -
ios-src单独指定.usdz路径，否则iOS会降级为3D旋转视图 - 加
camera-controls和auto-rotate可提升非AR模式下的浏览体验
示例片段：
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
<model-viewer src="shoe.glb" ios-src="shoe.usdz" ar camera-controls auto-rotate alt="运动鞋3D模型"></model-viewer>
WebXR手动控制AR场景（需要自定义交互逻辑）
当你要叠加UI按钮、实时更换材质、或响应真实空间中的点击位置时，就得绕过model-viewer，用three.js + webxr-polyfill（仅作开发参考，生产环境慎用）手写XR会话。
核心步骤：
- 检测支持：
navigator.xr?.isSessionSupported('immersive-ar')，返回Promise，不是布尔值 - 启动会话前必须由用户手势触发（如
button.onclick），不能自动调用requestSession - 模型加载必须在
session.requestReferenceSpace('local-floor')之后，否则Y轴位置全乱（地板锚点未建立） - 每帧用
frame.getViewerPose(referenceSpace)获取摄像头位姿，再更新three.js相机矩阵
性能影响：未压缩的.glb超过8MB会导致iOS Safari加载失败；建议用gltf-pipeline工具压缩并转成DRACO编码。
为什么AR预览常卡在“正在初始化”或黑屏？
这不是代码写错了，而是环境链路中断。优先排查这三处：
- 检查
console是否有DOMException: Failed to execute 'requestSession' on 'XRSystem'——大概率是HTTPS未启用或非安全上下文（比如iframe sandbox未加allow-xr） - 安卓设备是否已安装
Google Play Services for AR（ARCore服务），旧版本不提示，只静默失败 -
model-viewer的shadow-intensity设为0会导致iOS无法识别地面，AR按钮灰显；设为1才能触发Quick Look
真正难的不是写几行代码，而是让不同品牌、不同系统版本、不同网络环境下的用户，都能在同一套标记里稳定唤起AR。模型格式、CDN缓存策略、fallback降级提示，这些比JS逻辑更消耗上线时间。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
