> For AI agents: the complete documentation index is available at https://rspack.rs/zh/llms.txt, the full documentation bundle is available at https://rspack.rs/zh/llms-full.txt.

# Node

全局变量：该选项可以配置是否 polyfill 或 mock 某些 [Node.js 全局变量](https://nodejs.org/docs/latest/api/globals.html)。

- **类型：** `false | object`

将 `node` 设置为 `false` 可以禁用所有 Node.js 全局变量的 polyfill 和 mock。否则，可以使用下面的选项分别配置。

## node.global

- **类型：** `boolean | 'warn'`
- **默认值：** 当 [target](https://rspack.rs/zh/config/target.md) 原生提供 `global` 时为 `false`，否则为 `'warn'`。

控制 Rspack 在为非 Node 环境打包时，是否需要为 Node.js 的 `global` 对象提供 polyfill。

例如，`target: 'node'` 时默认为 `false`，`target: 'web'` 时默认为 `'warn'`。

关于该对象的具体行为，请参考 [Node.js 文档](https://nodejs.org/api/globals.html#globals_global)。

### 可选值

- `true`：Rspack 会注入 polyfill，使打包产物中能够使用 `global`。适用于依赖 Node.js 全局变量、但运行在非 Node 环境的代码
- `false`：不注入 polyfill。对 `global` 的引用将保持原样。如果目标环境不支持 `global`，运行时会抛出 `ReferenceError`
- `'warn'`：行为与 `true` 相同，会注入 polyfill，同时在使用 `global` 时额外打印警告

### 示例

例如，禁用 `global` polyfill：

```js title="rspack.config.mjs"
export default {
  node: {
    global: false,
  },
};
```

## node.\_\_filename

- **类型：** `boolean | 'mock' | 'warn-mock' | 'eval-only' | 'node-module'`
- **默认值：**
  - 当 `target` 不包含 `node` 时，默认值为 `'warn-mock'`。
  - 当 `target` 包含 `node` 时，启用 [output.module](https://rspack.rs/zh/config/output.md#outputmodule) 则为 `'node-module'`，否则为 `'eval-only'`

控制 Rspack 在为非 Node 环境打包时，如何处理 Node.js 的 [`__filename`](https://nodejs.org/api/modules.html#__filename) 和 [`import.meta.filename`](https://nodejs.org/api/esm.html#importmetafilename) 变量。

### 可选值

- `true`：替换为源文件相对于 [`context`](https://rspack.rs/zh/config/context.md) 的相对文件路径
- `false`：不做任何处理，保持原生行为
- `'mock'`：替换为 `'/index.js'`
- `'eval-only'`：等同于 `false`
- `'warn-mock'`：替换为 `'/index.js'`，并输出警告，用于提醒代码中存在潜在的 Node 依赖
- `'node-module'`：仅在 [output.module](https://rspack.rs/zh/config/output.md#outputmodule) 启用时使用。将 CommonJS 中的 `__filename` 替换为基于 `import.meta.url` 的等价实现，适合 ESM 产物

### 示例

例如，不对 `__filename` 和 `import.meta.filename` 进行任何处理，在产物中保留原内容：

```js title="rspack.config.mjs"
export default {
  node: {
    __filename: false,
  },
};
```

将 ESM 产物中的 `__filename` 和 `import.meta.filename` 替换为 `fileURLToPath(import.meta.url)`：

```js title="rspack.config.mjs"
export default {
  target: 'node',
  output: {
    module: true,
  },
  node: {
    __filename: 'node-module',
  },
};
```

## node.\_\_dirname

- **类型：** `boolean | 'mock' | 'warn-mock' | 'eval-only' | 'node-module'`
- **默认值：**
  - 当 `target` 不包含 `node` 时，默认值为 `'warn-mock'`。
  - 当 `target` 包含 `node` 时，启用 [output.module](https://rspack.rs/zh/config/output.md#outputmodule) 则为 `'node-module'`，否则为 `'eval-only'`

控制 Rspack 在为非 Node 环境打包时，如何处理 Node.js 的 [`__dirname`](https://nodejs.org/api/modules.html#__dirname) 和 [`import.meta.dirname`](https://nodejs.org/api/esm.html#importmetadirname) 变量。

### 可选值

- `true`：替换为源文件的目录路径，相对于 [`context`](https://rspack.rs/zh/config/context.md) 选项
- `false`：不做任何处理，保持原生行为
- `'mock'`：替换为 `'/'`
- `'eval-only'`：等同于 `false`
- `'warn-mock'`：替换为 `'/'`，并输出警告，用于提醒代码中存在潜在的 Node 依赖
- `'node-module'`：仅在 [output.module](https://rspack.rs/zh/config/output.md#outputmodule) 启用时使用。将 CommonJS 中的 `__dirname` 替换为基于 `import.meta.url` 的等价实现，适合 ESM 产物

### 示例

例如，不对 `__dirname` 和 `import.meta.dirname` 进行任何处理，在产物中保留原内容：

```js title="rspack.config.mjs"
export default {
  node: {
    __dirname: false,
  },
};
```

将 ESM 产物中的 `__dirname` 和 `import.meta.dirname` 替换为 `fileURLToPath(import.meta.url + "/..")`：

```js title="rspack.config.mjs"
export default {
  target: 'node',
  output: {
    module: true,
  },
  node: {
    __dirname: 'node-module',
  },
};
```


本页改编自 [webpack 文档](https://webpack.docschina.org/configuration/node/)，遵循 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)，且已作修改。