你是否曾因库在Node.js和浏览器中行为不一致而崩溃？或因开发/生产环境混淆导致包体积膨胀？本文将拆解条件导出（Conditional Exports）的底层机制，提供可直接落地的策略。通过真实代码示例，你将掌握从基础配置到避坑的全流程，让库的多环境适配变得简洁高效。

---

一、基本概念与定义

条件导出（Conditional Exports） 是Node.js 12+ 和现代前端工具链（如Webpack、Vite）支持的特性，允许通过 package.json 的 exports 字段，基于运行环境（如 node、browser）或自定义条件（如 development）动态指定模块入口。这解决了传统 main/module 字段的局限性——后者仅能区分CommonJS与ESM，无法处理环境差异。

术语	中文	英文	说明
多入口（Multiple Entry Points）	多个入口文件	Multiple Entry Points	库提供多个导出路径（如 lib/node.js、lib/browser.js）
条件导出（Conditional Exports）	条件导出	Conditional Exports	通过 exports 字段定义环境匹配规则
标准条件（Standard Conditions）	标准条件	Standard Conditions	Node.js内置条件（如 node、browser）
自定义条件（Custom Conditions）	自定义条件	Custom Conditions	非Node.js标准的条件（如 development）

为什么需要它？

• 避免在库代码中写 if (typeof window !== 'undefined') 等环境判断
• 为浏览器环境移除Node.js专属依赖（如 fs）
• 为开发环境启用调试工具（如 console.log），生产环境移除

---

二、关键属性：exports 字段语法详解

在 package.json 中定义条件导出，核心是 exports 字段。其语法结构如下：

{
  "exports": {
    ".": {
      "node": "./lib/node.js",
      "browser": "./lib/browser.js",
      "development": "./lib/dev.js",
      "default": "./lib/index.js"
    }
  }
}

关键规则：

1. 匹配顺序：Node.js 会按顺序匹配条件（node → browser → development → default），首个匹配成功的路径生效。
2. 标准条件：
   • node：Node.js运行时（如 require）
   • browser：浏览器环境（如Webpack的 target: 'web'）
   • import：ESM导入（import 语句）
   • require：CommonJS导入（require 语句）
3. 自定义条件：如 development 需在构建工具中注入（见实战示例）。

输入/输出示例：

• 输入：import { utils } from 'my-lib'
• 输出：
  • 若在浏览器中 → 优先匹配 browser → 导入 ./lib/browser.js
  • 若在Node.js中 → 匹配 node → 导入 ./lib/node.js
  • 若在开发环境（自定义）→ 匹配 development → 导入 ./lib/dev.js

✅ 正确实践：将 default 作为兜底，确保无条件匹配时仍能工作。

---

三、工作原理：条件匹配的底层机制

Node.js 解析 exports 的流程如下：

关键细节：

• browser 条件：由Webpack等工具自动注入（通过 resolve.conditions），非Node.js原生支持。
• 自定义条件：需在构建工具中定义。例如Webpack配置：

  // webpack.config.js
  module.exports = {
    resolve: {
      conditions: ['development', 'browser', 'node'] // 顺序影响匹配
    }
  };
  

• 匹配失败：若所有条件均不匹配，回退到 default。

⚠️ 注意：Node.js 12+ 才支持 exports，旧版本需用 main/module。

---

四、实战示例：真实场景落地

示例1：Node.js vs 浏览器环境隔离（基础）

问题：库需在Node.js中使用 fs，在浏览器中用 fetch。

正确配置（package.json）：

{
  "exports": {
    ".": {
      "node": "./lib/node.js",
      "browser": "./lib/browser.js",
      "default": "./lib/index.js"
    }
  }
}

文件结构：

lib/
├── index.js
├── node.js     # Node.js专用
└── browser.js  # 浏览器专用

lib/node.js：

// 仅Node.js使用
const fs = require('fs');
module.exports = { readFile: (path) => fs.readFileSync(path) };

lib/browser.js：

// 仅浏览器使用
module.exports = { readFile: (url) => fetch(url).then(r => r.text()) };

使用效果：

• 在Node.js：require('my-lib') → 导入 node.js
• 在浏览器：import { readFile } from 'my-lib' → 导入 browser.js

✅ 优势：无环境判断代码，包体积减小（浏览器包移除 fs 依赖）。

示例2：开发/生产环境条件导出（进阶）

问题：开发环境需启用调试日志，生产环境移除。

正确配置（package.json）：

{
  "exports": {
    ".": {
      "development": "./lib/dev.js",
      "production": "./lib/prod.js",
      "default": "./lib/index.js"
    }
  }
}

文件结构：

lib/
├── index.js
├── dev.js      # 开发环境
└── prod.js     # 生产环境

lib/dev.js：

// 开发环境：启用调试
console.log('Debug mode enabled');
module.exports = { log: console.log };

lib/prod.js：

// 生产环境：无调试输出
module.exports = { log: () => {} }; // 空函数

构建工具配置（Webpack）：

// webpack.config.js
module.exports = {
  mode: 'development', // 或 'production'
  resolve: {
    conditions: [
      process.env.NODE_ENV === 'development' ? 'development' : 'production',
      'browser',
      'node'
    ]
  }
};

使用效果：

• 开发模式：import { log } from 'my-lib' → 调用 dev.js（输出日志）
• 生产模式：import { log } from 'my-lib' → 调用 prod.js（无输出）

✅ 优势：通过构建时注入条件，避免运行时条件判断，优化生产包体积。

---

五、应用场景与最佳实践

场景	推荐策略	为什么
基础多环境（Node.js/浏览器）	优先用 node + browser	Node.js原生支持，无需构建工具干预
开发/生产环境	用自定义条件（development/production） + 构建工具注入	避免运行时判断，提升性能
ESM/CommonJS混合	用 import/require 条件	适配不同打包工具（如Vite用 import，Webpack用 require）
过度复杂化	避免同时定义 node 和 browser + 自定义条件	条件顺序混乱易导致错误

最佳实践总结：

1. 用 browser 处理浏览器环境，不要在代码中写 if (typeof window !== 'undefined')。
2. 自定义条件（如 development）必须配合构建工具配置。
3. 始终保留 default 作为兜底。
4. 用 exports 替代 main/module，避免重复配置。

---

六、常见坑与排错建议

问题	原因	解决方案
browser 条件未生效	构建工具未配置 resolve.conditions	在Webpack/Vite中添加 conditions: ['browser']
条件匹配顺序错误	browser 写在 node 后面	确保 node > browser > 自定义条件
自定义条件未注入	构建工具未传递环境变量	用 process.env.NODE_ENV 动态注入条件
default 被意外覆盖	未在 exports 中定义 default	显式添加 "default": "./index.js"
Node.js版本过低	低于12.0.0	升级Node.js或回退到 main/module

💡 防御性写法：在 lib/index.js 中添加断言，避免意外回退：

// lib/index.js
if (typeof process !== 'undefined' && process.env.NODE_ENV === 'production') {
  throw new Error('Production build should use `production` condition');
}

---

七、性能与安全注意

性能：

• 正面：正确使用条件导出可减少5-10%的包体积（移除浏览器环境的Node.js依赖）。
• 风险点：
  • 自定义条件过多（如同时定义 dev、test、prod） → 构建时条件检查开销增加（<1ms，可忽略）
  • 避免在 exports 中写复杂逻辑（如函数），仅指定文件路径。

安全：

• 敏感信息泄露：开发环境的调试日志（如 console.log）不应包含密钥。
  → 对策：在 dev.js 中禁用敏感输出，或用 process.env 控制（如 if (process.env.DEBUG) console.log(...)）。
• XSS风险：若 dev.js 通过 innerHTML 渲染用户输入 → 对策：始终用 textContent 或框架安全API。

---

八、与相关概念的对比

概念	优势	劣势	适用场景
main/module	兼容所有Node.js版本	仅区分CommonJS/ESM，无法处理环境差异	旧库迁移（Node.js <12）
条件导出（exports）	精确控制环境，包体积优化	需Node.js 12+	新库开发首选
browser 字段（旧方案）	简单	仅支持浏览器，无自定义条件	仅浏览器库（如React）

选型建议：

• 新建库：必须用 exports，避免 browser 字段（已被废弃）。
• 维护旧库：逐步迁移到 exports，保留 browser 作为过渡。

---

结尾

核心要点：

1. 条件导出是管理多环境的标准方案，通过 exports 字段 + 构建工具注入实现。
2. 优先用 node/browser 处理基础环境，自定义条件（如 development）需配合构建工具。
3. 始终保留 default，避免运行时错误。