Node.js 升级 HTTP 客户端后，如何回归验证代理行为

Node.js 升级代理 IP 行为变化，多不来自业务代码，而来自运行时、HTTP 客户端库或代理 agent 中某一层的默认值改变。回归时先把这三层分开，再按代理配置、连接复用、流式响应逐项验证。测试使用测试账号与自有出口，具体默认行为以对应版本文档为准。

这次升级改了 Node.js、客户端库还是代理组件？

三层各自管不同的事，混在一起就无法定位。

• 层级：Node.js 运行时 ｜ 常见改动：主版本升级 ｜ 影响范围：内置 fetch、TLS 默认值、DNS 解析顺序
• 层级：HTTP 客户端库 ｜ 常见改动：undici、axios、got 版本 ｜ 影响范围：重试、超时、重定向、连接池
• 层级：代理 agent ｜ 常见改动：proxy-agent、https-proxy-agent ｜ 影响范围：代理参数解析与转发方式

只升了库但运行时也变了，回归范围按运行时算，因为 TLS 与 DNS 行为会跟着变。

环境变量和 dispatcher 同时配置时，哪个生效？

同一进程里，代理可能来自环境变量、全局 dispatcher、请求级参数三处。

• HTTPS_PROXY / HTTP_PROXY：是否被读取、大小写写法如何影响，按具体 Node.js 与客户端版本核对；
• 全局 dispatcher：是否覆盖环境变量取决于实现与版本，需要实测；
• 请求级 dispatcher 或 agent：通常更靠前，但不构成跨客户端的统一优先级。

下面是待按版本验证的假设，不是通用结论。先写下实际使用的 Node.js、Undici、axios、got 版本，逐项核对对应文档，再用负向测试和实际出口确认。如果环境变量与显式配置同时存在，实际采用哪项取决于运行时和客户端实现。在隔离测试环境中可使用不可用代理做负向验证；若请求仍成功，还需排查绕过规则、其他代理配置或连接复用，并核对最终出口。

可用以下最小示例确认请求实际出口：

```js
import { ProxyAgent, fetch } from 'undici';

// PROXY_URL 由受限环境注入，不要写入真实凭据
const dispatcher = new ProxyAgent(process.env.PROXY_URL);
const res = await fetch('https://ipinfo.io/json', { dispatcher });
console.log(await res.json()); // 核对本次请求实际出口
```

代理凭据从权限受限的密钥管理器或环境变量注入，不要写进源码、shell history、进程参数或日志；确需认证时优先用客户端支持的认证接口，避免把 user:pass 拼进 URL。

分别测试全局 dispatcher 和请求级配置，并记录每种设置下的实际出口。结果不符合预期时，检查所用 Node.js、Undici 或客户端库版本及其配置优先级文档。

Android 应用网络栈接入代理后的定位思路，可参考Android App 网络栈测试怎么做？接入代理后异常定位。

不同代理配置组合要怎么逐项验证？

将常见配置组合放在同一矩阵中核对；以受控实测结果为准：

• 配置方式：仅环境变量 ｜ 待验证的默认行为：是否读取、大小写敏感性按版本而定 ｜ 怎么确认：记录变量来源、是否设置及脱敏主机/端口，再查实际出口
• 配置方式：全局 dispatcher ｜ 待验证的默认行为：是否覆盖环境变量取决于实现 ｜ 怎么确认：同时设两者，看出口 IP 跟谁走
• 配置方式：请求级 agent/dispatcher ｜ 待验证的默认行为：通常更靠前，但不保证 ｜ 怎么确认：在隔离环境用新进程分别连受控不可达代理和可用代理，比较出口与错误，并排查连接池、NO_PROXY 与 fallback
• 配置方式：显式代理参数 ｜ 待验证的默认行为：由具体库决定，认证与 SOCKS 支持不一 ｜ 怎么确认：用受控测试凭据验证握手；日志不得包含完整代理 URL 或认证值

按实际使用的 Node.js 与客户端版本逐行核对配置组合；认证和 SOCKS 能力以对应版本文档与受控实测为准。不要将完整代理 URL 或凭据写入日志。

怎么检查连接复用、HTTP/2 和 TLS 是否变化？

升级后这三项最容易出现“能通但变慢”。

三项都要按“固定条件—记录字段—与升级前比较—失败判据”检查：

• keep-alive：固定并发与请求数，记录新建连接数、复用比例和连接池上限；与升级前同负载对比，复用比例明显下降且时延同步上升，判为异常；
• HTTP/2：固定目标与 TLS 配置，记录协商到的协议和错误信息；非预期降级到 1.1 或协商失败，判为异常；
• TLS：固定目标与 SNI，记录协议版本、证书校验结果；握手失败或校验被放宽，判为异常。

记录相同负载下每个请求是否新建连接，并比较升级前后的复用比例和 TLS 握手情况。复用下降可能与连接池、服务端关闭连接或代理行为有关，需结合客户端日志进一步区分。阈值由团队基线设定，没有跨项目的通用数字。

需要补充网络与产品归因的对照思路，可参考多地区测试发现问题，如何判断是网络故障还是产品缺陷？。

怎么确认流式数据和超时行为正常？

如果应用依赖流式响应，应测量应用层事件，而不是只看最终文本。TCP/HTTP 读取块可能拆分或合并 SSE 事件；TTFB 与总时长也不能单独证明缓冲。

以下 curl 命令只作代理连接和 TTFB 辅助对照，-o /dev/null 会丢弃正文，不能测事件间隔：

```bash
curl -N --no-buffer -x "$PROXY_URL" \
-o /dev/null -w 'ttfb=%{time_starttransfer}\n' https://api.example.com/v1/stream
```

记录应用层首事件、后续事件间隔、总时长和错误类型，并与相同请求的升级前基线比较。PROXY_URL 从环境变量或密钥管理器读取，不要把凭据写入命令历史。无数据时长按接口心跳和 deadline 判断；重复异常时再区分客户端、代理和上游问题。

哪些结果能说明升级后的代理行为符合预期？

回归时按下表记录配置与观测结果，并和升级前基线比较：

• 检查项：代理优先级 ｜ 固定条件：同一请求、同一进程配置 ｜ 记录字段：配置来源、是否设置、脱敏主机/端口、绕过命中及实际出口 IP ｜ 失败判据：出口与预期配置不符且无法解释
• 检查项：连接复用 ｜ 固定条件：相同并发与请求数 ｜ 记录字段：新建与复用连接数、复用比例 ｜ 失败判据：复用比例明显低于升级前且时延上升
• 检查项：HTTP/2 ｜ 固定条件：相同目标与 TLS 配置 ｜ 记录字段：协商协议、错误信息 ｜ 失败判据：非预期降级或协商失败
• 检查项：TLS ｜ 固定条件：相同目标与 SNI ｜ 记录字段：协议版本、证书校验结果 ｜ 失败判据：校验被放宽或握手失败
• 检查项：流式响应 ｜ 固定条件：相同请求、心跳和 deadline ｜ 记录字段：首个应用事件、事件间隔、总时长、错误类型 ｜ 失败判据：与基线/接口契约不符且重复复现
• 检查项：超时 ｜ 固定条件：按客户端实际支持的超时类型与契约 ｜ 记录字段：触发阶段与错误类型 ｜ 失败判据：与该客户端支持范围及约定不符

出现不符合预期的结果时，回到对应配置行或观测项复查；需要归因时使用相同请求和网络条件重复对照。

Undici ProxyAgent 官方文档

FAQ

Q：设置了代理环境变量，所有 fetch 实现都会使用它吗？

A：不一定，行为取决于 Node.js 版本和客户端实现；应核对实际使用的 dispatcher 或代理配置。

Q：HTTP/2 测试失败就说明代理不支持 HTTP/2 吗？

A：不能直接判断，还需区分客户端能力、代理隧道方式和目标服务协商结果。

Q：升级后只在开发机通过是否足够？

A：还需核对部署环境的 Node.js 版本、环境变量和启动参数是否一致。