HTML引入JS模块路径报错：使用Import Map解决three和gsap加载问题

前言

本文探讨在JS代码抽离并引入three模块时遇到的路径问题。

使用LiveServer运行项目时，控制台报错如下：

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

这已是多次遇到此类问题的经历之一。在编写HTML文档案例并尝试引入各类库时，常因包路径问题导致引入失败。此次问题解决过程令人印象深刻，同时也带来了不少技术收获。

一、错误复现情况

1. three模块引入失败

HTML文件结构如下：

<script src="./js/main.js" type="module"></script>

JavaScript代码尝试直接引入：

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

2. gsap模块引入失败

未在HTML文档中直接操作，而是直接在JS文件中通过npm安装并引入：

import gsap from 'gsap';

最终结果是两个模块均未能成功引入。

二、解决办法

路径本身并未写错，问题在于打包或本地服务器环境下，浏览器无法正确解析模块路径，导致找不到对应模块。

当导入JavaScript模块时，import语句和import()运算符都包含一个“模块标识符”，用于指示要导入的具体模块。浏览器需要根据此标识符解析出绝对路径，才能成功执行导入操作。

导入映射（import map）是一个JSON对象，允许开发者在导入JavaScript模块时，控制浏览器如何解析模块标识符。它提供了在import语句或import()运算符中用作模块标识符的文本，建立标识符与替换文本之间的映射关系。

在HTML文件中增加以下代码，协助浏览器正确解析模块标识符。这段配置代码可在three.js源码的example任意案例中找到。第一个映射修正three模块的路径，第二个映射修正OrbitControls等附加模块的路径。

<script type="importmap">
  {
    "imports": {
      "three": "../../node_modules/three/build/three.module.js",
      "three/addons/": "../../node_modules/three/examples/jsm/"
    }
  }
</script>

three的引入问题核心在于路径错误，LiveServer最终需要定位到three.module.js。对于three的其他附加模块，若需找到jsm目录下的文件，且OrbitControls等模块不在three.module.js内部时，可以不配置importmap内的three/addons/路径，而是直接指定具体文件：

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

实际上，这种做法是将importmap中的映射内容直接写入了JS文件中。

但对于three.module.js这种一次性导出多个类的文件，必须通过importmap进行配置才能正确引入。

gsap引入失败的原因在于HTML文档中不能直接以简单字符串形式引用：

import gsap from 'gsap';

正确的引入方式应如下所示。

需要先配置importmap：

<script type="importmap">
  {
    "imports": {
      "gsap": "../../node_modules/gsap/index.js"
    }
  }
</script>

然后在JS文件中：

import { gsap } from 'gsap';

路径无需固定，只要引导至index.js即可。

或者不配置importmap，直接在JS文件中编写：

import { gsap } from '../../node_modules/gsap/index.js';

总结

到此这篇关于HTML文档引入JS模块出现路径问题解决办法的文章就介绍到这了,更多相关HTML引入JS模块路径问题内容请搜索本站以前的文章或继续浏览下面的相关文章希望大家以后多多支持本站！