Import Maps 统一浏览器端依赖别名

当浏览器端项目从几个模块扩展到多目录、多版本依赖时，import "../../shared/utils.js" 这类路径很快会变成维护负担。Import Maps 的作用不是替代打包器，而是在浏览器解析模块说明符时提供一层稳定的别名：业务代码写 import { formatDate } from "@app/date"，部署路径变化时只调整映射表。

先确认 Import Maps 解决的边界

浏览器原生模块默认能解析相对 URL、绝对 URL和完整 URL，不能像 Node.js 那样凭空知道一个裸名称对应哪个文件。Import Map 把模块说明符映射成可解析的 URL，覆盖静态 import 和动态 import()。它只参与文档中模块的解析，不会改写 HTML 里 的入口地址，也不负责 Worker 或 Worklet 的模块环境。

因此，适合迁移的是模块之间的依赖别名，而不是把整套构建、压缩和代码分割都交给浏览器。先把目标限定为“统一引用方式”，后续再决定是否继续使用 Vite、Rollup 或其他构建链。

用 imports 建立单模块与目录别名

单文件别名适合稳定指向一个入口；目录别名适合一组模块。目录键和值必须同时以 / 结尾，否则浏览器只会做整串说明符匹配。

有了这张表，main.js 可以写：

// 中文注释：使用稳定别名，避免业务文件感知哈希文件名和目录层级
import { formatDate } from "@app/date";
import { createCard } from "@app/widgets/card.js";

// 中文注释：模块导出缺失或路径映射错误时，让错误尽早暴露在模块加载阶段
const card = createCard(formatDate(new Date()));
document.querySelector("#app").append(card);

这里的 @app/date 是完整键匹配，@app/widgets/ 则把后面的 card.js 拼到目标目录。不要只写键的斜杠而忘记值的斜杠；也不要把右侧写成另一个裸名称，右侧应是相对、根相对或绝对 URL。

按文档顺序接入 HTML

type="importmap" 内部是 JSON，不支持 JavaScript 注释、尾逗号或变量插值。它必须出现在依赖这些键的模块脚本之前；生产页面通常把它放在入口模块标签附近，便于一起检查。

相对地址按照包含 Import Map 的文档基准 URL 解析，所以从本地文件双击打开页面并不能代表线上部署结果。应通过开发服务器访问，并重点确认静态资源的响应路径和 JavaScript MIME 类型。

// 中文注释：在可选增强场景中，先判断当前文档是否支持 Import Maps
const supportsImportMaps = HTMLScriptElement.supports?.("importmap") === true;

if (!supportsImportMaps) {
  // 中文注释：兼容旧环境时进入构建产物或降级入口，不假设别名已经生效
  document.documentElement.classList.add("no-importmap");
}

用 scopes 管理局部依赖版本

当应用的一部分仍依赖旧版库、另一部分已经迁移到新版时，可以在 scopes 中按“发起 import 的模块 URL 路径”提供局部映射。匹配多个 scope 时，路径更长、更具体的 scope 优先；局部 scope 没有命中某个键时，浏览器会继续回退到更宽的 scope，最后再查全局 imports。

{
  "imports": {
    "shared-ui": "/assets/shared-ui-v2/index.js"
  },
  "scopes": {
    "/legacy/": {
      "shared-ui": "/assets/shared-ui-v1/index.js"
    }
  }
}

上面的 JSON 没有加入注释，是因为 Import Map 必须保持严格 JSON。含义是：从 /legacy/ 路径下模块发起的 shared-ui 使用旧版，其余模块使用全局新版。scope 的路径只负责选择规则，右侧 URL 仍按 Import Map 所在文档的基准解析。若没有真实的兼容边界，不要为了“看起来灵活”提前引入 scopes，它会增加依赖图排查成本。

迁移后按清单回归

最后检查缓存策略：如果构建产物使用哈希文件名，业务模块只保留稳定别名，发布时更新 Import Map 即可减少引用链改动。对不支持 Import Maps 的环境，选择构建阶段展开路径或提供降级入口，不要把运行时兼容判断和业务模块耦合在一起。

常见问题

Import Map 能改写 script 的 src 吗？

不能。它只解析模块中的 import 与 import() 说明符，入口脚本的 src 仍要写真实 URL。

为什么目录别名必须写两个斜杠？

末尾斜杠表示前缀匹配。键和值都带斜杠时，浏览器才能把后续子路径拼到目标目录；单文件别名则不需要斜杠。

可以在 Worker 里直接使用页面的别名吗？

不能把页面 Import Map 当成 Worker 配置。Worker 的模块加载边界需要单独设计，或在构建阶段把依赖路径处理成 Worker 可用的 URL。