理解 package.json imports：一次配置，跨环境自由切换

package.json 的 imports 字段 配置，它可以让你在代码里用简短的"内部别名路径"来引用模块，同时还能根据运行环境（如 Node.js 还是浏览器/打包器）选择不同的实现。

官网代码拆解

json 复制代码

// package.json
{
  "imports": {
    "#dep": {
      "node": "dep-node-native",
      "default": "./dep-polyfill.js"
    }
  },
  "dependencies": {
    "dep-node-native": "^1.0.0"
  }
}

1. `"imports"`

imports 是 Node.js 自定义导入路径（subpath imports） 的配置。
语法要求前缀必须是 #，例如 #dep。
配置的值可以是 路径映射表 或者 字符串。

2. `#dep`

表示在项目里你可以这样导入：
javascript 复制代码
```
import dep from "#dep";
```
Node.js 会根据运行环境，解析成不同的实际模块。

3. 条件导入（conditional exports/imports）

"node": "dep-node-native"
- 如果代码运行在 Node.js 环境中，#dep 会被映射到依赖包 dep-node-native。
"default": "./dep-polyfill.js"
- 如果在 其他环境 （例如浏览器打包、非 Node 环境），#dep 会被解析到项目本地的 ./dep-polyfill.js 文件。

这就是条件导入机制（和 exports 类似，但用于内部别名）。

4. `"dependencies"`

json 复制代码

"dependencies": {
  "dep-node-native": "^1.0.0"
}

因为 Node 环境下会实际使用 dep-node-native 包，所以要在依赖中声明它。
./dep-polyfill.js 是本地文件，不需要放在 dependencies 里。

使用效果

假设 dep-node-native 是一个 Node.js 原生实现的库，而 dep-polyfill.js 提供了浏览器可运行的 polyfill。

代码里写：

javascript 复制代码

import dep from "#dep";

在 Node.js 运行时 → 实际加载 dep-node-native
在 浏览器打包工具 （如 Vite/Webpack） → 实际加载 ./dep-polyfill.js

知识延伸：常见条件 Key

1. 通用环境

"default"
- 兜底条件：任何环境都匹配。
- 必须放在最后，因为一旦匹配到 default，后面的条件不会再被检查。

2. 运行时环境

"node"
- 运行在 Node.js 环境时匹配。
"browser"
- 一般由打包工具（webpack / vite / rollup）识别，不是 Node.js 自带的条件。
- 常用来提供浏览器端 polyfill。

3. 模块系统

"import"
- 使用 import (ESM) 加载时匹配。
"require"
- 使用 require (CommonJS) 加载时匹配。

4. 开发者扩展

"types"
- 用于 TypeScript 的 typesVersions 或 exports 提供 .d.ts 定义。
"react-native"、"deno" 等
- 不是 Node.js 内置的条件，但一些工具链会支持。

总结：

这段配置的作用是 给模块 #dep 定义一个跨环境别名 ，在 Node.js 环境下用原生依赖 dep-node-native，而在非 Node 环境下回退到本地的 polyfill 实现，从而实现 同一导入路径，跨平台差异化加载。

参考来源：

nodejs.org#subpath-imports