importmap实战：告别路径地狱，解锁浏览器原生模块解析

1. 内容整体设计与思路拆解

1.1 从“../../../”到importmap：解决的是心智负担，不只是路径问题

先问一个问题：你在项目里写过多少个../../../utils/format？如果有ES模块开发经验，大概率对这个字符串又爱又恨。爱的是它总能指向正确的文件，恨的是每次改动目录结构、移动组件、拆分包时，你得像个侦探一样数层级。更麻烦的是，代码审查时一眼扫过去，../../../../这种“路径长尾”几乎很难快速判断它到底指向谁。

我用原生importmap之前，项目里维护了一套“内部路径别名”方案，靠的是构建工具里的alias配置。这个方案本身没问题，但它有一个天然前提：你的代码必须经过打包器处理。一旦脱离打包——比如在纯静态页面、原型验证、零构建场景里直接写ES Module，或者用浏览器原生支持的模块功能调试一个独立组件——alias就完全不生效了，你只能老老实实写繁琐的相对路径或绝对路径，回到“数点点”的原始状态。

原生importmap核心价值就在于：它在浏览器层解决了“裸模块说明符（bare module specifier）”的解析问题。什么意思？就是你可以在浏览器里直接写import { fn } from 'my-utils'，不需要一个Node环境、不需要构建脚本，浏览器自己会根据页面上声明的映射关系去找到my-utils的真实位置。这相当于给原生模块系统加了一张路由表，一个纯前端的“路径服务器”。

我用了一段时间之后，最大的体会是：它带来的不只是“路径短了一点”这种表面便利，而是真正把模块引用从“目录结构依赖”中解放了出来。你引用的模块标识符从此有了“业务语义”，比如@shared/logger、ui/button，而不是../../../components/button。目录重构时，只要改映射表中的一行，所有引用无需变动。工程可维护性提升的幅度，绝对值回票价。

1.2 适用场景与方案选型：不是替代构建工具，而是补上原生模块的短板

简单说，importmap最适合下面几类场景：

• 纯静态HTML项目，不想引入任何构建工具，但模块数量多、引用关系复杂。
• 开发阶段用原生ES模块做“免构建热试”，生产再用完整打包。
• 微前端落地时的模块共享，尤其是依赖第三方库的版本统一管理。
• CDN直接投喂ES模块的场景，比如在页面里引用某种“浏览器模块分发”服务。
• 多年维护的老项目里，局部模块想跳出相对路径泥潭，但又不值得为“路径别名”单独造一套构建链路的场景。

有一点要特别说清楚：importmap不是要来干掉webpack、Vite这类打包器。它解决的是“模块怎么命名、怎么被解析”的问题，构建工具解决的是“模块怎么合并、怎么优化、怎么兼容”的问题。两者可以共存。像Vite这类构建工具，反而是原生importmap推广和普及的重要推手。我现在的做法就是：开发环境用原生importmap配合浏览器直接跑ES模块，调试爽快；上线前用打包工具做现代浏览器目标版本的产物，同时保留一份带importmap的静态版本作为降级方案，效果相当理想。

2. 核心细节解析与实操要点

2.1 importmap的基本语法与映射规则

想用importmap，只需在HTML文档的任何模块脚本之前，放入一个<script type="importmap">块。之所以强调“任何模块脚本之前”，是因为映射关系必须在模块加载前就绪。浏览器解析到这个标签时，会将其内部JSON解析为模块标识符映射表，后续遇到import语句时按表解析。

先看一个最简示例：

html复制<script type="importmap">
{
  "imports": {
    "lodash": "./vendor/lodash.js",
    "lodash/": "./vendor/lodash/",
    "dayjs": "./vendor/dayjs.js",
    "@shared/utils": "./src/shared/utils.js"
  }
}
</script>

<script type="module">
  import _ from 'lodash'
  import dayjs from 'dayjs'
  import { debounce } from '@shared/utils'
</script>

这里面有几个值得深入理解的规则。

第一是映射的“最长前缀匹配”原则。浏览器解析import 'lodash'时，先去imports里找精确的键lodash；解析import 'lodash/map'时，会先匹配到lodash/这个键，然后把剩下的map拼到映射值后面，得到./vendor/lodash/map。我把这个规则跟朋友打musquare比喻：像快递柜里的长条格子和短格子，包裹先找恰好合适的格子，找不到再看能不能放进某个宽格子并挤一挤。实际开发中，建议把公共前端库的“包根”和“子路径”分别映射，这样既能兼容深路径引用，又不会造成映射表过于庞大。

第二是映射值既可以是相对路径，也可以是完整URL。相对路径的基准是importmap脚本所在文档的URL，而不是当前模块文件的URL。这与普通import语句中“相对路径相对当前模块”的规则截然不同，是最容易踩的坑之一。如果页面位于https://example.com/app/index.html，映射里的"./vendor/lodash.js"会被解析为https://example.com/app/vendor/lodash.js，而不是https://example.com/app/pages/home/vendor/lodash.js。我一开始把importmap放在公共头部文件里，然后通过服务端模板插入不同层级的页面，结果吃了大亏：页面层级深时./vendor/...指向了错误目录。后来统一改成绝对路径或将映射放在固定根入口，问题才消失。

第三是键名中允许的字符。裸模块说明符不能以/、./或../开头，也不能以.js等明显扩展名结尾，否则无法成为合法的“裸标识符”。映射表里的值则不受限制。

2.2 模块作用域（scopes）：精细化控制的“命名空间映射”

大部分讲importmap的文章讲完imports就结束了，但对复杂项目而言，scopes才是真正体现“工程化思维”的设计。它的作用是对不同来源的模块应用不同的映射规则，相当于给映射表再挂一层“条件路由”。

举一个我实际遇到过的例子：项目里同时存在两个版本的依赖库——老模块用的是某个老版本的库，新功能块用的是另一个较新版本。我起初想全局把它映射到新版本，结果老模块直接报错。常见写法是在imports里全局映射到新版本，老模块则改源码适配，但那是很动荡的改法。更优雅的解法是用作用域：

json复制{
  "imports": {
    "@app/logger": "./src/logger.js"
  },
  "scopes": {
    "./src/legacy/": {
      "date-fns": "https://cdn.example.com/date-fns@2.29.3/esm/index.js"
    },
    "./src/new/": {
      "date-fns": "./node_modules/date-fns@3.x/esm/index.js"
    }
  }
}

这样，凡是从./src/legacy/下的模块发出的import 'date-fns'，都会使用老版本；从./src/new/下的模块发出的，则用新版本。我把这个比作“同一栋楼里不同楼层走不同的水表管道”。

scopes的值本身也是映射表，甚至还可以嵌套scopes（理论上允许但一般别用，维护成本太高）。作用域的匹配同样是最长前缀优先，而且优先级高于全局imports。如果某个作用域内找不到对应键，还会继续退回全局映射。这个机制在微前端子应用映射同一类库的不同版本、或者在多包仓库里按包定制依赖时，几乎可以当作“零成本依赖注入器”。

2.3 浏览器兼容性与动态importmap：只认支持它的现代浏览器

兼容性永远是前端技术落地躲不开的问题。好消息是，所有现代主流浏览器已经支持importmap；老版本浏览器则需要额外的polyfill。在写作本文时，我实测的结论是：最新版Chrome、Edge、Firefox、Safari均支持基本映射，但部分版本对“外部importmap（即通过src属性加载外部JSON）”“动态加映射后再次模块解析”等高级特性支持度不一。

这里强调一个经验做法：写<script type="importmap">时，不要给这个标签加src属性来加载外部JSON文件，因为早期的部分实现不支持，并且src会导致内联内容失效。如果想要把映射表独立成文件，目前更稳妥的方式是通过一个小脚本fetch后重新注入到页面中，但这只能在页面脚本加载前完成，时序要控制好。再加上这是原生特性，很多前端工具链并不会自动处理兼容降级，建议在部署页面中包含一段特性检测与回退逻辑。

动态importmap指的是在运行时通过document.querySelector('script[type="importmap"]').textContent = ...或调用某个polyfill库的接口来更新映射。但有一个天坑：模块解析是在模块加载时“固化”的。也就是说，如果一个<script type="module">已经执行过，或者一个模块已经被加载过，后面再去改importmap，不会影响已经解析完毕的模块。只有尚未加载的新模块才会使用新映射。因此，动态importmap只适用于“在所有模块执行前先行注入”的场景，不能当作运行时热重载来用。我踩过这个坑：想通过动态更新importmap切换微前端子应用版本，结果子应用模块首帧加载后，后续更新映射完全不生效，只能刷新页面。

2.4 与其他路径方案的对比

为了更直观说明，我把常见模块路径方案放在一张表里对照：

在我的实际感受里，importmap最显著的优势，是它把“路径策略”从构建期拉升到了运行期。这意味着，同一份映射JSON，可以被不同入口页面共用，也可以在CDN层做针对性的版本切换。比如同一套页面，给某个渠道用户下发映射表中analytics指向统计SDK的A版本，给另一渠道下发B版本，这种颗粒度的控制用构建工具做起来非常费劲，用importmap配合服务端模板却是一行JSON的事。

3. 实操过程与核心环节实现

3.1 一个免构建的前端小工具站：从相对路径到importmap的完整迁移

为了把这套东西讲透，我用一个实际的模拟项目X来说明——一个纯静态的图片批处理小工具站，页面里包含几个工具模块：image-utils.js负责缩放、剪裁等基础操作，color-picker.js负责取色，log.js负责日志，另有若干工具函数和第三方依赖库。项目目录结构如下：

text复制project/
├─ index.html
├─ pages/
│  ├─ index/
│  │  ├─ main.js
│  │  └─ tool-a.js
│  └─ advanced/
│     ├─ main.js
│     └─ tool-b.js
├─ src/
│  ├─ utils/
│  │  ├─ image-utils.js
│  │  ├─ color-picker.js
│  │  └─ log.js
├─ vendor/
│  ├─ lodash.js
│  └─ dayjs.js

迁移前的入口模块长这样：

javascript复制// pages/advanced/main.js
import { scaleImage } from '../../src/utils/image-utils.js'
import { getColor } from '../../src/utils/color-picker.js'
import { log } from '../../src/utils/log.js'
import _ from '../../vendor/lodash.js'
import dayjs from '../../vendor/dayjs.js'

注意：pages/advanced下的模块引用 ../../src/utils，而如果 pages/advanced/tool-b.js 里再加一层，就会变成../../../src/utils。这份代码一旦某个文件嵌套更深，错误率直线上升。而且每当我调整目录层级时，所有 import 都“哗啦”全片反红。

迁移后，index.html中引入importmap：

html复制<script type="importmap">
{
  "imports": {
    "lodash": "../vendor/lodash.js",
    "lodash/": "../vendor/lodash/",
    "dayjs": "../vendor/dayjs.js",
    "@utils/image-utils": "../src/utils/image-utils.js",
    "@utils/color-picker": "../src/utils/color-picker.js",
    "@utils/log": "../src/utils/log.js"
  }
}
</script>

看到这里，你可能发现我把vendor和src都映射成了以../开头的相对地址。这是因为这个站点里index.html位于项目根目录，而它在实际部署时的虚拟路径恰好与项目根的相对关系一致。简单说：importmap里的相对路径基准是HTML文档。index.html在根目录，那么"../vendor/lodash.js"相对根目录指向的其实是/vendor/lodash.js？这里例子中假设站点部署后访问根路径是/，index.html在根路径下，那么../vendor会指到上一级，这不合理。

让我把这个例子改得更合理：假设页面URL是https://example.com/tools/index.html，那么"../vendor/lodash.js"会解析为https://example.com/vendor/lodash.js。项目目录里index.html放tools/子目录，vendor放tools/../vendor？不如直接使用绝对根路径映射：

json复制{
  "imports": {
    "lodash": "/assets/vendor/lodash.js",
    "dayjs": "/assets/vendor/dayjs.js",
    "@utils/image-utils": "/assets/src/utils/image-utils.js"
  }
}

另一种做法是全部使用相对./并保持页面与资源同层。这里我建议用绝对路径，原因在于它不依赖HTML所在层级，逻辑更明确。除非你的站点部署在文档根目录下的某个未知子路径，才需要动态拼接base URL来生成映射。

继续，改造后的入口模块代码变成：

javascript复制// pages/advanced/main.js
import { scaleImage } from '@utils/image-utils'
import { getColor } from '@utils/color-picker'
import { log } from '@utils/log'
import _ from 'lodash'
import dayjs from 'dayjs'

是不是清爽得惊艳？每个import都自带语义，一眼看出它引用的是“工具”还是“库”。更重要的是，如果下次要把image-utils.js从src/utils移到src/image/tools，只需修改importmap中那一行，不需要动main.js和其它几十处引用。

3.2 核心步骤拆解：如何在已有项目中分步启用importmap

有人会担心一上来全量改造风险大。我个人推荐分三步走：

第一步，把第三方依赖统一收拢。将import _ from '../vendor/lodash.js'这类写法改为import _ from 'lodash'，并在页面顶部加一个最简importmap。这一步不用动业务模块的路径，只处理第三方库。好处是，你的映射表先建立起来，同时验证浏览器对importmap的支持情况。如果有的浏览器不支持，此时影响面很小，容易回退。

第二步，为业务模块建立映射。我会把高频公共模块和相对路径在3层以上的模块优先列入映射。比如把src/utils下的核心函数全部用@utils/xxx别名替代。此时保留一部分尚不复杂的相对路径引用也没关系。这样既降低首轮改造成本，又能快速看到收益。

第三步，当映射表逐渐稳定后，再把全部业务模块的跨包引用切换到别名，并删掉多余的相对路径。此时可以结合引入scopes处理版本冲突。同时我还会建立一个“路径命名规范”文档：哪些前缀留给公共库，哪些前缀留给业务模块，尔后在代码评审时统一检查。

3.3 微前端场景下的importmap共享库配置

微前端是我觉得最值得谈的应用场景。多个子应用如果各自打包一份庞大的公共库，性能与存储都难以接受。用importmap在运行时把公共依赖“全局注入”，让子应用去消费，是一个相当自然的方案。

我见过一种实用的配置方式：基座应用页面里维护一份公共映射表，子应用模块则通过scopes按需覆盖。例如：

json复制{
  "imports": {
    "@shared/event-bus": "/assets/shared/event-bus.js",
    "react": "/assets/shared/react.js",
    "react-dom": "/assets/shared/react-dom.js"
  },
  "scopes": {
    "/apps/app-a/": {
      "react-dom": "/assets/shared/react-dom-v17.js"
    },
    "/apps/app-b/": {
      "react-dom": "/assets/shared/react-dom-v18.js"
    }
  }
}

这样app-a和app-b可以共存于同一页面，各自使用不同版本的react-dom而互不干扰。要注意的是，各子应用构建时，externals（或称“外部化”）必须设置为使用全局这些包名，而不是把库打包进产物。否则子应用自己又包一份副本，importmap就形同虚设了。

我记得自己第一次尝试这种方案时，一直困惑为什么子应用加载后还是“Duplicate React”的警告。排查后才发现，子应用的构建配置里没把react标记为外部依赖，导致打包器把React复制了一份。调整构建配置后，子应用真正共享了基座的React实例，整个页面内存占用明显下降。这一实践体验让我彻底认可了importmap在微前端里的价值。

3.4 与CDN库结合：浏览器直接消费ES Module CDN内容

ES模块的第三方库可以直接通过CDN的URL引用。配合importmap，可以写：

html复制<script type="importmap">
{
  "imports": {
    "lodash-es": "https://cdn.example.com/lodash-es@4.17.21/+esm",
    "dayjs": "https://cdn.example.com/dayjs@1.11.10/esm/index.js"
  }
}
</script>

这时的映射值是一个完整的URL，浏览器会像请求普通模块一样，带着CORS去CDN加载。有一点必须提醒：CDN上必须正确返回Access-Control-Allow-Origin响应头，否则模块会被CORS拦截。很多CDN支持?module或/+esm这样的特殊入口，实际实践时需先验证。

另外，使用CDN作为依赖源时，版本锁定非常重要。请把确切版本号写进URL，因为latest或“最新版”的链接很可能在你下次上线时解析到不同代码，从而带来不可控的回归。我见过某个团队在importmap里写https://cdn.example.com/lib/latest/index.js，结果某天该库发布新版本破坏了API，页面瞬间全灰。锁定版本号，并将解析后的具体URL记录到仓库里，才能真正可复现。

4. 常见问题与排查技巧实录

4.1 importmap未生效或模块加载404

最典型的症状是浏览器控制台报出类似 Failed to resolve module specifier "utils/foo" 或 Failed to fetch，同时网络面板中请求的URL显然不对。

排查步骤一般如下：

1. 确认<script type="importmap">在页面中处于其他任何模块脚本之前。如果某个<script type="module">先执行，importmap就来不及参与了。
2. 检查JSON合法性。importmap内部必须是合法JSON，不能带注释，不能尾逗号。很多编辑器里添加注释后直接导致解析失败，整个映射静默失效。
3. 确认映射键不能有引号空格等问题。"lodash"和"lodash/"是两个键，如果大小写或斜杠不一致，可能匹配失败。
4. 查看Network面板里实际请求的完整URL。通过比对请求URL与期望URL，判断是映射值写错还是相对路径基准算错。

我记得有个案例：线上页面所有模块加载失败，排查后发现问题不在importmap，而是页面里有个try/catch包裹的代码把整个页面渲染阻断，导致模块脚本根本没执行。所以遇到诡异问题时，也别忘了先看页面HTML是否真的输出完整。

4.2 相对路径基准偏差

这个坑很多人会反复踩。importmap中的相对路径是基于文档地址的，而模块内部的相对路径是基于模块文件本身的。如果两者混用且没搞清基准，就会出现“深页面下映射找不到文件”的怪象。

我给出的实操建议：如果站点部署路径固定，优先使用以/开头的绝对路径，比如/assets/vendor/dayjs.js，这样无需考虑页面层级；如果部署环境支持从import.meta.url动态推导base，也可以在注入importmap前，用一个小脚本把${import.meta.url}里的公共前缀算出来并拼入映射值。虽然麻烦，但很可靠。

4.3 CORS、MIME类型与模块安全

原生ES模块受CORS策略限制，跨域模块加载必须通过access-control检查。同时，模块脚本的MIME类型必须正确。很多原本用于普通<script>的JS文件在作为模块加载时报错，问题就在于服务端返回的Content-Type不是JavaScript类型。使用importmap映射时尤其如此，因为映射值往往指向一个“非同源资源”。

排查技巧：打开DevTools的Network，查看模块响应的Content-Type头。若不正确，需要调整静态服务器配置。开发本地测试时，不要用file://协议打开带ES模块的页面，否则模块加载会因跨源限制失败。用npx serve或Vite的开发服务器来启动本地站点即可。

4.4 动态更新不生效

前面提过，模块加载后映射就固定了。如果尝试通过fetch外部JSON再替换importmap内容，会导致新模块可能用新映射、旧模块用旧映射，产生难以追查的不一致。要避免在应用运行时去改映射。若确实需要“按版本切换依赖”，应该以页面加载时“一次性决定”的方式，在第一个模块执行前把映射注入完整。或者干脆采用不同的入口HTML，比如index.html?v=1和index.html?v=2分别输出不同的importmap。

另外有一种做法是把importmap放在服务端渲染的占位脚本中，每次请求动态生成。这很好，但要注意强缓存：HTML文档本身应避免被CDN强缓存太久，否则动态映射更新也会失效。

4.5 与打包器协同时的坑

如果你的项目使用Vite、Rollup等工具，有时构建产物里仍保留了importmap中定义的“bare模块引用”，但打包器并不认识这些外部标识符。这时如果构建配置里没有将其标记为“external”，构建就会失败。反之，如果标记了external，构建后产物里就会保留import from 'lodash'，于是运行时就必须依赖页面上的importmap或真实可用模块。要避免出现“构建成功、运行时却找不到模块”的尴尬，需要在构建配置与页面映射表之间建立一份约定文档，列明哪些裸模块标识符是运行期提供的。

我习惯将这样一份清单放到项目根目录的importmap.external.json里，构建脚本读取它生成rollupOptions.external，页面再通过模板动态把同一份映射渲染为<script type="importmap">。一套数据两处使用，从源头避免不一致。

4.6 常见问题速查表

5. 进阶实践与心得点评

5.1 命名规范：映射表的可维护性来自命名

importmap很容易把路径写成一团“药方”，一段时间后连自己都看不懂。我给团队定过一套规则，这里也分享出来：

• 第三方库使用实际包名（如lodash、dayjs），不做语义化改名。
• 业务模块使用带命名空间的前缀，比如@utils/、@components/、@services/。
• 每个前缀对应一个明确的源目录，不要一个前缀混用多个目录。
• 映射表的键值排序按照“前缀从短到长”，便于人工审查。
• 一个映射值尽量只指向单文件；如果需要目录映射，则额外在目录级映射一条处理子路径。

这套规范让importmap文件本身成了一等公民。它不仅是技术配置，更是项目模块架构的“契约文档”。新人接手时，看一眼importmap，就能快速理解整个系统的模块分布。

5.2 版本管理：把importmap纳入版本仓库的“差量审计”

与package.json不同，importmap”天然指示了运行时的实际依赖版本。我建议把映射表单独抽成一个JSON文件，然后在构建或部署时由模板引擎注入HTML。这样，代码评审时可以清晰看到依赖更新的diff。

同时，尽量在CI流程里增加一个校验脚本：读取importmap JSON，检查所有映射值对应的URL是否可访问、是否指向存在的文件。虽然在浏览器中发现问题也能修，但通过自动化在合并前就把无效映射拦下来，能省去很多线上事故。这个脚本不复杂，几十行Node代码足够，性价比极高。

5.3 性能考量与加载优化

你可能关心importmap会不会影响模块加载性能。结论是：影响很小，但要注意不要滥用映射。浏览器在每次模块解析时都要根据映射表做字符串匹配，映射表条目越多匹配耗时越长，但这个开销远小于网络请求。然而，如果映射表写得过于庞杂，反而会造成维护困难。性能上我更关注的是被映射的模块文件本身——如果映射指向的CDN文件体积过大，尽量用精确入口（如lodash-es/map.js而非整包），从而减少加载体积。

还有一点：importmap本身因为变化的频率低于业务代码，应该让浏览器或CDN对它做强缓存。如果用内联方式，它会随HTML一起下发，此时HTML的缓存策略就很关键。如果映射内容大且基本不变，可以独立成一个外部JS文件通过脚本插入，但又要处理时序。权衡之下，我个人更倾向于内联，并配合较短的HTML缓存时长；如映射表稳定且巨大，再考虑独立加载。

5.4 与现有工具链的融合建议

很多前端开发者以为importmap会逼迫他们放弃构建流程。其实不然，相反，它是一个很好的“运行时补充层”。我的建议是“构建期管代码，运行期管依赖”：

• 构建期：压缩、转译、Tree Shaking、代码拆分，这些是打包器的强项，继续用它做。
• 运行期：依赖版本控制、微前端模块共享、子系统间依赖隔离，交给importmap处理。
• 开发期：直接用原生ES模块配合importmap做零构建原型，速度极快，省掉启动构建服务器的等待；等原型稳定再迁入正式构建流程。

如果你使用的是Vite，它还提供了“模块地图开发插件”类的支持，本质上就是利用importmap原理实现开发环境的依赖预构建。理解原生的实现后，会对这些工具的内部设计有更清晰的认知，排查问题也会更从容。

6. 一个从零到一的项目实例：用原生importmap重构静态工具页

6.1 项目背景与改造目标

我最近维护的模拟项目X是一个内部用的前端调试工具集合页，最初是零散的HTML文件，每个页面直接引用了大量相对路径脚本。随着页面增多，路径层级开始失衡：某个页面脚本位于pages/deploy/tools/legacy/index.js，引用公共工具时要写../../../../src/utils/token.js。这种代码别说别人，我隔两周自己都算不清楚。

改造目标很明确：

1. 所有跨目录的模块引用一律改为“语义化裸模块名”。
2. 不引入新构建工具，保持纯静态部署。
3. 第三方库和业务工具全部通过importmap统一管理。
4. 支持多个子页面通过同一套映射加载模块。

6.2 具体实现过程

首先创建importmap.json文件：

json复制{
  "imports": {
    "lit-html": "https://cdn.example.com/lit-html@2.8.0/lit-html.js",
    "lit-html/": "https://cdn.example.com/lit-html@2.8.0/",
    "@app/api": "./assets/js/api/index.js",
    "@app/utils/": "./assets/js/utils/",
    "@app/components/": "./assets/js/components/"
  },
  "scopes": {
    "./assets/js/utils/legacy/": {
      "@app/legacy-helper": "./assets/js/legacy/helper.js"
    }
  }
}

页面HTML结构类似：

html复制<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>调试工具集</title>
  <script type="importmap">
  {
    "imports": {
      "lit-html": "https://cdn.example.com/lit-html@2.8.0/lit-html.js",
      "lit-html/": "https://cdn.example.com/lit-html@2.8.0/",
      "@app/api": "./assets/js/api/index.js",
      "@app/utils/": "./assets/js/utils/",
      "@app/components/": "./assets/js/components/"
    },
    "scopes": {
      "./assets/js/utils/legacy/": {
        "@app/legacy-helper": "./assets/js/legacy/helper.js"
      }
    }
  }
  </script>
</head>
<body>
  <script type="module" src="./assets/js/pages/legacy-tools/main.js"></script>
</body>
</html>

原先legacy-tools/main.js里的路径引用：

javascript复制import { legacyCompute } from '../../../utils/legacy/legacy-helper.js'
import { getToken } from '../../../../src/utils/token.js'
import { createComponent } from '../../../components/table.js'

改造为：

javascript复制import { legacyCompute } from '@app/legacy-helper'
import { getToken } from '@app/utils/token.js'
import { createComponent } from '@app/components/table.js'

注意@app/utils/映射加了斜杠，所以引用token.js时写成@app/utils/token.js；而@app/components/table.js也可以写成@app/components/table.js，同样命中目录级映射。这份映射规则让我们既能整体处理目录，也能精确指定文件，非常灵活。

6.3 改造后效果与实测结论

改造完成后的页面在本地静态服务器下直接运行，浏览器加载一切正常。模块请求数量与改造前一致，但所有请求URL清晰可读。更直观的是，当我把assets/js/utils/目录迁移到assets/js/core/utils/后，只更新importmap里两行映射，所有页面模块引用自动跟随，无需再逐个调整源文件。这个体验比以往任何一个构建工具的alias方案都更干脆，因为它是浏览器原生行为，连“安装插件”这一步都省了。

使用Network面板观察，浏览器按预期平行加载模块，没有多余的请求。搭配HTTP/2后，多模块加载性能完全可以接受。如果将来模块数特别多，再用打包器做合并也不迟——反正映射表和源码改动分开，切换成本很低。

7. 写在最后的几点体会

前前后后把importmap应用到几个项目中后，我最深的感受不是“路径变短了”，而是“心智负担大幅下降”。以前写import时，脑子里要先过一遍目录树，心里默数“这是第几层？”；现在只要想“这个模块是什么、属于哪类”，引用就出来了。这跟重命名变量、提炼函数带来的认知卸载是同一类收益。

另外一个体会是：原生技术的接受度，取决于你有多愿意把它嵌入到现有工作流里。importmap不是银弹，它不能替代代码分割和兼容处理，但只要用对地方，尤其是纯ES模块环境、微前端公共依赖管理、免构建原型验证这三类场景，它确实称得上“优雅革命”。

如果你正被一长串../../../困扰，不妨花半天时间把其中一个页面改成importmap试试。我敢说，当你删掉最后那个../时，所产生的爽快感，比装任何新框架都来得真实。