ES modules import maps 管理浏览器依赖映射的配置

在浏览器原生 ES modules 中，用 定义 imports，将裸模块名映射到实际模块 URL；需要不同导入者使用不同版本时，再用 scopes。把一份完整映射放在依赖它的模块入口之前，并使用固定的资源地址，能让页面依赖配置更明确。

import maps 只控制模块标识符解析，不会安装 npm 包、打包 CommonJS 或自动下载缺失文件。本文使用原创 report-kit 示例，文件需由项目自行部署。规范地址：https://html.spec.whatwg.org/multipage/webappapis.html#import-maps；配置参考：https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script/type/importmap。

先明确映射与资源部署的职责

生产目标可以拆成两项：业务模块只引用稳定名称，发布配置决定这个名称对应哪份浏览器 ESM 文件。浏览器仍需通过正常 URL 加载资源，因此每个映射目标都要真实可访问，并返回适当 JavaScript MIME 类型。本文不是包管理器方案，不将任意 node_modules 文件直接暴露视为通用部署方式。

最小示例包含入口模块、公共模块目录与两个版本的导出文件。以下 report-kit 是自定义示例名，不是需要读者下载的第三方产品。

配置精确名称与目录前缀

report-kit 精确对应入口模块；report-kit/ 对应模块目录前缀，两者互不代替。前缀键和值都保留末尾斜杠，模块标识符 report-kit/format.js 才能映射到 /assets/report-kit/v2/format.js。不是把字符串里所有相似字符都替换一遍。

// /assets/report-kit/v2/index.js：原创示例入口
export const apiVersion = "v2";

// /assets/report-kit/v2/format.js：浏览器ESM导出
export function formatTotal(value) {
  return new Intl.NumberFormat("zh-CN").format(value);
}

// /app/main.js：名称由页面映射决定
import { apiVersion } from "report-kit";
import { formatTotal } from "report-kit/format.js";
// 这里只演示模块导出契约，不代表线上运行回执
console.log(apiVersion, formatTotal(2300));

映射中的相对 URL 按 import map 的基准 URL 解析，不是按每个导入文件的位置拼接。这里刻意使用站点根路径，减少页面目录变化的影响；若网站部署在子路径，需要按实际资源布局调整，而不是原样照搬根目录地址。

用导入者URL限定scopes

假设旧版入口位于 /app/legacy/main.js，新版入口是 /app/main.js。旧版需要 v1，其余代码默认使用 v2，可以用下列完整配置替换前一份映射，而不是把它当作修改已有解析结果的补丁。

{
  "imports": {
    "report-kit": "/assets/report-kit/v2/index.js",
    "report-kit/": "/assets/report-kit/v2/"
  },
  "scopes": {
    "/app/legacy/": {
      "report-kit": "/assets/report-kit/v1/index.js",
      "report-kit/": "/assets/report-kit/v1/"
    }
  }
}

这是严格 JSON，imports 是默认映射，scopes 的键限定导入者 URL 前缀。作用域内未找到的标识符，会继续查找适用的更外层映射及 imports。旧版文件也需要按相同导出契约提供 v1/index.js 和 v1/format.js，映射不能补齐缺失的导出。

scope 不根据 DOM 组件、脚本标签所在区域或“调用链属于哪个业务”决定。比如 /assets/report-kit/v1/helper.js 再导入其他裸名称时，导入者已经是 helper.js 自己；不能假定它继续继承 /app/legacy/ 的范围。依赖内部优先采用相对路径，或者为它实际所在 URL 另行设计映射。

把资源权限与映射配置分开管理

scopes 不是沙箱。同页模块仍按页面与浏览器已有安全模型运行，给两个模块不同版本并不会产生权限隔离。将依赖放到受控资源目录并固定版本，是为了让发布和回滚可追溯，不是给模块授予额外权限。

跨域目标仍受模块加载的 CORS 与站点 CSP 等规则约束，映射成功不等于网络加载成功。若页面已有 CSP，内联 import map 需要符合该策略，不能为了省事关闭整站约束；使用 nonce 等策略时由服务端按站点方案生成，不能把示例固定值当成生产 nonce。

本文采用内联 JSON，不给 importmap 标签设置 src。它也不会重写模块入口 script 的 src，更不会成为 fetch 的通用别名表。页面模块映射不要直接外推到 worker 或 worklet 环境。

按失败阶段定位，并把映射与文件一起发布

规范允许处理多份 import maps，并限制后来映射对既有定义和已解析标识符的影响；不同目标浏览器对相关能力的支持还需按项目范围判断。为了减少部署歧义，本方案只使用一份入口前的完整映射，不依赖运行中追加配置去热切换已有模块。

• 先发布新的固定版本资源，再发布引用它的页面映射。
• 保留旧版本资源以供旧页面和回滚使用，避免新旧缓存交错时丢失文件。
• 回滚恢复对应HTML映射及资源契约，不只改一个模块的版本字符串。
• 故障记录保存失败阶段、导入者URL与目标URL，避免把解析错误统称成网络问题。

常见问题

映射配置会自动处理package.json的依赖吗？

不会。需要部署可供浏览器加载的文件，并明确列出其使用的裸名称映射。

动态import也能使用这里的名称吗？

文档模块中的 import() 同样使用相关模块标识符解析规则；它不是任意字符串到网络URL的重写器。

改了映射能让已经加载的模块换版本吗？

不要这样设计。已有定义和解析结果受到合并规则约束，本方案以重新加载对应发布页面完成版本切换。

需要兼容不支持import maps的环境怎么办？

根据浏览器支持矩阵选择构建产物或经过评估的兼容方案，不能指望浏览器把裸名称自动理解成文件路径。