Webpack 5 的模块解析机制在过去几年经历了一次根本性升级，其中最显著的变化就是引入了基于条件的模块匹配体系，前端社区常把它形象地称为 Matching Universe（匹配宇宙）。这套机制让一个 npm 包能够针对不同的导入方式、运行环境和构建配置提供完全不同的实现文件，从而解决了长期以来单一入口无法同时满足 ESM 与 CommonJS、浏览器与 Node.js 需求的困境。下面我们将从条件导出的底层逻辑、配置语法、自定义条件以及实践中的常见问题几个层面展开分析。
从 main 单一入口到多条件匹配
早期前端项目在解析第三方依赖时，几乎完全依赖 package.json 中的 main 字段。main 字段指向一个固定的入口文件，例如 dist/index.js，无论调用方使用的是 import 还是 require，无论最终代码运行在浏览器还是 Node.js 环境，解析器都会加载同一个文件。这种一刀切的做法在模块生态复杂化之后暴露出很多问题：提供 ESM 版本的包无法让 CommonJS 用户直接使用，面向浏览器的包可能包含 Node.js 专用的 API，开发环境和生产环境需要的代码差异也无法体现。
Node.js 从 12.7.0 开始实验性地支持 package.json 中的 exports 字段，并在后续版本中稳定下来。Webpack 5 完整对齐了这一规范，并进一步扩展了条件名称的自定义能力。exports 字段不再只是一个字符串路径，而是一个可以包含多个条件分支的对象，每个条件分支对应一种解析场景。解析器在遇到 import 语句或 require 调用时，会根据当前激活的条件集合，从 exports 对象中选择最匹配的路径。这个选择过程就像在一个多维空间中查找最合适的坐标，多个条件之间交叉组合，形成一个庞大的匹配矩阵，因此才有了 Matching Universe 的说法。
与 main 字段相比，exports 字段还具有封装性。一旦包声明了 exports，外部就无法再通过深层路径直接访问包内部的任何文件，只能访问 exports 中明确暴露的入口。这一方面提升了包的边界清晰度，另一方面也要求包的维护者仔细设计条件结构，避免因条件遗漏导致用户解析失败。
条件导出的语法与匹配顺序
在 package.json 中配置 exports 字段时，最基本的写法是直接指定一个入口路径，但这无法发挥条件匹配的优势。真正的 Matching Universe 需要对象形式的条件映射。条件键可以分为两类：一类是模块格式条件，如 import、require；另一类是环境条件，如 browser、node、development、production。此外还有一个兜底条件 default，必须放在最后。下面是一个典型的配置示例。
{
"name": "example-lib",
"version": "1.0.0",
"exports": {
".": {
"import": "./esm/index.js",
"require": "./cjs/index.js",
"browser": "./browser/index.js",
"default": "./dist/index.js"
},
"./feature": {
"import": "./esm/feature.js",
"require": "./cjs/feature.js"
}
}
}
在这个示例中，根入口 . 同时定义了 import、require、browser 和 default 四个条件。当 webpack 以 import 方式引入 example-lib 时，如果当前构建目标包含 browser 条件（例如 target 设置为 web），解析器会优先命中 browser 条件，因为它比 import 更具体。Webpack 内部维护了一个条件优先级列表，默认顺序大致为：更具体的环境条件优先于格式条件，格式条件优先于 default。这个顺序并不是简单按对象书写顺序，而是由条件名称的语义和配置决定的。
条件值除了字符串，还可以是嵌套对象，这样可以实现更细粒度的组合匹配。例如，可以针对浏览器的 ESM 和 CommonJS 分别提供不同文件。解析器会递归地查找最匹配的嵌套路径，直到找到字符串路径。这种嵌套结构让 Matching Universe 的维度进一步增加，但同时也增加了维护难度，因此官方建议在满足需求的前提下尽量保持扁平。
在 Webpack 5 中自定义条件名称
Webpack 5 不仅支持 Node.js 标准条件，还允许开发者通过 resolve.conditionNames 配置自定义条件名。这个配置项接受一个字符串数组，数组中的名称会在解析 exports 和 imports 字段时被激活。一个常见的应用场景是区分不同的构建模式，比如为测试环境提供 mock 版本，或者为特定的打包工具提供专属入口。
下面的配置展示了如何添加一个名为 custom 的条件，并在 package.json 中声明对应的入口。
// webpack.config.js
module.exports = {
resolve: {
conditionNames: ['custom', 'import', 'require', 'browser', 'default']
}
};
{
"exports": {
".": {
"custom": "./custom/index.js",
"import": "./esm/index.js",
"require": "./cjs/index.js",
"default": "./dist/index.js"
}
}
}
需要特别注意条件数组的顺序。Webpack 会按照数组顺序依次尝试匹配，因此把更具体的自定义条件放在前面可以确保它优先于通用条件。如果自定义条件放在 default 之后，则永远不会被命中。此外，conditionNames 不仅影响 exports 字段，也同样作用于 imports 字段，imports 字段是 exports 的镜像，用于包内部的自引用，可以避免使用相对路径。
调试条件匹配问题时，可以使用 webpack 的 resolve 相关日志，或者借助 enhanced-resolve 的调试输出查看具体的匹配过程。因为条件匹配是多维的，一旦某个条件名称拼写错误或顺序错乱，解析结果就会与预期不符。
实践中的常见陷阱与优化建议
第一个容易踩的坑是忘记提供 default 条件。当解析器无法命中任何已声明的条件时，如果不存在 default，就会抛出模块未找到的错误。即使你认为所有使用场景都已经被 import、require 等条件覆盖，也应该保留 default 作为安全网，防止未来新增的环境或格式导致解析失败。另一个常见问题是条件顺序错乱导致的意外命中，特别是在使用 browser 和 import 组合时。由于 browser 条件通常比 import 更具体，如果希望 import 优先，就不应该把 browser 放在 import 前面，或者通过 conditionNames 重新定义优先级。
性能方面，exports 字段的条件匹配本身对构建速度影响很小，因为解析器在读取 package.json 后只在内存中遍历条件树，不会触发额外文件读取。但如果你在条件中引用了大量分支，每次解析都会遍历整个条件对象，不过对于大部分包来说这个遍历成本可以忽略。更值得关注的是包的发布配置，确保 exports 字段中的每个路径都真实存在于发布产物中，否则用户会在构建时报错，而且这类错误信息有时不够直观。
对于 TypeScript 用户，exports 字段与类型声明文件的匹配需要额外配置。Webpack 本身不处理类型，但 TypeScript 编译器同样遵循 exports 规范。建议在每个条件分支对应的出口旁边放置类型声明，或者使用 types 条件显式指定声明文件路径。总之，合理运用 Matching Universe 能够让一个包同时服务多种模块格式和运行环境，但前提是条件设计清晰、顺序合理、兜底完整。
通过以上分析可以看到，Webpack 5 的 Matching Universe 并非一个独立的 API，而是由 exports、imports、conditionNames 等配置共同构成的一套解析策略。理解了它的匹配规则，就能在实际项目中更灵活地组织代码和依赖。