package.json中browser、module与main字段的加载优先级详解

browser、module与main字段对比

在前端开发中，使用 npm 包是日常操作，而在使用 npm 包时，不可避免地需要接触 package.json 包的配置文件。

这里便引出一个关键问题：当我们在不同运行环境下 import 一个 npm 包时，系统实际加载的是 npm 包中的哪个文件？

经验丰富的开发者通常能迅速给出答案：即 main 字段中指定的文件。

然而，我们需要明确 npm 包实际上可分为三类：

• 仅限客户端（浏览器）使用的包，
• 仅限服务端（Node.js）使用的包，
• 以及同时兼容浏览器和服务端的包。

若需开发一个同时支持 Web 端和 Server 端的 npm 包，并要求在不同环境下加载 npm 包的不同入口文件，显然仅靠一个 main 字段已无法满足需求，由此衍生出了 module 与 browser 字段。

本文将阐述这几个字段的具体使用场景，以及当它们同时存在时的优先级规则。

文件扩展名优先级

在讨论 package.json 字段之前，先明确文件扩展名的优先级规则。

由于当前模块规范主要包含 ESM 和 CommonJS 两种，为了让 Node.js 环境能够原生执行 ESM 规范的脚本，.mjs 文件应运而生。

当项目中同时存在 index.mjs 和 index.js 这种同名但后缀不同的文件时，无论是通过 import './index' 还是 require('./index') 进行导入，系统都会优先加载 index.mjs 文件。

这意味着在文件扩展名层面，优先级为 mjs 高于 js。

browser、module 和 main 字段详解

字段定义

• main：定义了 npm 包的默认入口文件，Browser 环境和 Node 环境均可使用。
• module：定义了 npm 包符合 ESM 规范的入口文件，Browser 环境和 Node 环境均可使用。
• browser：定义了 npm 包在 Browser 环境下的特定入口文件。

使用场景与优先级分析

首先，假设我们的 npm 包名为 test，其目录结构如下：

----- lib
   |-- index.browser.js
   |-- index.browser.mjs
   |-- index.js
   |-- index.mjs

其中，*.js 文件采用 CommonJS 语法（通过 require('xxx') 引入），而 *.mjs 文件采用 ESM 语法（通过 import 'xxx' 引入）。

其对应的 package.json 配置如下：

"main": "lib/index.js",  // main 
  "module": "lib/index.mjs", // module
  // browser 可定义成和 main/module 字段一一对应的映射对象，也可以直接定义为字符串
  "browser": {
    "./lib/index.js": "./lib/index.browser.js", // browser+cjs
    "./lib/index.mjs": "./lib/index.browser.mjs"  // browser+mjs
  },
  // "browser": "./lib/index.browser.js" // browser

根据上述配置，我们的 package.json 指定的入口文件可能存在以下五种情况：

main

module

browser

browser+cjs

browser+mjs

这涵盖了五种不同的加载路径。

接下来详细分析具体场景。

Webpack + Web + ESM

这是最常见的开发场景，通过 webpack 打包构建 Web 应用，且模块语法使用 ESM。

当我们执行如下代码：

import test from 'test'

实际的加载优先级顺序为：browser 等于 browser+mjs，且高于 module，再高于 browser+cjs，最后才是 main。也就是说，Webpack 会根据这个顺序依次查找字段指定的文件，直到找到为止。

然而，实际情况可能比上述线性关系更为复杂，具体逻辑可参考相关流程图。

Webpack + Web + CommonJS

const test = require('test')

事实上，在构建 Web 应用时，无论使用 ESM 还是 commonJS 模块规范，对加载优先级均无影响。

此时的优先级依然保持为：browser 等于 browser+mjs，且高于 module，再高于 browser+cjs，最后是 main。

Webpack + Node + ESM/CommonJS

我们知道，在使用 Webpack 构建项目时，存在一个 target 选项，默认值为 web，即针对 Web 应用进行构建。

当我们需要构建同构项目或其他 Node.js 项目时，需要将 webpack.config.js 中的 target 选项设置为 node 来进行构建。

import test from 'test'
// 或者 const test = require('test')

在此环境下，优先级为：module 高于 main。

Node + CommonJS

通过 node test.js 直接执行脚本文件。

const test = require('test')

此时，只有 main 字段生效。

Node + ESM

通过 --experimental-modules 参数可以让 Node.js 执行 ESM 规范的脚本（必须使用 .mjs 后缀）： `node --experimental-modules test.mjs`

import test from 'test'

在此模式下，同样只有 main 字段生效。

总结

• 如果 npm 包导出的是符合 ESM 规范的代码，建议使用 module 字段。
• 如果 npm 包仅在 Web 端使用，且严禁在服务端使用，请使用 browser 字段。
• 如果 npm 包仅在服务端使用，请使用 main 字段。
• 如果 npm 包在 Web 端和服务端均允许使用，建议同时配置 browser 和 main 字段。
• 对于其他更复杂的情况，如 npm 包需要提供 CommonJS 与 ESM 等多个规范的多个代码文件，请参考上述使用场景或流程图进行配置。

以上就是 package.json 中 browser、module 和 main 字段优先级对比的详细内容，更多关于 package.json 字段优先级的资料请关注本站其它相关文章！