Three.js OBJLoader初始化报错：裸模块说明符未映射问题

错误根源 #

浏览器原生ES模块不支持'three'这种裸模块标识符，而Three.js的示例JS模块（如OBJLoader.js、OrbitControls.js）内部均使用import * as THREE from 'three'这类裸路径导入核心库，因此需要通过Import Maps建立映射规则，让浏览器识别'three'对应的实际文件URL。

解决方案 #

1. 在HTML中配置Import Map #

在HTML的<head>标签内插入以下代码，定义模块映射关系：

<script type="importmap">
{
  "imports": {
    "three": "https://10.1.10.101/work-shop/three.js/build/three.module.js",
    "three/addons/": "https://10.1.10.101/work-shop/three.js/examples/jsm/"
  }
}
</script>

该配置实现：

• 将裸标识符three映射到你的核心Three.js模块URL
• 将three/addons/前缀映射到示例JS模块根目录，简化后续插件导入路径

2. 修正JS文件的导入语句 #

把原绝对URL导入改为裸标识符导入，匹配上述映射规则：

import * as THREE from 'three';
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
import { OBJLoader } from 'three/addons/loaders/OBJLoader.js';

3. 修复代码中的语法错误 #

你的JS代码存在两处拼写错误，必须修正才能正常运行：

• THREE.scene() → 改为THREE.Scene()（构造函数首字母需大写）
• oxffffff → 改为0xffffff（十六进制颜色前缀为数字0，而非字母o）

修正后的完整JS代码：

import * as THREE from 'three';
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
import { OBJLoader } from 'three/addons/loaders/OBJLoader.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 light = new THREE.AmbientLight(0xffffff, 1);
scene.add(light);

// 添加轨道控制器，方便交互查看模型
const controls = new OrbitControls(camera, renderer.domElement);
camera.position.z = 5; // 调整相机初始位置，确保能看到模型

const loader = new OBJLoader();
loader.load(
    'https://10.1.10.101/work-shop/base_assets/obj/Human/Characters/footman.obj',
    function( object ) {
        scene.add(object);
    },
    function( xhr ) {
        console.log(`${(xhr.loaded/xhr.total*100).toFixed(2)}% loaded.`);
    },
    function( error ) {
        console.error("模型加载出错", error);
    }
);

function animate() {
    requestAnimationFrame(animate);
    controls.update(); // 更新控制器状态
    renderer.render(scene, camera);
};
animate(); // 启动渲染循环

4. 环境验证要点 #

• 确保服务器支持application/importmap+json MIME类型（现代服务器默认支持，若不生效需手动配置）
• 使用支持Import Maps的现代浏览器（Chrome 89+、Firefox 108+、Safari 16.4+）

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