importmap是w3c标准的模块路径映射机制,必须用type="importmap"(非application/importmap),写错大小写、短横线或漏引号均静默失效;须置于head内所有type="module"脚本之前,映射目标须为合法es模块且响应头为application/javascript。

importmap 是什么,为什么不能直接写 type="importmap"
HTML 的 <script></script> 标签不支持 type="importmap" —— 这个值根本不是合法的 MIME 类型,浏览器会忽略它,甚至在严格模式下报错 Failed to execute 'import' on 'WorkerGlobalScope': The script has unsupported type 'importmap'。真正用于声明 import map 的是 type="importmap" 的 错误认知,实际必须用 type="application/importmap",且仅允许出现在 <script></script> 标签中(不能是外部文件),且必须在任何 import 语句执行前加载。
正确写法:用 type="application/importmap" 声明映射
import map 必须是内联 JSON,且 <script></script> 标签要放在所有依赖模块的 import 之前(通常紧贴 底部):
<script type="application/importmap">
{
"imports": {
"lodash": "https://cdn.jsdelivr.net/npm/lodash@4.17.21/+esm",
"utils": "./src/utils.js"
}
}</script><script type="module">
import _ from 'lodash';
import { helper } from 'utils';
</script>
-
type必须严格为"application/importmap",大小写敏感,拼错或加空格都会失效 - JSON 内容不能有注释、尾逗号,也不能是变量或动态生成(服务端渲染除外)
- 映射目标路径必须是完整 URL 或相对路径(从当前 HTML 所在位置解析),不能是 bare specifier 本身
- 如果用
import加载了模块,但 import map 尚未解析完成,会直接报Failed to resolve module specifier
常见错误:CDN 路径没带 +esm 或用了非 ES 模块
很多 CDN(如 jsDelivr、unpkg)默认返回 CommonJS 版本,而 type="module" 只能加载 ES 模块。例如:https://cdn.jsdelivr.net/npm/lodash@4.17.21 返回的是 CJS,浏览器会报 TypeError: Cannot assign to read only property 'exports' of object。
- jsDelivr:在 URL 后加
/+esm(如https://cdn.jsdelivr.net/npm/lodash@4.17.21/+esm) - unpkg:加
?module(如https://unpkg.com/lodash@4.17.21?module) - Skypack:直接用
https://cdn.skypack.dev/lodash@4.17.21(自动转 ES 模块) - 本地路径如
./src/utils.js必须确保文件导出是export语法,且服务器支持.js的Content-Type: text/javascript
importmap 不支持嵌套或动态更新,上线前得验证路径有效性
import map 是静态声明,浏览器不会重新 fetch 或重解析它;修改后必须刷新页面,且不支持 importmap 中引用另一个 import map(无递归)。生产环境容易踩的坑:
- 路径写错(比如少个
./或多一层../),错误不报具体行号,只显示Failed to resolve... - HTTP 服务器没配 MIME 类型,导致
.js返回text/plain,触发 CORS 或解析失败 - 开发时用 Live Server 插件,但它的根路径和真实部署路径不一致,本地能跑,上线 404
- 没有 fallback 机制——一旦某个映射 URL 404 或跨域失败,整个模块图就断了,无法像打包工具那样降级或提示
真正要用好 importmap,得把路径当成硬编码来测,而不是当作配置项随便改。
前端入门到VUE实战笔记:立即使用
在学习笔记中,你将探索 前端 的入门与实战技巧!











