微信小程序端直接用标签最省事，原生支持gltf格式（.glb/.gltf），模型放/static/、宽高需显式设置；h5端须用renderjs+three.js；xr-frame仅限微信小程序；插件市场组件易致包体积过大或兼容问题。

小程序端直接用 <model></model> 标签最省事

微信小程序原生支持 <model></model>，uni-app 小程序平台可直接使用，无需引入任何 js 库，也不依赖 renderjs 或 webgl 上下文。它专为轻量级 3d 展示优化，加载快、内存低、手势旋转缩放开箱即用。

• 只支持 glTF 格式：必须是 .glb 或 .gltf（推荐用二进制 .glb，单文件、免路径解析）
• 模型需放在 /static/ 下（不能放 /assets/，否则真机找不到）
• 宽高必须显式设置，否则渲染区域为 0 × 0：style="width: 300px; height: 300px;"
• 不支持自定义光照、材质或运行时动画，仅基础查看 —— 想加点击交互或换装？得切 Three.js

示例：<model src="/static/robot.glb" style="width: 100%; height: 400px;"></model>

H5 端用 renderjs + Three.js 是唯一可行路径

uni-app 的 renderjs 是 H5 端运行 Three.js 的“安全区”：它在独立 JS 线程执行，能访问 canvas 和 WebGL 上下文，又不会被 Vue 响应式系统干扰。直接在 <script></script> 里 import three 并操作 DOM？真机白屏或报 document is not defined。

• renderjs 脚本必须用 <script module="xxx" lang="renderjs"></script> 声明，且只能写在 .vue 文件内（不能抽离成 .js）
• canvas 必须带 id，且要在 mounted() 后通过 document.getElementById() 获取（this.$refs 在 renderjs 中不可用）
• 别在 renderjs 里调用 console.log 或 alert，调试靠 uni.postMessage 回传数据到主线程
• H5 端模型加载建议用 THREE.GLTFLoader，但注意：loader 本身不支持直接读取本地 static 路径，要用 new THREE.FileLoader().setPath('/static/') 配合相对路径

关键代码片段：const canvas = document.getElementById('3dCanvas'); —— 这行漏掉或 ID 写错，整个场景就黑屏。

跨平台项目慎选 XR-Frame

XR-Frame 是微信小程序专属方案，体积小、性能好、API 简洁，但它和 uni-app 的跨平台承诺天然冲突：一旦你用了 <xr-scene></xr-scene>，App 和 H5 端直接报错或空白。它适合「纯微信小程序」且对启动速度敏感的场景（比如电商商品页 3D 查看），不适合多端统一维护。

• manifest.json 中插件配置必须严格匹配："provider": "wx6afed118d9e81df9"，少一个字符就加载失败
• 模型同样只认 .glb，且需开启 HTTPS（开发工具可勾选“不校验合法域名”，真机必须配业务域名）
• 不支持 v-if 动态控制 <xr-model></xr-model> 显示隐藏，切换会导致上下文丢失，得用 v-show + opacity 控制
• 遇到 XRFrame is not defined 错误？先检查微信开发者工具是否更新到最新版（2026 年起要求 v1.07.20260101+）

Three.js 插件市场组件容易踩包体积和分包坑

插件市场搜 “3D模型” 能快速集成，但多数封装了完整 three.min.js（超 500KB），对小程序首屏影响极大。尤其当你只展示一个静态模型时，为这点功能引入整套引擎，得不偿失。

• 务必确认插件是否支持分包：在 subNVue 或 subNVue 页面中使用，主包体积才可控
• 很多插件文档写“支持 GLTF”，实际只处理了基础网格，遇到带骨骼动画或 PBR 材质的模型直接崩溃（错误如 TypeError: Cannot read property 'array' of undefined）
• 插件内部若用 require('three') 而非 import * as THREE，在 Vue 3 + Vite 构建下会报 Cannot find module 'three'
• 真机调试时发现模型“卡顿掉帧”？大概率是插件没做 requestAnimationFrame 节流，或未启用 renderer.setPixelRatio(window.devicePixelRatio)

真正省心的做法是：小程序用 <model></model>，H5 用最小化 renderjs + GLTFLoader，其他平台暂不支持就降级为 2D 图片 —— 别硬塞一个“看起来能跑”的方案。