Shopify通过Liquid引入three.js资产无正常渲染效果的问题排查

AI 小北

2026-11-5

核心问题定位

片段结构冲突：自定义片段three-html.liquid内嵌套了完整的<head>、<body>全局标签，而Shopify主题根文件theme.liquid已经包含全页面的全局结构，渲染时会出现HTML标签嵌套顺序错误，导致浏览器解析异常，页面内容渲染中断。
资源路径错误：代码内使用相对路径src="three.js"引入Three.js库，Shopify静态资产必须通过内置asset_url过滤器生成可访问的完整路径，直接写文件名会被浏览器解析为当前页面路径下的资源，实际无法加载到Three.js文件，脚本会直接报THREE is undefined错误，无法执行后续3D渲染逻辑。
样式作用域错误：片段内直接写全局body { margin: 0; }样式，会覆盖店铺原有主题的全局布局边距，造成页面布局错乱、内容被挤出可视区域。
画布挂载错误：代码内直接通过document.body.appendChild(renderer.domElement)把Three.js画布挂载到全局body下，会被主题自带的导航栏、页脚、弹窗等模块的层叠顺序覆盖，就算脚本正常执行，也会因为画布被遮挡看不到3D效果。
执行时机错误：脚本没有等待DOM加载完成就执行容器查找，会因为DOM节点未渲染完成，出现找不到挂载目标的报错。

正确实现步骤

重构片段结构
删除three-html.liquid内所有<head>、<body>、<meta>、<title>类的全局标签，只保留独立组件结构：
- 新增一个带固定高度的独立容器作为3D画布的挂载点，避免画布出现高度为0的问题
- 所有样式都用容器ID做选择器限定作用域，不使用全局body、html选择器
正确引入Three.js资源
将上传到Shopify资产目录的Three.js文件，通过asset_url过滤器生成正确的可访问路径，禁止直接写相对路径文件名，正确写法为：
<script src="{{ 'three.min.js' | asset_url }}"></script>
调整画布挂载逻辑
把原代码中挂载到全局body的逻辑，改为挂载到自定义独立容器下，避免和主题原有模块层叠冲突。
修正场景初始化逻辑
增加DOM加载完成的事件监听，等页面DOM结构渲染完成后再初始化Three.js场景，同时用容器的实际宽高计算相机比例，替代原来的全局窗口尺寸计算逻辑，避免画布尺寸溢出。

修正后的three-html.liquid参考实现代码：

<!-- 3D展示独立容器 -->
<div id="three-cube-container" style="height: 400px; margin: 2rem 0;">
  <style>
    #three-cube-container { position: relative; }
    #three-cube-container canvas { position: absolute; top: 0; left: 0; }
  </style>
</div>

<!-- 正确通过资产过滤器引入Three.js静态资源 -->
<script src="{{ 'three.min.js' | asset_url }}"></script>
<script>
  // 等待DOM完全加载后再初始化3D场景
  document.addEventListener('DOMContentLoaded', () => {
    const cubeContainer = document.getElementById('three-cube-container');

    const scene = new THREE.Scene();
    // 使用容器实际尺寸计算相机宽高比
    const camera = new THREE.PerspectiveCamera(
      75,
      cubeContainer.clientWidth / cubeContainer.clientHeight,
      0.1,
      1000
    );

    const renderer = new THREE.WebGLRenderer();
    renderer.setSize(cubeContainer.clientWidth, cubeContainer.clientHeight);
    // 画布挂载到自定义容器内，不侵入全局body
    cubeContainer.appendChild(renderer.domElement);

    const geometry = new THREE.BoxGeometry();
    const material = new THREE.MeshBasicMaterial({ color: 0x00ff00 });
    const cube = new THREE.Mesh(geometry, material);
    scene.add(cube);

    camera.position.z = 5;

    const animate = () => {
      requestAnimationFrame(animate);
      cube.rotation.x += 0.01;
      cube.rotation.y += 0.01;
      renderer.render(scene, camera);
    };
    animate();

    // 增加窗口尺寸变化监听，适配不同屏幕大小
    window.addEventListener('resize', () => {
      camera.aspect = cubeContainer.clientWidth / cubeContainer.clientHeight;
      camera.updateProjectionMatrix();
      renderer.setSize(cubeContainer.clientWidth, cubeContainer.clientHeight);
    })
  })
</script>

效果排查要点

打开浏览器开发者工具的控制台面板，排查两类核心报错：
- 如果提示THREE is not defined，检查资产目录内的Three.js文件名和代码内写的文件名是否完全匹配、大小写是否一致，Shopify的资产路径是区分大小写的
- 如果提示Cannot read properties of null (reading 'appendChild')，检查容器ID的拼写是否正确、是否增加了DOM加载完成的监听，避免脚本早于容器渲染执行
确认容器设置了固定的高度值，不要使用无固定高度的块级容器，避免画布因为父容器高度为0无法显示
不要在片段内写全局作用域的样式规则，所有样式都要绑定到自定义容器的ID上，避免破坏店铺原有主题的布局逻辑

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