使用AR.JS扫描NFT时自定义模型不显示的问题排查

问题复现 #

NFT可被正常检测，扫描时盒子能加载显示，但自定义GLB模型#avocado仅随NFT移动却不可见，已确认资源路径、脚本导入无异常，调整尺寸角度后仍无效。

用户代码片段：

<a-assets>
  <a-asset-item id="avocado" src="%BASE_URL%assets/models/Avocado.glb"></a-asset-item>
</a-assets>

<a-nft
  type="nft"
  url="%BASE_URL%assets/nfts/pattern-qr-code"
  smooth="true"
  smoothCount="10"
  smoothTolerance=".01"
  smoothThreshold="5"
>
  <a-entity scale="100 100 100">
    <a-entity
      position="0 0 0"
      gltf-model="#avocado"
      scale="20 20 20"
      rotation="-45 90 0"
      id="avocado-entity"
    ></a-entity>
    <a-box position="0 0.25 0" material="opacity: 0.5;" scale="0.5 0.5 0.5"></a-box>
  </a-entity>
</a-nft>
<a-entity camera id="camera"></a-entity>

排查与解决步骤 #

• 验证模型加载状态

  1. 打开浏览器开发者工具，在Console执行：console.log(document.querySelector('#avocado-entity').object3D.children)，如果输出为空数组，说明模型未成功加载。
  2. 检查Network面板中Avocado.glb的请求状态：
     • 若返回404，尝试将%BASE_URL%替换为相对路径（如./assets/models/Avocado.glb），确认资源文件是否存在于对应目录。
     • 若返回跨域错误，本地开发需启动本地服务器（如用npx serve），不能直接打开本地HTML文件。

• 修复层级缩放/位置异常

  1. 当前嵌套层级的总缩放倍数为100*20=2000，可能导致模型超出相机视野范围。简化缩放层级：

     <a-nft ...>
       <!-- 移除外层大缩放，直接调整模型自身尺寸 -->
       <a-entity
         position="0 0 0"
         gltf-model="#avocado"
         scale="2 2 2"
         rotation="-45 90 0"
         id="avocado-entity"
       ></a-entity>
       <a-box position="0 0.25 0" material="opacity: 0.5;" scale="0.5 0.5 0.5"></a-box>
     </a-nft>
     

  2. 调整模型位置，避免被遮挡或超出相机裁剪范围：将模型position改为0 1 0，同时检查相机的near/far参数（默认near=0.01，far=1000，可在相机实体添加camera="near: 0.001; far: 5000"扩大范围）。

• 解决材质/渲染问题

  1. 给场景添加环境光，避免模型因光照不足不可见：

     <a-light type="ambient" color="#ffffff" intensity="1"></a-light>
     

  2. 强制双面渲染，排除模型法线反向导致的背面剔除：

     <a-entity
       ...
       material="side: double"
     ></a-entity>
     

  3. 给模型添加自发光材质，快速验证模型是否存在：

     <a-entity
       ...
       material="emissive: #ffffff; emissiveIntensity: 1"
     ></a-entity>
     

• 使用调试工具定位
  按Ctrl+Alt+I打开A-Frame Inspector，选中avocado-entity，在3D视图中查看模型的实际位置、缩放，手动调整参数确认是否可见。

内容的提问来源于stack exchange，提问作者Dhawal Arora