import maps是monorepo中实现浏览器原生es模块加载的必要基础设施，通过html中声明json映射表，将裸模块名（如@repo/ui）解析为可访问路径或url，绕过浏览器不支持node_modules和tsconfig.paths的限制。
在大型 Monorepo 项目中直接用浏览器原生 type="module" 开发，不走打包流程，会立刻撞上模块路径解析的硬墙：浏览器根本不认识 import { utils } from '@repo/utils' 或 import 'lodash' 这类“裸模块说明符”。Import Maps 不是锦上添花的特性，而是让原生 ES 模块在 Monorepo 场景下能跑起来的必要基础设施。
为什么默认 import 在 Monorepo 里根本走不通
浏览器模块加载器只认三类路径：相对路径（./、../）、绝对路径（/ 开头）和完整 URL。它没有 node_modules 概念，也不读 tsconfig.json 里的 paths 或 baseUrl。你在 apps/web/src/main.ts 里写 import { Button } from '@repo/ui'，浏览器会直接报错：Failed to resolve module specifier "@repo/ui"。
即使你用 pnpm workspace 把 @repo/ui 链到了 node_modules/@repo/ui，那也只是 Node.js 和构建工具（如 Vite）能理解的逻辑，浏览器完全无视符号链接和包名映射。
Import Maps 是怎么补上这块拼图的
Import Maps 就是一张由开发者声明的“路径翻译表”，放在 HTML 的 <script type="importmap"></script> 里，告诉浏览器：“当你看到这个模块名时，请去加载那个 URL 或本地路径”。它不修改源码，不引入构建步骤，纯前端运行时接管解析。
对 Monorepo 来说，关键在于把 workspace 包名映射到本地源码路径。例如：
{
"imports": {
"@repo/ui": "/packages/ui/src/index.ts",
"@repo/utils": "/packages/utils/src/index.ts",
"lodash": "https://cdn.skypack.dev/lodash@4.17.21"
}
}
注意两点：
-
路径必须可被服务器直接访问：
/packages/ui/src/index.ts要求开发服务器（如serve或自定义 Express 中间件）能将/packages/目录作为静态资源公开，且支持 TypeScript 文件的 MIME 类型或预编译（通常需配合 Deno 或 esbuild serve）；更稳妥的做法是先构建出.js文件，再映射到/packages/ui/dist/index.js。 - 避免与构建工具冲突：如果项目同时使用 Vite 或 Webpack，它们有自己的路径解析逻辑，Import Maps 会被绕过。Import Maps 只适用于真正“零构建”的场景，比如快速原型、文档站点或微前端子应用的独立调试。
Monorepo 中落地 Import Maps 的实用建议
单纯配一张 map 表远远不够，需要配套机制保证一致性：
-
自动生成 importmap.json：不要手写。用脚本读取
pnpm-workspace.yaml和各包package.json中的name字段，结合约定的源码入口（如src/index.ts），生成标准importmap.json文件，并在 HTML 中通过<script type="importmap" src="/importmap.json"></script>加载。 -
类型提示不能丢：Import Maps 解决运行时加载，但 TypeScript 编译仍需
paths和references。保持tsconfig.json正确配置，确保 IDE 跳转和类型检查正常——这两套系统并行不悖。 -
慎用 scopes 做多版本隔离：Monorepo 内部一般不需要为不同子应用配不同版本的同一包。若真有此需（如灰度测试），可用
scopes精确控制，例如："scopes": {"/apps/admin/": {"@repo/ui": "/packages/ui-admin/dist/index.js"}}。
它不是万能解药，但解决了特定痛点
Import Maps 让你跳过打包环节，在浏览器里直连 Monorepo 源码，对快速验证跨包 API、编写交互式文档、或搭建轻量级微前端沙箱非常高效。但它不提供代码压缩、Tree Shaking、CSS 提取等构建能力。如果你需要生产部署、性能优化或复杂资源处理，依然得回归 Vite/Webpack/Turbopack 等构建工具链——Import Maps 是补充，不是替代。
