原生HTML引入Three.js OrbitControls报模块解析错误如何解决

你看到的报错核心原因是原生浏览器的ES模块规范不支持裸模块标识符解析：

Uncaught TypeError: Failed to resolve module specifier "three". Relative references must start with either "/", "./", or "../".

OrbitControls.js源码内部默认写了import * as THREE from 'three'，这里的'three'就是裸标识符，浏览器无法识别它对应的资源地址，只有完整URL、以//.//../开头的路径才能被原生模块解析。
你的原有代码还存在几个明确问题：

• 导入本地OrbitControls.js时未加相对路径前缀./，直接写from 'OrbitControls.js'同样会被识别为裸模块，无法解析
• 之前尝试的unpkg路径带/browse/字段，返回的是HTML预览页而非JS源码，无法作为模块导入
• 重复引入OrbitControls：既通过script标签单独引入本地文件，又在模块脚本中重复import，产生逻辑冲突
• 模块脚本闭合标签书写错误，写成了</src>，正确写法为</script>
• 同时引入了非模块版和模块版dat.gui，产生冲突

方案1：CDN引入（无需本地存放three相关文件，配置最简单） #

所有three生态依赖使用同版本的CDN模块地址，不要混用版本，不要带页面预览路径，参考代码：

<script type="module">
  // 核心库和插件版本保持一致，均使用0.141.0
  import * as THREE from 'https://unpkg.com/three@0.141.0/build/three.module.js';
  import { OrbitControls } from 'https://unpkg.com/three@0.141.0/examples/jsm/controls/OrbitControls.js';
  import * as dat from 'https://unpkg.com/dat.gui@0.7.9/build/dat.gui.module.js';

  // 下方直接编写业务逻辑即可
  console.log(THREE, OrbitControls, dat);
  // 初始化示例
  // const scene = new THREE.Scene()
  // const camera = new THREE.PerspectiveCamera(75, window.innerWidth/window.innerHeight, 0.1, 1000)
  // const renderer = new THREE.WebGLRenderer()
  // renderer.setSize(window.innerWidth, window.innerHeight)
  // document.body.appendChild(renderer.domElement)
  // const controls = new OrbitControls(camera, renderer.domElement)
</script>

注意：OrbitControls这类three官方插件必须和three核心库版本完全一致，否则会出现API不兼容问题

方案2：本地文件引入 #

如果需要把所有资源存到本地，按以下规则调整：

1. 打开本地OrbitControls.js源码，将内部的from 'three'修改为本地three.module.js的相对路径，若两个文件在同一目录，改为from './three.module.js'即可
2. 所有本地模块导入时必须加./前缀，不要直接写文件名
3. 移除单独引入OrbitControls的script标签，模块文件统一通过import导入即可
   参考代码：

<script type="module">
  // 本地文件必须加./相对路径前缀
  import * as THREE from './three.module.js';
  import { OrbitControls } from './OrbitControls.js';
  import * as dat from './dat.gui.module.js';

  // 下方编写业务逻辑
</script>

• 不要使用GitHub raw地址、资源站预览页地址作为模块导入地址，这类地址返回的MIME类型不符合JS模块要求，浏览器会拒绝执行
• 所有ES模块代码必须放在添加了type="module"属性的script标签内，不要和普通非模块脚本混用
• 本地调试时不要直接双击HTML文件通过file://协议打开，会触发跨域限制，建议使用本地静态服务（如VSCode的Live Server插件、Python内置http服务）启动后访问

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