iPad上GLB/GLTF穿模主因是iOS Safari WebGL对深度缓冲、透明排序等处理异常，需启用阴影映射、适配Retina像素比、禁用半透明材质深度写入。

iPad 上用 HTML5 加载 3D 模型（如 GLB/GLTF）时出现穿模，根本原因不是“HTML5 不行”，而是 WebGL 渲染管线在 iOS Safari 有限资源下对深度缓冲、透明排序、法线翻转等处理不一致导致的。直接改模型或换引擎成本高，优先从加载逻辑和渲染配置入手。

GLTFLoader 加载后没启用 renderer.shadowMap.enabled 导致阴影层叠穿模

iOS Safari 的 WebGL 实现对阴影映射（shadow mapping）默认关闭，而很多 GLB 模型依赖阴影判断图层顺序。不启用会导致多个 mesh 投影重叠时 Z 缓冲失效，视觉上像“穿透”。

• 必须在 new THREE.WebGLRenderer() 初始化后立即设置：

  renderer.shadowMap.enabled = true;
  renderer.shadowMap.type = THREE.PCFSoftShadowMap;

• 每个需要投射/接收阴影的 mesh 都要显式开启：

  mesh.castShadow = true;
  mesh.receiveShadow = true;

• iPad 上 THREE.BasicShadowMap 容易糊边穿模，强制用 PCFSoftShadowMap 或 VSMShadowMap

renderer.setPixelRatio(window.devicePixelRatio) 没适配 iPad Retina 屏引发 Z-fighting

iPad 的高 PPI 屏幕若未正确设置像素比，WebGL 会用低分辨率 framebuffer 渲染，深度缓冲精度下降，相近 Z 值的面（比如衣服贴身体、头盔贴头皮）就会高频闪烁穿模。

htmlppt.skill

把任意文章或文档内容转换成精美的全屏翻页 HTML 演示文件（幻灯片风格）。当用户发来一篇文章、文档链接、Markdown 内容、或粘贴的文本，并且希望生成演示用的 HTML 时触发。支持任意内容来源：iWiki 链接、KM 链接、本地文件路径、直接粘贴的文本。生成的 HTML 文件保存到本地工作区，并通过企微直接发送给用户。触发词示例：帮我把这篇文章做成PPT、转成演示文档、生成HTML幻灯片、做个演示、转成可以演示的格式、article to deck、make a slide。

下载

• 务必在 renderer 创建后、首次 render() 前执行：

  renderer.setPixelRatio(window.devicePixelRatio || 2);

• 监听 resize 时也要同步更新：

  window.addEventListener('resize', () => {
    renderer.setPixelRatio(window.devicePixelRatio);
    renderer.setSize(window.innerWidth, window.innerHeight);
  });

• 不要写死 setPixelRatio(2) —— 新款 iPad Pro 是 2.8，硬编码会加剧 Z-fighting

GLB 模型含半透明材质（alphaMode: BLEND）但没关深度写入

GLTF 中 alphaMode: "BLEND" 的材质（如玻璃、布料）在 iOS Safari 下默认仍写入深度缓冲，导致后绘制的不透明物体被错误剔除，看起来像“从内部透出”。

立即学习“前端免费学习笔记（深入）”；

• 加载后遍历所有 material，手动禁用深度写入：

  gltf.scene.traverse((obj) => {
    if (obj.isMesh && obj.material?.transparent) {
      obj.material.depthWrite = false;
    }
  });

• 若需保留部分深度关系，改用 alphaMode: "MASK" 并设 alphaCutoff: 0.5，iOS 兼容性更好
• 避免在同一个 mesh 上混用 transparent: true 和 opacity: 0.99 —— Safari 会误判为全透明并跳过深度测试

穿模问题在 iPad 上往往不是单点故障，而是深度测试、像素比、透明混合三者叠加失准。调试时先关掉所有阴影和透明效果，确认基础渲染无穿模，再逐个开回来验证——否则容易把 zNear/zFar 设置过窄误判成模型问题。