# @cocos/rollup-plugin-node-resolve 中文文档

规范地址：https://npmcn.com/package/%40cocos/rollup-plugin-node-resolve/

版本：15\.3\.0
npm 元数据更新时间：2025-05-21T08:20:39.209Z
中文译文更新时间：2026-11-10T07:08:48.076Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cocos/rollup-plugin-node-resolve
原文对照：https://npmcn.com/package/%40cocos/rollup-plugin-node-resolve/?lang=original
项目主页：https://github.com/rollup/plugins/tree/master/packages/node-resolve/#readme
源码仓库：https://github.com/rollup/plugins

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：109 kB，7 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=14\.0\.0
- 运行依赖：5 个
- peer 依赖：rollup ^2\.78\.0\|\|^3\.0\.0\|\|^4\.0\.0
- 首次发布：2024-11-04T08:25:27.988Z
- 最新版本发布：2024-11-04T08:25:28.250Z
- 近 30 天下载量：2473（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：1（近 12 个月 0 个）

## 中文简介

在节点模块中定位和捆绑第三方依赖性

## 安装

```sh
npm install @cocos/rollup-plugin-node-resolve
```

也可以使用：`pnpm add @cocos/rollup-plugin-node-resolve`、`yarn add @cocos/rollup-plugin-node-resolve`、`bun add @cocos/rollup-plugin-node-resolve`

## README

[![npm](https://img.shields.io/npm/v/@rollup/plugin-node-resolve)](https://www.npmjs.com/package/@rollup/plugin-node-resolve) [![size](https://packagephobia.now.sh/badge?p=@rollup/plugin-node-resolve)](https://packagephobia.now.sh/result?p=@rollup/plugin-node-resolve) [![libera manifesto](https://img.shields.io/badge/libera-manifesto-lightgrey.svg)](https://liberamanifesto.com/)

# @ rollup/ plugin- node- resolve

使用 : [节点解析算法](https://nodejs.org/api/modules.html#modules_all_together),用于在 `node_modules`

## 所需资源

此插件需要一个 [长期](https://github.com/nodejs/Release) 节点版本(v14.0.0+)和"滚出"v2.78.0+.

## 安装

使用 npm :

```console
npm install @rollup/plugin-node-resolve --save-dev
```

## 使用量

创建一个 `rollup.config.js` [配置文件](https://www.rollupjs.org/guide/en/#configuration-files) 并导入插件 :

```js
import { nodeResolve } from '@rollup/plugin-node-resolve';

export default {
  input: 'src/index.js',
  output: {
    dir: 'output',
    format: 'cjs'
  },
  plugins: [nodeResolve()]
};
```

那就打电话 `rollup` 要么通过 [国 际](https://www.rollupjs.org/guide/en/#command-line-reference) 或 [API 密码](https://www.rollupjs.org/guide/en/#javascript-api)。 。 。 .

## 软件包入口

此插件支持来自节点js的软件包切入点特性,该特性在 `exports` 或者说 `imports` 字段。 检查 [正式文件](https://nodejs.org/api/packages.html#packages_package_entry_points) 了解更多信息,说明如何运作。 这是默认行为。 在这些地区 `mainFields` 将被使用.

## 选项

### `exportConditions`

类型 : `Array[...String]`  
默认 : `[]`

Package.json导出字段的附加条件在解析模块时匹配. 默认情况下,此插件将查找 `['default', 'module', 'import']` 解决进口时的条件.

使用时 `@rollup/plugin-commonjs` v16 或更高, 此插件将使用 `['default', 'module', 'require']` 解决时的条件需要声明.

设置此选项将在默认条件外添加额外条件 。 见 [https://nodejs.org/api/packages.html#packages 有条件的 exports](https://nodejs.org/api/packages.html#packages_conditional_exports) 更多信息.

为了得到 [解析节点.js的行为](https://nodejs.org/api/packages.html#packages_conditional_exports),设置为 `['node']`。 。 。 .

### `browser`

类型 : `Boolean`  
默认 : `false`

若为 `true`,指示插件在 `package.json` 添加 `'browser'` 改为 `exportConditions` 如果它不在场, 浏览器条件为 `exports` 适用。 若为 `false`,包文件中的任何浏览器属性都将被忽略。 或者,价值为 `'browser'` 可添加到两个 `mainFields` 财务报告和审定财务报表 `exportConditions` 选项,但此选项优先于 `mainFields`。 。 。 .

> 软件包使用时此选项不起作用 [软件包条目](https://nodejs.org/api/packages.html#packages_package_entry_points)

### `moduleDirectories`

类型 : `Array[...String]`  
默认 : `['node_modules']`

一份目录名称列表, 用于重复查找模块 .

### `modulePaths`

类型 : `Array[...String]`  
默认 : `[]`

用于搜索模块的其他位置的绝对路径列表 . [这类似于设置 `NODE_PATH` 节点的环境变量](https://nodejs.org/api/modules.html#loading-from-the-global-folders)。 。 。 .

### `dedupe`

类型 : `Array[...String]`  
默认 : `[]`

一个 `Array` 模块名称,指示插件将指定的模块强制解析到根 `node_modules`。如果从依赖区导入了软件包,有助于防止同一软件包被多次捆绑.

```js
dedupe: ['my-package', '@namespace/my-package'];
```

这会使纯进口产品减少,例如:

```js
import 'my-package';
import '@namespace/my-package';
```

它将使深度进口减少,例如:

```js
import 'my-package/foo.js';
import '@namespace/my-package/bar.js';
```

### `extensions`

类型 : `Array[...String]`  
默认 : `['.mjs', '.js', '.json', '.node']`

指定插件将操作的文件的扩展名.

### `jail`

类型 : `String`  
默认 : `'/'`

在指定的路径(如chroot)内锁定模块搜索。 在此路径外定义的模块会被此插件忽略 .

### `mainFields`

类型 : `Array[...String]`  
默认 : `['module', 'main']`  
有效值 : `['browser', 'jsnext:main', 'module', 'main']`

指定要扫描的属性 `package.json`,用于确定捆绑入点。 物业名称的顺序很重要,因为先得地产被用作已解决的出入口. 如果数组包含 `'browser'`键/值 `package.json` `browser` 属性将被使用.

### `preferBuiltins`

类型 : `Boolean | (module: string) => boolean`  
默认 : `true` (如果在本地版本上使用内建模块,则警告。) 设定为 `true` 以禁用警告。)

若为 `true`,插件将选择内置模块(例如:. `fs`, (中文(简体) ), `path`) (中文(简体) ). 若为 `false`,插件将查找本地安装的同名模块.

或者,您可以在返回布尔值的函数中通过,以确认插件是否应该选择内置模块。 譬如说.

```js
preferBuiltins: (module) => module !== 'punycode';
```

不治疗 `punycode` 作为内置模块

### `modulesOnly`

类型 : `Boolean`  
默认 : `false`

若为 `true`,检查已解决的文件,以断言它们是ES2015模块.

### `resolveOnly`

类型 : `Array[...String|RegExp] | (module: string) => boolean`  
默认 : `null`

一个 `Array` 它指示插件将模块分辨率限制在名称符合数组图案的人. _注意: 不匹配任何模式的模块将被标记为外部模式 ._

或者,您可以在返回布尔值的函数中通过,以确认模块是否应当包含.

实例:

-   `resolveOnly: ['batman', /^@batcave\/.*$/]`
-   `resolveOnly: module => !module.includes('joker')`

### `rootDir`

类型 : `String`  
默认 : `process.cwd()`

指定用于解决模块的根目录。 通常用于解决入点导入,以及解决去重复模块. 在一个单存储器包中执行滚动时有用 .

```
// Set the root directory to be the parent folder
rootDir: path.join(process.cwd(), '..')
```

### `ignoreSideEffectsForRoot`

如果你使用 `sideEffects` 属性在 package.json 中,默认情况下,对根包中的文件尊重此选项。 设定为 `true` 忽略 `sideEffects` 根包的配置.

### `allowExportsFolderMapping`

旧节点版本支持导出文件夹的映射

```json
{
  "exports": {
    "./foo/": "./dist/foo/"
  }
}
```

这与"节点"14被贬值,被"节点"17被去除,相反建议采用"等出口模式"

```json
{
  "exports": {
    "./foo/*": "./dist/foo/*"
  }
}
```

但是,为了反向兼容性,这个行为仍然通过启用 `allowExportsFolderMapping` (违约) `true`) (中文(简体) ). 默认值在将来的主要发行中可能会有变化.

## 保留符号链接

此插件符合滚动 [`preserveSymlinks`](https://rollupjs.org/guide/en/#preservesymlinks) 选项.

## 使用时使用@ rollup/ plugin- commonjs

由于您节点- 模块文件夹中的大多数软件包可能都是遗留的 CommunityJS 而不是 JavaScript 模块, 您可能需要使用 [@ rollup/ plugin- commonjs (英语)](https://github.com/rollup/plugins/tree/master/packages/commonjs)数字 :

```js
// rollup.config.js
import { nodeResolve } from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';

export default {
  input: 'main.js',
  output: {
    file: 'bundle.js',
    format: 'iife',
    name: 'MyModule'
  },
  plugins: [nodeResolve(), commonjs()]
};
```

## 解决已建内线( 如 `fs`(中文(简体) )

默认情况下,此插件会比本地模块更偏好内置,将其标为外置.

见 [`preferBuiltins`](https://npmcn.com/package/%40cocos/rollup-plugin-node-resolve/#readme-preferbuiltins)。 。 。 .

要提供节点内置的倒接版,请使用类似插件 [卷起插孔-节点-填充](https://github.com/ionic-team/rollup-plugin-node-polyfills) 设置 `preferBuiltins` 改为 `false`例如.

```js
import { nodeResolve } from '@rollup/plugin-node-resolve';
import nodePolyfills from 'rollup-plugin-node-polyfills';
export default ({
  input: ...,
  plugins: [
    nodePolyfills(),
    nodeResolve({ preferBuiltins: false })
  ],
  external: builtins,
  output: ...
})
```

## 解决需要的语句

根据 [节点JS模块分辨率](https://nodejs.org/api/packages.html#packages_package_entry_points) `require` 语句应使用 `require` 组合导出字段的条件,而 es 模块应使用 `import` 条件.

节点解析插件使用 `import` 默认情况下,您可以选择使用 `require` 语义学通过向解析函数传递额外选项:

```js
this.resolve(importee, importer, {
  skipSelf: true,
  custom: { 'node-resolve': { isRequire: true } }
});
```

## 解析选项

此插件解决了目标文件中的导入 ID 后 `node_modules`它会引用 `this.resolve` 和已解决的ID。 它将在解决方案中通过下列信息:

```js
this.resolve(resolved.id, importer, {
  custom: {
    'node-resolve': {
      resolved, // the object with information from node.js resolve
      importee // the original import id
    }
  }
});
```

您的插件可以使用 `importee` 将原始导入映射到已解析文件的信息 `node_modules`,在插件钩子中,例如 `resolveId`。 。 。 .

这个 `resolved` 对象包含已解析的 id,它作为第一个参数被传递。 它也有财产 `moduleSideEffects`,其中可能包含 npm 值 `package.json` 字段 `sideEffects` 或者说 `null`。 。 。 .

## 元数据

[捐款](https://npmcn.com/.github/CONTRIBUTING.md)

[利比里亚(麻省理工学院)](https://npmcn.com/LICENSE)

## 常见问题

### @cocos/rollup-plugin-node-resolve 是什么？

在节点模块中定位和捆绑第三方依赖性

### 如何安装 @cocos/rollup-plugin-node-resolve？

在项目目录运行 npm install @cocos/rollup-plugin-node-resolve，或使用 pnpm add / yarn add / bun add。

### @cocos/rollup-plugin-node-resolve 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cocos/rollup-plugin-node-resolve 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @cocos/rollup-plugin-node-resolve 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=14\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cocos/rollup-plugin-node-resolve 可以商用吗？

@cocos/rollup-plugin-node-resolve 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cocos/rollup-plugin-node-resolve 的下载量有多少？

根据 npm 官方下载统计，@cocos/rollup-plugin-node-resolve 在 2026/10/10 – 2026/11/08 这 30 天内被下载 2,473 次，日均约 82 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cocos/rollup-plugin-node-resolve 还在维护吗？

最新版本 15\.3\.0 发布于 2024/11/04（2 年前）；至今共发布 1 个版本，其中过去 12 个月发布了 0 个；首次发布于 2024/11/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。