关于创建含浏览器与服务端代码的同构ESM包的正确性及优化咨询

数据老陈

2026-6-18

同构ESM包创建与importmap优化问题

背景信息

我正在尝试创建一个包含浏览器专属、服务端专属及共享代码的同构ESM包，目录结构如下：

src/
  browser.js
  server.js
  shared.js

package.json使用了条件导出配置：

"type": "module",
"exports": {
  "node": "./src/server.js",
  "default": "./src/browser.js"
}

在另一个项目中：

浏览器端的example-browser.js导入代码：

import { shared, browser } from "esm-package-browser-server";
console.log(shared('Example'));
console.log(browser('Example'));

对应的HTML文件：

<html>
  <script type="importmap">
    {
      "imports": {
        "esm-package-browser-server": "./node_modules/esm-package-browser-server/src/browser.js"
      }
    }
  </script>
  <script type="module" src="example-browser.js"></script>
</html>

服务端的example-server.js导入代码：

import { shared, server } from "esm-package-browser-server";
console.log(shared('Example'));
console.log(server('Example'));

运行命令：

node example-server.js

目前该方案在两种环境中均可正常运行，我有以下问题：

这是创建同构ESM包的“正确”方式吗？如果不是，应如何修改？
我必须使用指向./node_modules/esm-package-browser-server/src/browser.js的importmap，能否改为指向./node_modules/esm-package-browser-server并自动推断browser.js？或者完全不用importmap？

问题解答

1. 同构ESM包的创建方式优化

你的方案整体方向是正确的，但可以做一些更规范的调整，提升包的兼容性和可维护性：

明确添加浏览器条件导出字段：目前仅用default兜底浏览器环境，建议显式声明browser字段，让环境解析逻辑更清晰：
```
"exports": {
  "node": "./src/server.js",
  "browser": "./src/browser.js",
  "default": "./src/browser.js"
}
```

统一导出结构：确保browser.js和server.js都同步导出共享内容，避免用户在不同环境导入时需要调整代码。示例：

// src/browser.js
import * as shared from './shared.js';
export const browser = (msg) => `Browser: ${msg}`;
export { shared };

// src/server.js
import * as shared from './shared.js';
export const server = (msg) => `Server: ${msg}`;
export { shared };

添加构建产物（针对发布场景）：如果要将包发布到npm，建议添加构建步骤（用rollup、esbuild等工具），将源码编译为兼容的ESM产物，并把exports指向构建后的文件，而非源码目录：
```
"exports": {
  "node": "./dist/server.js",
  "browser": "./dist/browser.js",
  "default": "./dist/browser.js"
},
"scripts": {
  "build": "rollup -c"
}
```

2. importmap的优化方案

可以实现指向包根目录或完全移除importmap，具体如下：

方案1：修改importmap指向包根目录

浏览器原生不支持直接解析npm包根目录的package.json导出规则，但借助开发服务器（如Vite、Webpack Dev Server）即可实现：

开发服务器会自动识别包的条件导出配置，此时你可以将importmap修改为：
```
{
  "imports": {
    "esm-package-browser-server": "./node_modules/esm-package-browser-server/"
  }
}
```
服务器会根据浏览器环境自动匹配browser字段对应的文件。

方案2：完全移除importmap

有两种可行方式：

使用现代开发/构建工具：Vite、Snowpack等工具支持在浏览器模块中直接导入npm包名称（如import ... from "esm-package-browser-server"），工具会自动处理模块解析、路径映射，无需手动配置importmap。
生产环境预构建：用rollup、esbuild等工具构建生产代码时，将npm包的导入路径替换为实际的文件路径，浏览器可直接加载对应文件，无需依赖importmap。

内容的提问来源于stack exchange，提问作者Kim T

关于创建含浏览器与服务端代码的同构ESM包的正确性及优化咨询

背景信息 #

问题解答 #

1. 同构ESM包的创建方式优化 #