# @antora/user-require-helper 中文文档

规范地址：https://npmcn.com/package/%40antora/user-require-helper/

版本：3\.0\.0
npm 元数据更新时间：2024-11-28T22:54:26.370Z
中文译文更新时间：2026-11-06T07:07:04.165Z
软件包许可：MPL-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40antora/user-require-helper
原文对照：https://npmcn.com/package/%40antora/user-require-helper/?lang=original
项目主页：https://gitlab.com/antora/user-require-helper#readme
源码仓库：https://gitlab.com/antora/user-require-helper

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

- 包体积（解压后）：29.6 kB，4 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=16\.0\.0
- 运行依赖：1 个
- 首次发布：2021-07-12T10:27:25.221Z
- 最新版本发布：2024-11-28T22:54:26.128Z
- 近 30 天下载量：181946（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 0 个）

## 中文简介

在指定上下文中解析模块名称或路径的帮助函数并需要它.

## 安装

```sh
npm install @antora/user-require-helper
```

也可以使用：`pnpm add @antora/user-require-helper`、`yarn add @antora/user-require-helper`、`bun add @antora/user-require-helper`

## README

# @antora/user-require-帮助者

一个节点(Node.js)模块,提供帮助功能,解决与指定上下文相关的模块名称或路径,并要求其(使用) `userRequire`)或返回(使用 `userRequire.resolve`) (中文(简体) ). 扩展路径是系统依赖的. 开发用于安多拉.

此功能的目的是需要用户环境的JavaScript模块(指定为模块名称或路径请求). 这个 `require` 函数在Node.js中解析调用脚本环境中的模块名称和路径(即应用程序代码). 这意味着它不会在本地找到模块 _节点( 模块)_ 文件夹(除非调用脚本也位于该文件夹内)或本地相对路径. 这个假设不适合用户提供的代码.

使用 `require.resolve`,而这正是这个帮助者所封装的功能. 以行为为基础 `require.resolve`,此函数的荣誉前缀为 **@antora/ 扩展路径帮助器** 模块,将请求的模块名称或路径定位到请求中指定的已解决上下文. 见 **使用量** 用于实例.

例如 `.:` 或者说 `./` 前缀将针对指定的点参数分别查找模块名称或路径. 如果未指定上下文,且请求参数是一个模块名称,此函数将使用解析参数指定的函数(默认为内置) `require.resolve` 如果指定,则与路径参数一起. 换句话说,如果给出了光模块名,帮助者会解决模块相对于指定路径,如果指定的话,否则会与调用脚本的环境相干(从而忽略了基和点参数).

函数检查请求参数以区分模块名称和路径. 如果请求参数有文件扩展名, 则以路径解决 . 此外,如果请求的论据以点开头(`./`)或点点(`../`) 段并不含结肠(`:`)作为一条道路解决, _即使它没有文件扩展名_。 。 。 . 否则,它就成了一个模块名称.

**人口贩运**  
如果请求是一个包含文件扩展名的模块名称(例如, `highlight.js`),附件 `/` 以迫使它被当作一个模块名称(例如, `highlight.js/`) (中文(简体) ).

## 安装

```console
$ npm i @antora/user-require-helper
```

## API 密码

```js
function userRequire (id[, context])
```

使用 `userRequire.resolve` 并且需要它. 如果无法在本地文件系统中找到已解析的模块名称或路径,则错误带有 `MODULE_NOT_FOUND` 代码被丢弃.

-   `request` < string> - 要解决的模块名称或路径. 此参数是必需的, 且不能为空 .
-   `context` <Object> - 控制如何解决请求的命名参数. 所有被命名的参数都是可选的. **默认 :** `{}`。 。 。 .
    -   `base` < string> - 用来解决相对模块名称或路径的基础目录. 传入 `expandPath`,指定默认值 `~+`。 。 。 . **默认 :** `~+`。 。 。 .
    -   `cwd` < string> - 要用作工作目录而不是当前工作目录的绝对目录. 传入 `expandPath`,它将当前工作目录指定为默认值. **默认 :** `process.cwd()`。 。 。 .
    -   `dot` < 字符串 > - 用于替换主要点的目录( X)`.`) 模块名称或路径中的段. 传入 `expandPath`,指定默认值 `.`。 。 。 . **默认 :** `.`。 。 。 .
    -   `paths` < 字符串\[ \] > - 传递到 `require.resolve` 当指定了空模块名称时. 如果此参数为空, 则没有路径传递到 `require.resolve` (这意味着它使用内置路径). **默认 :** `[]`。 。 。 .
    -   `context.resolve` < 功能> - 用于解决模块名称或路径请求的解析函数. 内置默认值 `require.resolve` 函数. **默认 :** `require.resolve`。 。 。 .

```js
function userRequire.resolve (request[, context])
```

确定与指定上下文相关的模块名称或路径并返回. 如果无法在本地文件系统中找到已解析的模块名称或路径, 编码错误 `MODULE_NOT_FOUND` 被抛出.

见 `userRequire` 用于描述参数.

## 使用量

### 用户要求. resolve

这个 `userRequire.resolve` 函数返回一个系统依赖的路径. 在此显示使用Unix类操作系统时的结果 .

```js
const userRequire = require('@antora/user-require-helper')

// request is a path

userRequire.resolve('/foo/bar.js')
//=> /foo/bar.js

userRequire.resolve('~/foo/bar.js')
//=> $HOME/foo/bar.js

userRequire.resolve('foo/bar.js')
//=> $PWD/foo/bar.js

userRequire.resolve('foo/bar.js', { base: '/base/dir' })
//=> /base/dir/foo/bar.js

userRequire.resolve('./foo/bar.js')
//=> $PWD/foo/bar.js

userRequire.resolve('./foo/bar.js', { dot: '/dot/dir' })
//=> /dot/dir/foo/bar.js

userRequire.resolve('~+/foo/bar.js')
//=> $PWD/foo/bar.js

// request is a module name

userRequire.resolve('/path/to/node_modules/foo-bar')
//=> /path/to/node_modules/foo-bar/main.js

userRequire.resolve('foo-bar')
//=> /calling/script/dir/node_modules/foo-bar/main.js

userRequire.resolve('foo-bar', { paths: ['/other/dir'] })
//=> /other/dir/node_modules/foo-bar/main.js

userRequire.resolve('^:foo-bar')
//=> /calling/script/dir/node_modules/foo-bar/main.js

userRequire.resolve('^:foo-bar', { paths: ['/other/dir'] })
//=> /calling/script/dir/node_modules/foo-bar/main.js

userRequire.resolve(':foo-bar')
//=> $PWD/node_modules/foo-bar/main.js

userRequire.resolve(':foo-bar', { base: '/base/dir' })
//=> /base/dir/node_modules/foo-bar/main.js

userRequire.resolve('.:foo-bar')
//=> $PWD/node_modules/foo-bar/main.js

userRequire.resolve('.:foo-bar', { dot: '/dot/dir' })
//=> /dot/dir/node_modules/foo-bar/main.js

userRequire.resolve('./subdir:foo-bar', { dot: '/dot/dir' })
//=> /dot/dir/subdir/node_modules/foo-bar/main.js

userRequire.resolve('~+:foo-bar')
//=> $PWD/node_modules/foo-bar/main.js

userRequire.resolve('foo-bar.js/')
//=> /calling/script/dir/node_modules/foo-bar.js/main.js
```

### 用户要求

用途 `userRequire.resolve` 以解析路径,并通过要求返回该路径导出的对象.

```js
const userRequire = require('@antora/user-require-helper')

const exportedObject = userRequire('./foo/bar.js', { dot: '/dot/dir' })
```

## 版权和许可证

版权 (C) 2021年-由OpenDevise Inc. 和为Antora的个人贡献者所出.

该软件的使用按照下列规定进行: [Mozilla 公共许可版本 2.0](https://www.mozilla.org/en-US/MPL/2.0/) (MPL-2.0) (中文(简体) ).

## 常见问题

### @antora/user-require-helper 是什么？

在指定上下文中解析模块名称或路径的帮助函数并需要它\.

### 如何安装 @antora/user-require-helper？

在项目目录运行 npm install @antora/user-require-helper，或使用 pnpm add / yarn add / bun add。

### @antora/user-require-helper 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/antora\_\_user-require-helper 是否存在。

### @antora/user-require-helper 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @antora/user-require-helper 需要什么版本的 Node\.js？

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

### @antora/user-require-helper 可以商用吗？

@antora/user-require-helper 使用 MPL-2\.0 许可。弱 Copyleft：可以商用，也可以和闭源代码一起使用；但如果分发时修改了 MPL 授权的文件，这些文件的修改需以 MPL 开源。以上为概括，不构成法律意见，请以许可原文为准。

### @antora/user-require-helper 的下载量有多少？

根据 npm 官方下载统计，@antora/user-require-helper 在 2026/10/06 – 2026/11/04 这 30 天内被下载 181,946 次，日均约 6,065 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @antora/user-require-helper 还在维护吗？

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