开发兼容浏览器/Node的UMD库时如何处理fetch等环境差异API

一、请求类API适配方案 #

针对你遇到的axios兼容问题，有两种可行方案：

• 方案1：替换为同构fetch实现。直接选用isomorphic-unfetch、cross-fetch这类专门做跨端适配的请求库，这类库会自动在Node环境绑定node-fetch、浏览器环境调用原生fetch，不存在XMLHttpRequest未定义的问题，体积也比axios更小。
• 方案2：修复axios打包配置。如果必须使用axios，不要直接引入源码，而是在webpack的resolve.alias中配置axios: path.resolve(__dirname, 'node_modules/axios/dist/axios.min.js')，该版本是axios官方预构建的双端兼容版本，打包时不会丢失Node端的http适配器逻辑。

二、构建配置修正（解决externals双端兼容问题） #

如果你希望将axios作为外部依赖不打入包体，需要按UMD规范配置多环境externals，不能仅做全局排除：

// webpack.config.js
module.exports = {
  output: {
    libraryTarget: 'umd',
    globalObject: 'this', // 关键配置，兼容Node和浏览器的全局对象指向
    library: 'YourLibraryName'
  },
  externals: {
    axios: {
      commonjs: 'axios', // Node CommonJS 导入
      commonjs2: 'axios', // Node CommonJS 导出兼容
      amd: 'axios', // AMD 模块导入
      root: 'axios' // 浏览器全局变量导入，要求用户提前通过script引入axios
    }
  },
  target: 'universal' // 开启双端兼容打包模式
}

配置后Node端会自动从node_modules导入axios，浏览器script引入场景会从window.axios读取依赖，不会出现未定义报错。

三、原生浏览器ES模块兼容方案 #

浏览器原生ES模块不支持裸导入（绝对路径导入npm包）的问题有三种成熟解决方案：

• 方案1：单独构建浏览器专用ESM版本。在rollup/webpack中新增一份构建配置，将axios等第三方依赖全部打入该版本的包体，package.json中新增browser字段指向该浏览器ESM包，原生ES模块导入场景用户直接引入该包即可。
• 方案2：构建时替换导入路径。构建ESM版本时，通过@rollup/plugin-replace或者webpack的DefinePlugin将import axios from 'axios'替换为import axios from '对应版本的axios ESM格式公开资源地址'，原生ES模块可直接识别该类远程路径。
• 方案3：文档补充import map指引。告知使用原生ES模块的用户，在HTML中添加import map配置，将裸导入路径映射到对应公开资源地址：

<script type="importmap">
{
  "imports": {
    "axios": "对应版本的axios ESM格式公开资源地址"
  }
}
</script>

四、其他跨端库通用兼容注意事项 #

• 全局对象统一使用globalThis，低版本环境可做polyfill，不要直接调用window、global等环境特有的全局对象。
• 所有环境特有API（比如Node的Buffer、fs，浏览器的document、localStorage）调用前必须做环境判断，或者设计为依赖注入，由上层使用方传入对应实现。
• 优先使用rollup作为库的构建工具，相比webpack更适合多格式（CJS/UMD/ESM）输出，配置更简洁，打包产物体积更小。

内容的提问来源于stack exchange，提问作者Sayed Muhammad Talha