编译与运行指引（Windows）

前置条件

• 安装 Node.js（建议 18+，当前测试为 22.15.1），确保 node -v 与 npm -v 正常
• 安装 Python 3.x，并将 python 置于 PATH（示例：Python 3.10.11）
• 安装 Visual Studio Build Tools 2019/2022，选择“使用 C++ 的桌面开发”工作负载，包含最新 Windows SDK
• 如需指定 MSVC 版本：
  • 命令：npm config set msvs_version 2019 或设置环境变量 GYP_MSVS_VERSION=2019

项目结构要点

• 原生入口源码：addon.cc（项目根目录）
• 头文件目录：ffi/ 与 lib64/include/
• Windows 链接库：lib64/libcurl_imp.lib（仓库已内置）
• 构建产物位置：build/Release/curlcffi.node
• 配置文件：
  • binding.gyp
  • index.js

安装与编译

# 安装依赖（node-addon-api、node-gyp）
npm install

# 生成工程（VS 项目与配置）
npm run configure

# 编译（Release x64）
npm run build

成功后，产物位于：

d:\web\node-curl-im\node-curl-impersonate\build\Release\curlcffi.node

运行与验证

• index.js 在 Windows 会自动将 lib64 与 lib64/bin 追加到 PATH，以加载仓库内置的 DLL
• 快速验证（首次建议关闭证书校验以排查环境）：

node -e "const {get}=require('./index');get('https://example.com',{impersonate:'chrome',verify:false}).text().then(t=>{console.log('LEN',t.length);console.log(t.slice(0,120));}).catch(console.error)"

• TLS 指纹验证（BrowserLeaks）：

node -e "const {get}=require('./index');get('https://tls.browserleaks.com/json',{impersonate:'chrome'}).json().then(j=>{console.log(JSON.stringify(j,null,2));}).catch(console.error)"

伪装目标（impersonate）

• 通过 impersonate 选择目标，index.js 会进行映射与规范化，例如：
  • chrome → chrome142
  • edge → edge101
  • safari → safari2601
  • safari_ios → safari260_ios
  • chrome_android → chrome131_android
  • firefox → firefox144
  • tor → tor145

开启证书校验

• 将 verify 设为 true（默认即为 true），并设置 CA Bundle：
  • 环境变量：CURL_CA_BUNDLE 或 REQUESTS_CA_BUNDLE 指向有效的 cacert.pem
  • index.js 也会尝试查找 certifi 常见路径（可按需安装/放置）

常见问题排查

• ERR_DLOPEN_FAILED 或 “The specified procedure could not be found”：
  • 原因：运行时未正确加载本仓库自带的 DLL（PATH 未指向 lib64 与 lib64/bin）
  • 解决：使用 index.js 作为入口（其会自动设置 PATH）；或在启动前手动将上述目录前置到 PATH
• 源文件路径报错（找不到 addon.cc）：
  • 确认 binding.gyp 的 sources 为 addon.cc（项目根）
• MSBuild/SDK 相关错误：
  • 确认已安装 VS Build Tools 与 Windows SDK；必要时设置 msvs_version 后重新 configure/build
• 证书验证失败：
  • 先用 verify:false 验证网络与功能，再配置 CA Bundle 并启用校验
• 需要清理重编：
  • 删除 build/ 目录后重新执行 npm run configure 与 npm run build

跨平台说明（概览）

• macOS / Linux：
  • binding.gyp 中已配置 -lcurl-impersonate，需在系统中准备对应库与头文件
  • 步骤一致：npm install → npm run configure → npm run build
  • 运行前确保动态链接库可被系统加载（LD_LIBRARY_PATH / DYLD_LIBRARY_PATH 或系统安装路径）

目录引用

• 配置文件： binding.gyp
• 入口模块： index.js
• 产物示例： build/Release/curlcffi.node