HTML Academy · 课时

导入映射：importmap

使用 importmap 将裸模块说明符映射到 URL

导入映射：importmap 是 CoddyKit 上的免费 HTML Academy 课时。这是第 2 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 HTML Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 HTML Academy 课程共包含 4 节课。

裸说明符问题

在 Node 中，import "lodash" 可以正常工作，因为解析器能够找到 node_modules/lodash。浏览器没有 node_modules，因此需要真实网址。没有额外帮助时，import "lodash" 会抛出“无法解析模块说明符”错误。

导入映射表的作用

导入映射表声明一个 JSON 字典，将裸说明符（以及网址前缀）映射到真实网址。浏览器会在模块解析时查询该映射表，把 import "lodash" 转换为从您配置的网址获取模块。

<script type="importmap">
{
  "imports": {
    "lodash": "https://esm.sh/lodash@4.17.21",
    "preact": "https://esm.sh/preact"
  }
}
</script>

声明顺序很重要

导入映射表必须出现在任何使用裸说明符的 <script type="module"> 之前——一旦模块开始解析导入内容，映射表就会被锁定。请将 <script type="importmap"> 放在 <head> 的靠前位置。

前缀映射

以斜杠结尾的条目会匹配网址前缀："@/": "/src/" 会将任何 import "@/utils/sum.js" 映射到 /src/utils/sum.js。这就是模拟打包工具通常支持的“别名”语法的方式。

通过映射表进行版本管理

导入映射表可以集中管理版本选择：只需在一个位置将 "react" 从 esm.sh/react@18 改为 esm.sh/react@19，所有导入该模块的模块都会使用新网址。没有导入映射表时，每个导入位置都会将自己的版本硬编码其中。

作用域

scopes 键允许您为网站的不同部分设置不同的映射。在 /admin/ 内，您可能希望使用比 /public/ 中更新的依赖项版本；作用域可以让您按路径指定映射。

{
  "imports": { "lodash": "https://esm.sh/lodash@4" },
  "scopes": {
    "/admin/": { "lodash": "https://esm.sh/lodash@5" }
  }
}

每个文档一个映射表

每个文档最多只能有一个 <script type="importmap">。在同一个页面中放置两个映射表是无效的；请将它们的内容合并到同一个代码块中，以组合所有条目。

外部导入映射表

您可以通过 <script type="importmap" src="map.json"> 将映射表托管在外部网址上。浏览器对它的支持晚于内联映射表，但现在已经相当普遍；当您希望将大型映射表与文档分开缓存时，这种方式很有用。

生成导入映射表

JSPM Generator 和 esbuild 的 --servedir 模式等工具可以根据 package.json 自动生成导入映射表。生成的映射表包含所有传递依赖，并将每个依赖映射到 CDN 网址，从而实现不依赖 node_modules 的工作流。

浏览器支持

Chrome、Edge、Safari 和 Firefox 都已支持导入映射表。较旧的浏览器会忽略 <script type="importmap"> 标签，这意味着裸说明符会失败。若要广泛支持旧版浏览器，请使用能在构建时解析说明符的打包工具进行构建，并提供普通网址。

填充方案

ES Module Shims 填充程序（es-module-shims.js）可以为较旧的浏览器添加导入映射表支持以及其他一些较新的功能。请将它放在导入映射表脚本之前。大多数现代项目会跳过填充程序，依赖原生支持。

知识检查

为什么 <script type="importmap"> 必须出现在任何使用裸说明符的模块脚本之前？

摘要

导入映射表会将裸说明符和网址前缀映射到真实网址，从而让浏览器恢复类似 Node 的“import lodash”用法。请在每个文档中只声明一次，并放在所有模块脚本之前；也可以通过 src 从外部加载，并使用作用域进行按路径覆盖。结合 CDN（esm.sh、jsdelivr）即可实现不依赖 node_modules 的工作流。

常见问题解答

「导入映射：importmap」课时是免费的吗？

是的 — 「导入映射：importmap」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 HTML Academy 课程的其余内容，请升级到 CoddyKit PRO。 HTML Academy 课程共包含 4 节课。

「导入映射：importmap」这节课中我会学到什么？

使用 importmap 将裸模块说明符映射到 URL 你通过在浏览器中直接运行的动手代码来练习 HTML Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 HTML Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 HTML Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 2 节课，共 4 节。

「导入映射：importmap」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 HTML Academy 课中编写并运行代码吗？

能。每节 HTML Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 HTML Academy