# @brightsec/node-libcurl 中文文档

规范地址：https://npmcn.com/package/%40brightsec/node-libcurl/

版本：5\.1\.6
npm 元数据更新时间：2026-10-06T21:25:15.394Z
中文译文更新时间：2026-11-08T15:45:26.493Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40brightsec/node-libcurl
原文对照：https://npmcn.com/package/%40brightsec/node-libcurl/?lang=original
项目主页：https://github.com/NeuraLegion/node-libcurl
源码仓库：https://github.com/NeuraLegion/node-libcurl

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

- 包体积（解压后）：1.3 MB，358 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.14
- 运行依赖：7 个
- 首次发布：2026-05-15T17:24:08.857Z
- 最新版本发布：2026-10-06T21:25:15.030Z
- 近 30 天下载量：1914（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：23（近 12 个月 23 个）

## 中文简介

对 Node.js 最快的 http 客户端( 以及更多) - 对 libcurl 绑定的 Node.js

## 安装

```sh
npm install @brightsec/node-libcurl
```

也可以使用：`pnpm add @brightsec/node-libcurl`、`yarn add @brightsec/node-libcurl`、`bun add @brightsec/node-libcurl`

## README

# 节点- libcurl

[![Buy Me A Coffee](https://cdn.buymeacoffee.com/buttons/v2/default-black.png)](https://www.buymeacoffee.com/jonathancardoso)  
[![Patreon Logo](https://c5.patreon.com/external/logo/become_a_patron_button@2x.png)](https://www.patreon.com/bePatron?u=19985213 "Become a Patreon")  
[![Discord Logo](https://i.imgur.com/DlKeNmn.png)](https://discord.io/jonathancardoso "Join our Discord Server")

[![NPM version](https://img.shields.io/npm/v/node-libcurl.svg?style=flat-square)](https://www.npmjs.org/package/node-libcurl) [![license](https://img.shields.io/npm/l/node-libcurl?style=flat-square)](https://raw.githubusercontent.com/JCMais/node-libcurl/develop/LICENSE)

[![AppVeyor CI Status](https://ci.appveyor.com/api/projects/status/u7ox641jyb6hxrkt/branch/master?svg=true)](https://ci.appveyor.com/project/JCMais/node-libcurl)

> 这个 [快点](https://npmcn.com/package/%40brightsec/node-libcurl/#readme-benchmarks) 用于 Node.js 的特性丰富的 URL 传输库.

[利布尔](https://github.com/bagder/curl) node.js. libcurl 的正式描述:

> libcurl是一个自由而易于使用的客户端URL传输库,支持DICT,FILE,FTP,FTPS,Gopher,HTTP,HTTPS,IMAP,IMAP,IMAP,LDAP,POP3,POP3S,RTMP,RTSP,SCP,SFTP,SMTP,SMTPS,Telnet和TFTP. libcurl支持SSL证书,HTTP POST,HTTP PUT,FTP上传,基于HTTP格式的上传,代理,cookie,用户+password认证(Basic, Digest, NTLM, Negotiate, Kerberos),文件传输恢复,http代理隧道等!

-   [快速启动](https://npmcn.com/package/%40brightsec/node-libcurl/#readme-quick-start)
    -   [安装](https://npmcn.com/package/%40brightsec/node-libcurl/#readme-install)
    -   [简单请求 - Async / 使用卷轴等待](https://npmcn.com/package/%40brightsec/node-libcurl/#readme-simple-request---async--await-using-curly)
    -   [简单请求 - 使用 Curl 类](https://npmcn.com/package/%40brightsec/node-libcurl/#readme-simple-request---using-curl-class)
    -   [设置 HTTP 信头](https://npmcn.com/package/%40brightsec/node-libcurl/#readme-setting-http-headers)
    -   [格式提交(Content-Type:应用程序/x-www-form-urlencoded)](https://npmcn.com/package/%40brightsec/node-libcurl/#readme-form-submission-content-type-applicationx-www-form-urlencoded)
    -   [多部分上传 / HttpPost libcurl 选项( Content- Type: 多部分/ 形式数据)](https://npmcn.com/package/%40brightsec/node-libcurl/#readme-multipart-upload--httppost-libcurl-option-content-type-multipartform-data)
    -   [二进制数据](https://npmcn.com/package/%40brightsec/node-libcurl/#readme-binary-data)
-   [SSL 服务器](https://npmcn.com/package/%40brightsec/node-libcurl/#readme-ssl)
-   [API 密码](https://npmcn.com/package/%40brightsec/node-libcurl/#readme-api)
-   [特别说明](https://npmcn.com/package/%40brightsec/node-libcurl/#readme-special-notes)
    -   [`READFUNCTION` 选项](https://npmcn.com/package/%40brightsec/node-libcurl/#readme-readfunction-option)
-   [共同问题](https://npmcn.com/package/%40brightsec/node-libcurl/#readme-common-issues)
-   [基准](https://npmcn.com/package/%40brightsec/node-libcurl/#readme-benchmarks)
-   [警卫](https://npmcn.com/package/%40brightsec/node-libcurl/#readme-security)
-   [支持的 Libcurl 版本](https://npmcn.com/package/%40brightsec/node-libcurl/#readme-supported-libcurl-versions)
-   [企业](https://npmcn.com/package/%40brightsec/node-libcurl/#readme-for-enterprise)
-   [详细安装](https://npmcn.com/package/%40brightsec/node-libcurl/#readme-detailed-installation)
    -   [关于预建二进制/ 直接安装的重要注释](https://npmcn.com/package/%40brightsec/node-libcurl/#readme-important-notes-on-prebuilt-binaries--direct-installation)
        -   [缺少软件包](https://npmcn.com/package/%40brightsec/node-libcurl/#readme-missing-packages)
    -   [电子/NW.js](https://npmcn.com/package/%40brightsec/node-libcurl/#readme-electron--nwjs)
        -   [NW.js(高级节点-webkit)](https://npmcn.com/package/%40brightsec/node-libcurl/#readme-nwjs-aka-node-webkit)
        -   [电子( aka 原子壳)](https://npmcn.com/package/%40brightsec/node-libcurl/#readme-electron-aka-atom-shell)
    -   [以 Linux 为基础](https://npmcn.com/package/%40brightsec/node-libcurl/#readme-building-on-linux)
    -   [建立在 macOS 上](https://npmcn.com/package/%40brightsec/node-libcurl/#readme-building-on-macos)
        -   [Xcode 10 macOS 莫哈韦](https://npmcn.com/package/%40brightsec/node-libcurl/#readme-xcode--10--macos--mojave)
    -   [以视窗为基础](https://npmcn.com/package/%40brightsec/node-libcurl/#readme-building-on-windows)
        -   [关于已过时的节点-gyp版本的说明](https://npmcn.com/package/%40brightsec/node-libcurl/#readme-note-on-outdated-node-gyp-version)
-   [获取帮助](https://npmcn.com/package/%40brightsec/node-libcurl/#readme-getting-help)
-   [捐款](https://npmcn.com/package/%40brightsec/node-libcurl/#readme-contributing)
-   [捐赠/帕特里昂](https://npmcn.com/package/%40brightsec/node-libcurl/#readme-donations--patreon)

## 快速启动

> **说明**数字 :
> 
> -   此库不能用于浏览器, 取决于本地代码 .

### 安装

```shell
npm i node-libcurl --save
```

或者说

```shell
pnpm i node-libcurl --save
```

或者说

```shell
yarn add node-libcurl
```

### 简单请求 - Async / 使用卷轴等待

> 此 API 是实验性的, 在没有大版本突起的情况下可更改

```javascript
const { curly } = require('node-libcurl');

const { statusCode, data, headers } = await curly.get('https://www.google.com')
```

任何选项都可以使用 `FULLNAME` 或一个 `lowerPascalCase` 格式 :

```javascript
const querystring = require('querystring');
const { curly } = require('node-libcurl');

const { statusCode, data, headers } = await curly.post('https://httpbin.com/post', {
  postFields: querystring.stringify({
    field: 'value',
  }),
  // can use `postFields` or `POSTFIELDS`
})
```

JSON Post的例子:

```javascript
const { curly } = require('node-libcurl')
const { data } = await curly.post('https://httpbin.com/post', {
  postFields: JSON.stringify({ field: 'value' }),
  httpHeader: [
    'Content-Type: application/json',
    'Accept: application/json'
  ],
})

console.log(data)
```

### 简单请求 - 使用 Curl 类

```javascript
const { Curl } = require('node-libcurl');

const curl = new Curl();

curl.setOpt('URL', 'www.google.com');
curl.setOpt('FOLLOWLOCATION', true);

curl.on('end', function (statusCode, data, headers) {
  console.info(statusCode);
  console.info('---');
  console.info(data.length);
  console.info('---');
  console.info(this.getInfo( 'TOTAL_TIME'));
  
  this.close();
});

curl.on('error', curl.close.bind(curl));
curl.perform();
```

### 设置 HTTP 信头

通过指定信头的字符串阵列

```javascript
curl.setOpt(Curl.option.HTTPHEADER,
  ['Content-Type: application/x-amz-json-1.1'])
```

### 格式提交(Content-Type:应用程序/x-www-form-urlencoded)

```javascript
const querystring = require('querystring');
const { Curl } = require('node-libcurl');

const curl = new Curl();
const close = curl.close.bind(curl);

curl.setOpt(Curl.option.URL, '127.0.0.1/upload');
curl.setOpt(Curl.option.POST, true)
curl.setOpt(Curl.option.POSTFIELDS, querystring.stringify({
  field: 'value',
}));

curl.on('end', close);
curl.on('error', close);
```

### 多部分上传 / HttpPost libcurl 选项( Content- Type: 多部分/ 形式数据)

```javascript
const { Curl } = require('node-libcurl');

const curl = new Curl();
const close = curl.close.bind(curl);

curl.setOpt(Curl.option.URL, '127.0.0.1/upload.php');
curl.setOpt(Curl.option.HTTPPOST, [
    { name: 'input-name', file: '/file/path', type: 'text/html' },
    { name: 'input-name2', contents: 'field-contents' }
]);

curl.on('end', close);
curl.on('error', close);
```

### 二进制数据

当请求二进制数据时,请确保完成其中之一:

-   自己传 `WRITEFUNCTION` (单位:千美元)[https://curl.haxx.se/libcurl/c/ CURLOPT WRITEF CONUTION.html 互联网档案馆的存檔,存档日期2014-12-21](https://curl.haxx.se/libcurl/c/CURLOPT_WRITEFUNCTION.html):

```javascript
curl.setOpt('WRITEFUNCTION', (buffer, size, nmemb) => {
  // something
})
```

-   启用以下旗帜之一 :

```javascript
curl.enable(CurlFeature.NoDataParsing)
// or
curl.enable(CurlFeature.Raw)
```

背后的推理是,默认 `Curl` 实例将尝试将收到的数据和信头解码为 utf8 字符串, 如下所示: [https://github.com/JCMais/node-libcurl/blob/b55b13529c9d11fdcdd7959137d8030b39427800/lib/Curl.ts#L391](https://github.com/JCMais/node-libcurl/blob/b55b13529c9d11fdcdd7959137d8030b39427800/lib/Curl.ts#L391)

更多实例请检查 [示例文件夹](https://npmcn.com/package/%40brightsec/node-libcurl/examples)。 。 。 .

## SSL 服务器

## API 密码

最新稳定版本的 API 文档可在 [https://node-libcurl-docs.netlify.app/modules/ (中文(简体) )_lib 索引_.html (中文(简体) )](https://node-libcurl-docs.netlify.app/modules/_lib_index_.html)。 。 。 .

开发分支文件,可在 [https://develop--node-libcurl-docs.netlify.app/modules/ 互联网档案馆的存檔,存档日期2014-12-22_lib 索引_.html (中文(简体) )](https://develop--node-libcurl-docs.netlify.app/modules/_lib_index_.html)。 。 。 .

此库提供了 Typescript 类型定义.

几乎所有 [CURL 选项](https://curl.haxx.se/libcurl/c/curl_easy_setopt.html) 将被支持,如果您通过一个非错误,则将出现错误.

更多使用示例请检查 [示例文件夹](https://npmcn.com/package/%40brightsec/node-libcurl/examples)。 。 。 .

## 特别说明

### `READFUNCTION` 选项

缓冲器作为第一个参数传递到带有 [`READFUNCTION`](https://curl.haxx.se/libcurl/c/CURLOPT_READFUNCTION.html) 选项的初始化时, libcurl在上传缓冲器中使用的大小( 可以用 [`UPLOAD_BUFFERSIZE`](https://curl.haxx.se/libcurl/c/CURLOPT_UPLOAD_BUFFERSIZE.html)),使用 `node::Buffer::Data(buf);` 基本上与 `Buffer#allocUnsafe` 因此,它对于其正确使用具有各种影响: [https://nodejs.org/pt-br/docs/guides/buffer-conbusctor-deprencation/#提及-buffer-allocunsafe 互联网档案馆的存檔,存档日期2013-12-12](https://nodejs.org/pt-br/docs/guides/buffer-constructor-deprecation/#regarding-buffer-allocunsafe)

所以,小心点,一定要回来 **没错** 您已在此调用中写入缓冲器的数据量 。 只有这个具体数额将被复制并移交给libcurl.

## 共同问题

见 [(原始内容存档于2019-09-29) (英语). Common ISSUES.md](https://npmcn.com/package/%40brightsec/node-libcurl/COMMON_ISSUES.md)

## 基准

见 [./基准](https://npmcn.com/package/%40brightsec/node-libcurl/benchmark)

## 警卫

见 [警卫](https://npmcn.com/package/%40brightsec/node-libcurl/SECURITY.md)

## 支持的 Libcurl 版本

附加词仅针对 libcurl 版本进行测试 `7.81.0` 和最新的一个.

代码本身仅用于编译版本大于或等于 `7.81.0`,任何小于此的 libcurl 版本 **没有** 已支持.

7.81.0版本于2022年1月5日发售,是和Ubuntu 22.04一起发运的版本. 从那时起,Libcurl上已经有超过5541个bug修复.

## 企业

`node-libcurl` 现作为本报告的一部分提供 [潮汐订阅](https://tidelift.com/subscription/pkg/npm-node-libcurl?utm_source=npm-node-libcurl&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)。 。 。 .

节点-libcurl和其他上千个软件包的维护者与Tidelift合作,为您用于构建应用程序的开源依赖提供商业支持和维护. 节省时间,降低风险,改善代码健康,同时向维护者支付使用的确切依赖性. [学多取.](https://tidelift.com/subscription/pkg/npm-node-libcurl?utm_source=npm-node-libcurl&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)

## 详细安装

此软件包的最新版本有预建二进制( 感谢 [节点前显示](https://github.com/mapbox/node-pre-gyp/)(中文(简体) ) 可用于:

-   节点.js:活动 LTS + 当前版本的最新两个版本(参见 [https://github.com/nodejs/放行 (英语)](https://github.com/nodejs/Release)(中文(简体) )
-   电子:最新2个主要版本

并在以下平台:

-   Linux 64 比特 & ARM64 & Alpine( 穆斯尔, 64比特)
-   macOS 64 位 (英特尔) & ARM64 (M1+)
-   窗口 64 位元

安装中 `yarn add node-libcurl` 或者说 `npm install node-libcurl` 如果下载预建的二进制,则不需要编译。 然而,如果你试图安装 `nw.js` 或者说 `electron` 需要更多的步骤,请检查下方的相应部分.

预建的二进制是静态构建的,其库有以下版本,特征和协议(图书馆版本可能在Node.js版本之间更改):

```
Version: libcurl/8.17.0 OpenSSL/3.5.2 zlib/1.3.1 brotli/1.1.0 zstd/1.5.7 libidn2/2.1.1 libssh2/1.10.0 nghttp2/1.66.0 ngtcp2/1.17.0 nghttp3/1.12.0 OpenLDAP/2.6.9
Protocols: dict, file, ftp, ftps, gopher, gophers, http, https, imap, imaps, ldap, ldaps, mqtt, pop3, pop3s, rtsp, scp, sftp, smb, smbs, smtp, smtps, telnet, tftp, ws, wss
Features: AsynchDNS, IDN, IPv6, Largefile, NTLM, SSL, libz, brotli, TLS-SRP, HTTP2, UnixSockets, HTTPS-proxy, alt-svc
```

如果没有与您的系统相匹配的预建二进制可用,或者安装失败,那么您需要一个能够编译节点.js addons的环境,这意味着:

-   [p 3.x](https://www.python.org/downloads/) 已安装
-   更新了 C++ 编译器,能够编译 C++17 (Electron QQ v32的 C++20).

如果您不想使用预建的二进制, 即使它在您的系统上有效, 您可以在安装时通过一面旗帜 :

> 与 `npm`

```sh
npm install node-libcurl --build-from-source
```

> 与 `yarn`

```sh
npm_config_build_from_source=true yarn add node-libcurl
```

### 关于预建二进制/ 直接安装的重要注释

> 这些笔记在Windows上建设时不重要

预建的二进制与 `brotli`, (中文(简体) ), `libidn2`, (中文(简体) ), `libssh2`, (中文(简体) ), `openLDAP`, (中文(简体) ), `OpenSSL` `nghttp2`, (中文(简体) ), `zstd` 财务报告和审定财务报表 `zlib`。 。 。 .

这个 `brotli`, (中文(简体) ), `nghttp2`, (中文(简体) ), `OpenSSL` 财务报告和审定财务报表 `zlib` 版本 **必须** 与 Node.js 使用的版本相匹配,这对通过混合不同版本的库符号来避免任何可能的问题是必要的,因为 Node.js 也导出其去向的一些符号.

如果您要用上面提到的库来构建加词, 您必须确定它们的版本是ABI 兼容一个节点. js 使用的, 否则您很可能会撞上分块断层 .

如果你想自己构建一个静态链接的加通版本,就需要通过 `curl_static_build=true` 调用安装时的旗帜.

> 如果使用 `npm`数字 :

```sh
npm install node-libcurl --build-from-source --curl_static_build=true
```

> 如果使用 `yarn` 或者说 `pnpm`数字 :

```sh
npm_config_build_from_source=true npm_config_curl_static_build=true yarn/pnpm add node-libcurl
```

构建过程将使用 `curl-config` 在路径中可用,如果您想要将它覆盖到您的 libcurl 安装之一, 您可以设置 `curl_config_bin` 变量,如上文提到的 `curl_static_build`。 。 。 .

如果你不想用的话 `curl-config`,您可以通过两个额外的变量来控制构建过程:

-   `curl_include_dirs` 要搜索信头文件的分隔目录列表
-   `curl_libraries` 空格分隔的要传递到链接的旗帜列表

#### 缺少软件包

静态链接版本目前不支持 `GSS-API`, (中文(简体) ), `SPNEGO`, (中文(简体) ), `KERBEROS`, (中文(简体) ), `RTMP`, (中文(简体) ), `Metalink`, (中文(简体) ), `PSL` 财务报告和审定财务报表 `Alt-svc`。 。 。 .

用于构建 Kerberos 的脚本存在于 `./scripts/ci` 文件夹,但删除的原因有两个:

-   如果和海姆达尔一起建造,加通就会变得太大
-   如果与麻省理工学院Kerberos共同建造,加通将受到他们的许可条件的约束.

### 电子/NW.js

如果建造一个 `Electron` 或者说 `NW.js` 您需要通过安装命令的额外参数.

如果您不想使用预建的二进制, 请通过 `npm_config_build_from_source=true` 编号 : `--build-from-source` 旗到安装命令.

#### NW.js(高级节点-webkit)

在NW.js上从源头开始建设,您首先需要确保您在全球安装了 nw-gyp: `yarn global add nw-gyp` 或者说 `npm i -g nw-gyp` 或者说 `pnpm i -g nw-gyp`

> 如果在 Windows 上, 您还需要添加步骤, 当前可用的 win delay load hook.cc 上 `nw-gyp` 无法使用此加词, 因此必须应用补丁 。 该补丁可见于 `./scripts/ci/patches/win_delay_load_hook.cc.patch`,并且应当应用到文件 `<nw-gyp-folder>/src/win_delay_load_hook.cc`。 。 。 .

然后说:

> 线条

```
npm_config_runtime=node-webkit npm_config_target=0.38.2 yarn add node-libcurl
```

> 无

```bash
npm install node-libcurl --runtime=node-webkit --target=0.38.2 --save
```

地点 `--target` 是您当前使用的 NW.js 版本

#### 电子( aka 原子壳)

> 线条

```bash
npm_config_runtime=electron npm_config_target=X.Y.Z npm_config_disturl=https://www.electronjs.org/headers yarn add node-libcurl
```

> 无

```bash
npm install node-libcurl --runtime=electron --target=X.Y.Z --disturl=https://www.electronjs.org/headers --save
```

何处 `--target` 是您正在使用的电子版本, 在我们的情况中, 我们只是使用 本地安装返回的版本 `electron` 二进制.

您也可以将这些参数放入.npmrc文件中,比如:

```bash
runtime = electron
target = 5.0.1
target_arch = x64
dist_url = https://atom.io/download/atom-shell
```

### 以 Linux 为基础

要在基于linux的系统上构建加词,您必须具备:

-   页:1
-   libcurl dev 文件
-   蟒蛇 >= 3
-   操作系统没有超过他们的EOL.

如果你是在一个基于Debian的系统, 你可以通过运行来得到这些:

```bash
sudo apt-get install python libcurl4-openssl-dev build-essential
```

如果您不想使用 libcurl 版本与您的系统一起运出, 由于它可能非常老化, 你可以安装 libcurl 从源, `curl_config_bin`。 。 。 .

如果您需要一些实例来检查 CI 配置文件( I)[`.travis.yml`](https://npmcn.com/package/%40brightsec/node-libcurl/.travis.yml), (中文(简体) ), [`.circleci/config.yml`](https://npmcn.com/package/%40brightsec/node-libcurl/.circleci/config.yml))和 [`scripts/ci/`](https://npmcn.com/package/%40brightsec/node-libcurl/scripts/ci) 文件夹.

### 建立在 macOS 上

在macOS上,你必须:

-   马克OS QQ 13(索诺马语)
-   Xcode 命令行工具

您可以检查是否有 Xcode 命令行工具运行 :

```sh
xcode-select -p
```

它应该返回他们的路径,如果它不返回, 你必须通过运行安装它:

```sh
xcode-select --install
```

#### Xcode 10 macOS 莫哈韦

以防您从源头安装加词出错, 您正在使用 macOS 版本 QQ Mojave, 请检查您是否收到以下错误 :

```
  CXX(target) Release/obj.target/node_libcurl/src/node_libcurl.o
  clang: error: no such file or directory: '/usr/include'
```

如果是这样的话,这是因为命令行工具的最新版本没有添加 `/usr/include` 默认文件夹。 检查 [Xcode 10 发布注释](https://developer.apple.com/documentation/xcode_release_notes/xcode_10_release_notes#3035624) 详细情况.

这个 `/usr/include` 现可上网查阅 `$(xcrun --show-sdk-path)/usr/include`。要正确构建 libcurl ,您需要将路径传递到 `npm_config_curl_include_dirs` 环境变量 :

```
npm_config_curl_include_dirs="$(xcrun --show-sdk-path)/usr/include" yarn add node-libcurl
```

#### 土生土长

既然这样的话

```
error: use of undeclared identifier 'curl_ws_start_frame'; did you mean 'curl_ws_frame'?
```

这意味着你的系统正在使用macOS SDK的libcurl头条,这些头条已经过时(版本在8.16下方,需要WebSocket支持).

您必须使用 `curl` 通过Homebrew安装,您可以使用以下步骤来确保系统接取Homebrew `curl` 从源头建起时头/ libs .

1.  安装 `curl` 和Homebrew(如果你还没有):

```bash
brew install curl
```

2.  添加本乡人 `curl` 因此,构建工具可以找到信头、库和 `curl-config`数字 :

```zsh
export PATH="$(brew --prefix curl)/bin:$PATH" # optional

export CPPFLAGS="-I$(brew --prefix curl)/include"
export LDFLAGS="-L$(brew --prefix curl)/lib"
export PKG_CONFIG_PATH="$(brew --prefix curl)/lib/pkgconfig"
```

注:在Intel macs上,Homebrew通常安装在以下 `/usr/local` 和苹果硅 `/opt/homebrew`。使用 `$(brew --prefix curl)` 是两个架构中最便携的选项.

3.  构建安装( S) `node-libcurl` 从源.

可选: 删除先前安装的本地副本 `node-libcurl` 首先要确保清洁的建筑:

```zsh
# remove previously installed copy (local environment only)
rm -rf node_modules/node-libcurl
```

然后从源而起. 根据您的 macOS Xcode/ CLT 版本, 您可能还需要指出 SDK 的 `/usr/include` 目录 :

如果您喜欢明确使用 Homebrew 安装 `curl` 信头而非 SDK 包含路径, 您可以使用 :

```zsh
npm_config_curl_include_dirs="$(brew --prefix curl)/include" npm_config_curl_libraries="-L$(brew --prefix curl)/lib -lcurl" npm install node-libcurl --build-from-source
```

或者,如果你想使用 SDK 包含路径 :

```zsh
# build & install
npm_config_curl_include_dirs="$(xcrun --show-sdk-path)/usr/include" npm install node-libcurl --build-from-source
```

这应该可以让你的机器用Homebrew来建造附加装置 `curl` 安装.

### 以视窗为基础

如果使用预建的二进制安装, 您只需要拥有该二进制 [视觉 c++ 2017 运行时库](https://visualstudio.microsoft.com/downloads/#microsoft-visual-c-redistributable-for-visual-studio-2017)。 。 。 .

如果从源头建造,你必须:

-   Py 3.x
-   [Visual Studio QQ 2019 (英语)](https://visualstudio.microsoft.com/downloads/) (启用 Clang/LLVM 支持, 请见下项)
-   [视觉工作室的 Clang/LLVM 支持](https://learn.microsoft.com/en-us/cpp/build/clang-support-msbuild?view=msvc-170)
-   [鼻音](https://www.nasm.us/)

Python 3.x和Visual Studio编译器可以通过运行来安装:

```sh
npm install --global --production windows-build-tools
```

`nasm` 可从上述链接的网站或使用巧克力获取:

```
choco install nasm
```

目前没有支持使用其他libcurl版本,仅次于该版本 [卷曲为窗口](https://github.com/JCMais/curl-for-windows) 子模块 (帮助添加此功能).

关于在Windows上构建加词的重要说明是,我们必须用包含在标题文件中的"hack"来做一些 `node-gyp`编号 :`nw-gyp`。原因是因为我们正在使用一个独立的OpenSSL版本,我们不想使用由Node.js提供的OpenSSL头条,默认是添加到 `<nw-gyp-or-node-gyp-folder>/include/node/openssl`,所以我们要做的是,在编译之前,文件夹将被重新命名为 `openssl.disabled`。成功安装后,文件夹将重新命名为原名, **不过** 如果在编译过程中发生任何错误, 文件夹将保留重命名, 直到编译成功 。 提供更多信息,说明为何需要这样做,并可在问题上找到一些背景 [164号](https://github.com/JCMais/node-libcurl/issues/164)。 。 。 .

#### 关于已过时的节点-gyp版本的说明

国家预防机制有自己的内部版本: `node-gyp`,可能不是最新版本。 如果您看到这样的输出 :

```
[info] it worked if it ends with ok
[info] using node-pre-gyp@2.0.0
[info] using node@24.9.0 | win32 | x64 
gyp info it worked if it ends with ok
gyp info using node-gyp@10.1.0
gyp info using node@24.9.0 | win32 | x64
gyp info ok 
gyp info it worked if it ends with ok
gyp info using node-gyp@10.1.0
gyp info using node@24.9.0 | win32 | x64
```

节点- gyp 版本在哪里 `10.1.0`你可能会面临与ClangCL这样的问题:

```
C:\Users\internal\AppData\Local\node\corepack\v1\pnpm\9.9.0\dist\node_modules\node-gyp\src\win_delay_load_hook.cc(37,9): warning : unknown pragma ignored [-Wunknown-pragmas] [F:\jc\node-libcurl\build\deps\
curl-for-windows\libcurl.vcxproj]
  /LTCG:INCREMENTAL: no such file or directory
D:\Software\Microsoft Visual Studio\2019\Community\MSBuild\Microsoft\VC\v160\Microsoft.CppCommon.targets(1522,5): error MSB6006: "llvm-lib.exe" exited with code 1. [F:\jc\node-libcurl\build\deps\curl-fo
r-windows\libcurl.vcxproj]
C:\Users\internal\AppData\Local\node\corepack\v1\pnpm\9.9.0\dist\node_modules\node-gyp\src\win_delay_load_hook.cc(12,9): warning : unknown pragma ignored [-Wunknown-pragmas] [F:\jc\node-libcurl\build\deps\
curl-for-windows\brotli\brotli.vcxproj]
C:\Users\internal\AppData\Local\node\corepack\v1\pnpm\9.9.0\dist\node_modules\node-gyp\src\win_delay_load_hook.cc(37,9): warning : unknown pragma ignored [-Wunknown-pragmas] [F:\jc\node-libcurl\build\deps\
curl-for-windows\brotli\brotli.vcxproj]
  /LTCG:INCREMENTAL: no such file or directory
D:\Software\Microsoft Visual Studio\2019\Community\MSBuild\Microsoft\VC\v160\Microsoft.CppCommon.targets(1522,5): error MSB6006: "llvm-lib.exe" exited with code 1. [F:\jc\node-libcurl\build\deps\curl-fo
r-windows\brotli\brotli.vcxproj]
```

唯一的解决方案是安装全球可用的节点-gyp版本:

```powershell
npm install --global node-gyp@latest
```

然后通过设置 `npm_config_node_gyp` 环境变量( 假设电源) :

```powershell
$globalNodeGypPath = Join-Path (npm prefix -g) "node_modules\node-gyp\bin\node-gyp.js"
$env:npm_config_node_gyp=$globalNodeGypPath
pnpm install node-libcurl
```

## 获取帮助

如果您的问题与加词或用法直接相关,您可以通过以下方式获得帮助:

-   张贴一个问题在 `stack-overflow` 并使用 `node-libcurl` 标签.
-   [加入我们的 Discord 服务器](https://discord.gg/3vacxRY) 把你的问题发过去.

## 捐款

读取 [捐款额](https://npmcn.com/package/%40brightsec/node-libcurl/CONTRIBUTING.md)

## 捐赠/帕特里昂

有人问我是否有办法支持我的工作, 我为此创建了Patreon网页: [https://www.patreon.com/jonathancardoso (英语)](https://www.patreon.com/jonathancardoso)

如果您想通过 PayPal 捐赠, 请使用我的 GitHub 配置文件中可用的同样电子邮件 : [https://github.com/JCMais 页面存档备份,存于互联网档案馆](https://github.com/JCMais)

谢谢你读到这里

_最初这个加词是基于来自 [相声/正声](https://github.com/jiangmiao/node-curl),事物已经改变,大多数甚至所有代码都被重写._

## 常见问题

### @brightsec/node-libcurl 是什么？

对 Node\.js 最快的 http 客户端\( 以及更多\) - 对 libcurl 绑定的 Node\.js

### 如何安装 @brightsec/node-libcurl？

在项目目录运行 npm install @brightsec/node-libcurl，或使用 pnpm add / yarn add / bun add。

### @brightsec/node-libcurl 支持 TypeScript 吗？

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

### @brightsec/node-libcurl 支持 ESM 还是 CommonJS？

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

### @brightsec/node-libcurl 需要什么版本的 Node\.js？

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

### @brightsec/node-libcurl 可以商用吗？

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

### @brightsec/node-libcurl 的下载量有多少？

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

### @brightsec/node-libcurl 还在维护吗？

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