NodeJS 22.x升级后Octokit出现TLS错误但原生Fetch正常

问题概述 #

将NodeJS从16.x升级到22.x后，使用Octokit调用GitHub API出现TLS连接错误，但原生Fetch请求相同接口、相同代理配置可正常工作，错误信息为：

RequestError [HttpError]: Client network socket disconnected before secure TLS connection was established
  <stack_trace>
  status: 500,

可能原因 #

1. Octokit v5代理配置逻辑差异：Octokit v5默认基于Node.js原生fetch实现，但代理配置的处理逻辑和直接使用fetch略有不同，手动传递request.agent可能未被正确应用。
2. https-proxy-agent版本兼容性：旧版本的https-proxy-agent（如7.0.6）对NodeJS 22.x的原生fetch支持不足，导致代理连接时TLS协商失败。
3. NodeJS 22.x默认TLS配置变更：NodeJS 22.x默认禁用了较旧的TLS版本（如TLS 1.0/1.1），若企业代理仅支持这些旧版本，会触发连接断开。

解决方案 #

方案1：使用Octokit官方代理插件（推荐） #

Octokit提供的@octokit/plugin-proxy插件专门处理代理配置，比手动设置agent更可靠：

1. 安装插件：

npm install @octokit/plugin-proxy

2. 修改Octokit初始化逻辑：

const { Octokit } = require("octokit");
const { proxy } = require("@octokit/plugin-proxy");

// 加载代理插件
const OctokitWithProxy = Octokit.plugin(proxy);

async function main(argv) {
  process.env["NODE_TLS_REJECT_UNAUTHORIZED"] = 0;
  
  const token = process.env["AUTH_TOKEN"];
  const testProxy = process.env["HTTPS_PROXY"];

  // ... 保留Test #1的fetch代码 ...

  // TEST #2: 使用带代理插件的Octokit
  const testGithubClient = new OctokitWithProxy({
    auth: token,
    proxy: testProxy // 直接传入代理URL，插件自动处理agent和TLS配置
  });
  const test2response = await testGithubClient.rest.repos.get({
    owner: "<my org>",
    repo: "<my repo>",
  });
  console.log(`Response #2: [${JSON.stringify(test2response.data)}]`);
}

方案2：升级https-proxy-agent并调整TLS配置 #

若不想使用插件，可升级https-proxy-agent至兼容NodeJS 22.x的版本，并手动指定TLS协议：

1. 升级依赖：

npm install https-proxy-agent@latest

2. 修改代理Agent创建代码：

const { HttpsProxyAgent } = require("https-proxy-agent");

async function main(argv) {
  process.env["NODE_TLS_REJECT_UNAUTHORIZED"] = 0;
  
  const token = process.env["AUTH_TOKEN"];
  const testProxy = process.env["HTTPS_PROXY"];

  // 配置兼容企业代理的TLS协议
  const testProxyAgent = new HttpsProxyAgent(testProxy, {
    secureProtocol: "TLSv1_2_method", // 根据代理支持的版本调整
    minVersion: "TLSv1.2"
  });

  // ... 保留Test #1的代码 ...

  // TEST #2: 使用调整后的Agent
  const testGithubClient = new Octokit({
    auth: token,
    request: {
      agent: testProxyAgent,
    },
  });
  // ... 后续请求代码不变 ...
}

方案3：验证代理URL格式 #

确保HTTPS_PROXY环境变量的URL格式正确，需包含完整协议（如http://proxy.example.com:8080或https://proxy.example.com:8443），避免遗漏协议导致Agent初始化失败。

验证说明 #

• 方案1是官方推荐的代理配置方式，能自动适配不同NodeJS版本的fetch实现，兼容性最优。
• 方案2适合需要自定义TLS参数的场景，需根据企业代理的实际TLS支持情况调整协议版本。

内容的提问来源于stack exchange，提问作者Ben