You need to enable JavaScript to run this app. Three.js跟随官方教程搭建项目时浏览器仅显示白屏问题求助
优惠活动
大模型
产品
解决方案
定价
更多

Three.js跟随官方教程搭建项目时浏览器仅显示白屏问题求助

Three.js 页面白屏问题排查与解决方案

核心问题定位

  • nomodule属性的反向误用:当前引入main.js的script标签携带nomodule属性,该属性的作用是告知支持ES模块的现代浏览器跳过执行当前脚本,专门用于为不支持模块语法的老旧浏览器做脚本兜底。该属性会导致main.js完全不被浏览器执行,后续所有Three.js渲染逻辑都无法触发,是白屏的直接原因。
  • 浏览器无法识别npm安装的裸模块导入。main.js中import * as THREE from 'three'属于裸模块导入语法,这类语法是面向前端构建工具设计的——浏览器无法直接把字符串标识three映射到本地node_modules目录下的Three.js实际文件路径。哪怕删掉nomodule属性,浏览器也会直接抛出模块解析失败的错误,无法正常运行。此前尝试启动本地静态服务器无效,是因为静态服务器仅能解决本地文件访问的跨域限制,无法完成裸模块的路径映射。
  • 相机参数顺序错误。即便前面两个问题全部解决,当前相机初始化代码也存在参数错位问题。透视相机的标准参数顺序为「视场角、宽高比、近裁剪面、远裁剪面」,当前代码把第二个参数传为窗口宽度值、第三个参数传为窗口高度值,完全打乱参数顺序,会导致视锥计算错误,即便完成渲染也可能无任何可见内容。

具体修复步骤

  1. 修正index.html中的script标签写法
    把原来的<script nomodule src="js/main.js"></script>替换为带模块声明的标签:
    <script type="module" src="js/main.js"></script>
    
    这个写法既去掉了会阻止脚本执行的nomodule属性,也明确告知浏览器当前引入的是ES模块文件,可以正常执行模块内的代码。
  2. 解决npm依赖的浏览器兼容问题,二选一即可:
    • 临时快速跑通方案:放弃当前npm导入的写法,把官方提供的Three.js单文件脚本放到本地js目录下,先在index.html里通过普通script标签引入这个本地Three.js文件,让全局作用域挂载THREE对象,再删掉main.js里的import * as THREE from 'three'语句,就可以和官方示例一样正常运行。
    • 正经开发方案:如果需要继续用npm安装的依赖,就需要搭配轻量的前端构建工具(比如Vite),由构建工具完成裸模块的路径映射、依赖预打包,把浏览器无法识别的裸导入转换成实际可访问的文件路径,这也是当前Three.js现代项目开发的标准流程。
  3. 修正main.js里的相机参数
    把原来写错位的相机初始化代码,替换为正确的参数格式:
    // 错误的写法:参数顺序错位
    // const camera = new THREE.PerspectiveCamera(75, window.innerWidth, window.innerHeight, 0.1, 1000);
    // 正确的写法:第二个参数必须是窗口宽高的比值
    const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
    

通用排查技巧

后续再遇到页面白屏问题,第一时间按F12打开浏览器开发者工具,切换到Console标签页,所有脚本加载失败、语法错误、运行时报错都会直接展示在这里,不需要逐行猜测问题根源。

内容的提问来源于stack exchange,提问作者paddy.exe

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.11.11 06:06:03