[bug][http-proxy] 导出给子进程的 NO_PROXY 携带方括号条目 [::1],Python httpx 直接拒收整个变量(0.1.5-rc.1 复现)

[TT-Wang]

在 0.1.5-rc.1(上游 master 2377c272a8)上确认:harness 导出给子进程的 NO_PROXY 里带一个方括号条目 [::1],Python 的 httpx 会因此拒绝整个变量,于是任何用 trust_env=True 构造客户端的 Python 工具链在 harness 里直接抛错。

差异出现在哪一层很关键,我两边都量了:

进程	NO_PROXY
用户登录 shell	localhost,127.0.0.1,::1
harness 宿主进程自身	localhost,127.0.0.1,::1(原样继承,干净)
harness 用 bash 工具拉起的子进程	localhost,127.0.0.1,::1,[::1]

宿主自己的环境没问题,方括号是加在派生给子进程的那一份上的。这也是它难查的原因。

缺陷位置

packages/util/http-proxy/src/policy.ts:33

export const LOOPBACK_NO_PROXY: readonly string[] = ['localhost', '127.0.0.1', '::1', '[::1]']

紧邻的注释解释了理由,而且对 undici 是对的:undici 的匹配器会把裸 ::1 读成 host : port 1,所以必须同时列出带方括号的写法。问题不在这个常量本身,在于这份列表被原样导出成了通用环境变量。

导出点在 install.ts:262-278 的 proxyEnvironmentForChild(),关键是 :271-272:

const named = field !== 'noProxy' && names.some(name => inherited[name] !== undefined)
for (const name of names) overlay[name] = named ? inherited[name] : resolved

对 httpProxy / httpsProxy,用户写了什么子进程就拿什么;但对 noProxy,named 恒为 false,子进程永远拿派生值。这正好解释了宿主与子进程为什么不一致。

policy.ts:250 的注释也表明导出是有意的:「The bypass list carries LOOPBACK_NO_PROXY for the consumers that read an environment rather than a policy」。但 NO_PROXY 是所有语言的 HTTP 栈都会读的变量,方括号属于 URL authority 语法,不属于 no_proxy 条目。

复现

宿主侧,在设了 HTTP_PROXY 的 shell 里起 dsh web,会话里用 bash 工具跑:

node -e 'console.log(JSON.stringify(process.env.NO_PROXY))'

得到 "localhost,127.0.0.1,::1,[::1]"。

客户端侧(httpx 0.28.1 / CPython 3.12):

import os, httpx
for k in ("HTTP_PROXY","HTTPS_PROXY","http_proxy","https_proxy"): os.environ.pop(k, None)
for v in ["localhost,127.0.0.1,::1", "localhost,127.0.0.1,::1,[::1]"]:
    os.environ["no_proxy"] = v; os.environ["NO_PROXY"] = v
    try:
        httpx.Client(trust_env=True).close(); print(f"{v!r:42} -> OK")
    except Exception as e:
        print(f"{v!r:42} -> {type(e).__name__}: {e}")

'localhost,127.0.0.1,::1'                  -> OK
'localhost,127.0.0.1,::1,[::1]'            -> InvalidURL: Invalid port: ':1]'

版本核对

npm latest 的 0.1.3-alpha.2、alpha 的 0.1.5-alpha.2、next 的 0.1.5-rc.1,policy.ts:33 三者一致。git diff dsh-v0.1.5-alpha.1 2377c272a8 -- packages/util/http-proxy/ 只动了 README 和 package.json,policy.ts 与 install.ts 都没进 diff。该文件最近一次改动是 93bba8ef67(2026-09-02,关于 NODE_USE_ENV_PROXY),与本问题无关。

实际代价

一个在 harness 里于 Python 仓库工作的 agent 加载不了 sentence-transformers 模型:huggingface_hub 用 trust_env=True,Hub 路径死在方括号条目上,本地缓存又未命中,报错是

(Hub path: Invalid port: ':1]'; local cache: We couldn't connect to 'https://huggingface.co' ...)

表象是「目标仓库的模型加载坏了」,报错里没有任何东西指向 harness。

建议修法

进程内给 undici 消费的策略保留 [::1],但在 proxyEnvironmentForChild() 导出的副本上把方括号规范化掉(或不导出该条目)。同一个文件里已经有正确写法:isLoopbackHost()(policy.ts:257-258)自己匹配时就会剥方括号——

const host = hostname.replace(/^\[|\]$/g, '').replace(/\.$/, '').toLowerCase()

所以仓库已经知道方括号该剥,只是导出到环境的那一份漏了。另外 install.ts:246 自己写着「Node 的 NO_PROXY 规则……与本包不同」,而导出的环境变量正是这个差异不再是内部实现细节的地方。

想问维护者一句:导出副本做规范化(剥方括号)和干脆不把 [::1] 放进导出列表,哪个更符合你们对 proxyEnvironmentForChild 的定位?前者对只认裸 ::1 的客户端更友好,后者改动面更小。

[argszero]

@TT-Wang 这份报告的根因定位是对的，我在 2377c272a8 上逐条复现了。补三个能决定修法的机制事实，并标出一处需要更正的地方。

一、复现确认（httpx 0.28.1 / CPython 3.13.9）

[::1] 让 httpx 在构造期就抛，不是请求期：

httpx.InvalidURL: Invalid port: ':1]'
  File "httpx/_client.py", line 698, in __init__
    URLPattern(key): None
  File "httpx/_utils.py", line 172, in __init__
    url = URL(pattern)

即 httpx 把每个 no_proxy 条目当 URL 解析，[::1] 进 urlparse 后 port 取到 :1]。

范围收窄一点：不是「Python 全都坏」。实测三种客户端：

客户端	...,::1	...,::1,[::1]
httpx 0.28.1	OK	InvalidURL（构造期致命）
requests 2.34.2（should_bypass_proxies）	OK	OK
stdlib urllib.request.proxy_bypass	OK	OK

所以受害面精确地是「把 NO_PROXY 条目按 URL authority 语法解析」的客户端，httpx 是典型。你那条 huggingface_hub 报错正是 httpx 形状（Hub path: Invalid port: ':1]'），吻合。

二、导出的两条路径（其中一条与你的表不同）

方括号来自 policy.ts:33：

export const LOOPBACK_NO_PROXY = ['localhost', '127.0.0.1', '::1', '[::1]']

policy.ts:210 的 withLoopback() 把它合进 policy.noProxy。之后有两个出口，不止子进程那个：

1. 子进程（你引的那处）：install.ts:267-272 proxyEnvironmentForChild()。你对 named 恒为 false 的判断正确 —— noProxy 永远拿派生值。
2. 宿主进程自身：install.ts:79-92 applyPolicyEnv() 把 policy.noProxy 写进 process.env（经 writeProxyEnv），在第一个插件挂载前执行。

所以你表里的第一行需要更正：localhost,127.0.0.1,::1（干净）那一行，比的应该是 dsh 启动之前的登录 shell；harness 进程自己的 process.env.NO_PROXY 拿到的同样是 ...,::1,[::1]。

这不只是表格问题，它扩大了影响面：在 harness 进程内跑的 Python（而不只是派生的子进程）也会读到带方括号的值。唯一不受影响的是宿主自己的 fetch —— applyPolicyEnv 只写 HTTP(S)_PROXY / NO_PROXY，不写 NODE_USE_ENV_PROXY，所以宿主 Node 不读这些变量（它走自定义 undici dispatcher）。

三、决定修法的一件事：方括号不能直接删

这是本报告最关键、也最容易修错的地方。[::1] 不是给 harness 自己的匹配器用的 —— 仓库自己的测试就证明裸 ::1 足够（policy.spec.ts:193-195：bypassesProxy('::1', new URL('http://[::1]:3000/a')) 为 true；policy.ts:281 匹配前两侧都去方括号）。

它唯一的载荷点是「子进程里 Node 原生 fetch 读环境变量」这条通道。 用 NODE_USE_ENV_PROXY=1（正是 proxyEnvironmentForChild 给子进程加的那个 flag）实测，Node 26.5.0：

子进程 NO_PROXY	结果（访问绑在 [::1] 上的服务）
localhost,127.0.0.1,::1	被代理（连到死端口 → ECONNREFUSED）
localhost,127.0.0.1,::1,[::1]	直连

原因 = Node 26.5.0 内置 undici 为 8.7.0，其 #parseNoProxy 只有这条无方括号感知的规则：

const parsed = entry.match(/^(.+):(\d+)$/)   // [::1] 不匹配；::1 被拆成 host ":" port 1

即 policy.ts:30-31 注释描述的现象仍然成立，只是不在你们自己的依赖里：npm 上 undici 8.10.0（仓库 pin 的是 ^8.10.0）已加了剥方括号处理（entry.replace(/^\[(.+)\]$/, '$1')），所以 harness 的 dispatcher 与 bypassesProxy 都不需要它；但 Node 自身捆绑的 undici 还没升上去。

于是现状两头都真：

• 删掉方括号 → Python 好了，子进程里 Node 原生 fetch 的 IPv6 回环绕过坏掉；
• 留着 → Node 好了，httpx 类客户端构造即崩。

我验过有没有两边都接受的写法（0:0:0:0:0:0:0:1、[0:0:0:0:0:0:0:1]、::1,* 等）：Node 只认带方括号形态，Python 只认不带 —— 没有交集。

四、我认为根因在「通道选择」而非那一行常量

install.ts:255-261 的注释写了一句很关键的话：「Non-Node children (curl, git, pnpm) ignore the flag and read the variables themselves」。作者已经按「每个消费者各自怎么读」推理了 —— 但漏了一半：非 Node 子进程确实忽略 flag，可它们读同一个变量，而方括号是给 Node 的 undici 解析器打的补丁。

一个解析器版本相关的补丁，放在所有语言共用的 NO_PROXY 里，就必然要选一个赢家。可行方向（供参考，取舍在你们）：

1. 只在子进程是 Node 时补 [::1] —— 但 scrubbedParentEnv() 不知道消费者是谁，需要新的调用点参数；
2. 统一导出不带方括号，接受 Node 原生 fetch 失去 IPv6 回环绕过（localhost / 127.0.0.1 仍在），等 undici 升版后再收紧；
3. 靠上游：Node 把捆绑 undici 升到 ≥8.10.0 后该补丁整体可删。

顺带：policy.ts:250 注释以「those are four literal entries」自安，但这条理由只覆盖 harness 自己的 matcher，不覆盖环境变量的外部读者。

五、插件可挂载面判定（本轮扫描结论）

我按惯例查了能否以插件形态兜：

• SubprocessRuntime 是抽象 Service（subprocess/src/index.ts:115），spawn() 收 SubprocessSpawnSpec，其 env 是在 scrubbedParentEnv() 之后合并的显式层 —— 所以包装 spawn 的插件理论上能改掉子进程那一份 NO_PROXY。
• 但：① 宿主自己的 process.env 由 applyPolicyEnv 写入，不经过这个 seam，插件改不到；② 改法与第三点同病 —— 要么牺牲 Node fetch、要么牺牲 Python，插件无法作出比 core 更好的选择；③ 替换能力 provider 在本仓库是组合期选择（fs-local vs fs-sandbox 是「用这个代替那个」，不是叠加），不属于插件该做的事。

判定：缺口在 core 面（util/http-proxy 的导出策略），插件是下游受害者 —— 已归档 upstream-fix 候选，本轮不提议插件。

---

以上每条都标了测法与版本，方便复核；需要的话我可以把三份复现脚本（httpx / Node 原生 fetch / undici 版本矩阵）贴上来。