NPM安装ThreeJS后导入OrbitControls遇模块解析错误求助

错误原因 #

OrbitControls 的源码内部使用了 import * as THREE from 'three' 这种裸模块导入语法，但浏览器原生 ES 模块不支持这种写法——浏览器要求模块引用必须以 /、./ 或 ../ 开头，因此触发解析错误。

解决方案 #

方法一：使用导入映射（Import Maps，浏览器原生支持） #

在 HTML 中添加导入映射规则，将裸模块名 three 映射到本地的 Three.js 核心文件路径，让浏览器能正确解析：

修改后的 HTML 代码：

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>My first three.js app</title>
    <style>
        body { margin: 0; }
    </style>
    <!-- 添加导入映射 -->
    <script type="importmap">
    {
        "imports": {
            "three": "../node_modules/three/build/three.module.js"
        }
    }
    </script>
</head>
<body>
<script src="main.js" type="module"></script>
</body>
</html>

对应的 main.js 代码（可简化导入，同时注意先定义 camera 和 renderer）：

import * as THREE from 'three';
import {OrbitControls} from '../node_modules/three/examples/jsm/controls/OrbitControls.js';

// 先初始化必要的 Three.js 对象
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);

// 再创建 OrbitControls
const controls = new OrbitControls(camera, renderer.domElement );

方法二：使用构建工具（推荐长期项目） #

用 Vite、Webpack 等构建工具处理裸模块导入，这类工具会自动解析模块依赖并打包：

1. 初始化 Vite 项目：

npm create vite@latest my-three-app -- --template vanilla

2. 进入项目目录并安装 Three.js：

cd my-three-app
npm install three

3. 修改 main.js：

import * as THREE from 'three';
import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';

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);

4. 启动开发服务：

npm run dev

方法三：修改 OrbitControls 源码（不推荐） #

找到 ../node_modules/three/examples/jsm/controls/OrbitControls.js，将开头的 import * as THREE from 'three' 改为相对路径：

import * as THREE from '../../../build/three.module.js';

缺点：npm 更新 Three.js 后，修改会被覆盖，需重复操作。

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