跳到主要内容

Node.js 报 UNABLE_TO_VERIFY_LEAF_SIGNATURE?从根因到修复的完整排查指南

在 Node.js 里看到 UNABLE_TO_VERIFY_LEAF_SIGNATURE,本质是 OpenSSL 的 X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE(verify error num=21):Node 拿到了服务器证书,但没法沿着证书链把它追溯到一个自己信任的根证书。实际排查下来,绝大多数情况是服务端漏发中间证书,其余是私有 CA 或本地信任库的问题。本文按「先定位、再治本、最后兜底」的顺序,给出可以直接复制的命令和配置。

一、先看清错误:它在说什么

典型堆栈长这样:

Error: unable to verify the first certificate
    at TLSSocket.onConnectSecure (node:_tls_wrap:1530:34)
    at TLSSocket.emit (node:events:390:28)
    at TLSSocket._finishInit (node:_tls_wrap:874:8)
  code: 'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
  reason: 'unable to verify the first certificate',
  host: 'api.example.com'

三个关键点:

  • code 和 message 不是一回事。code 是 OpenSSL 的 X509_V_ERR 常量,message 是 unable to verify the first certificate。搜索时两个都值得试。
  • leaf / first 指的是服务器自己的那张证书,不是中间证书。所以问题一定出在「从这张证书往上追不到可信根」这一步。
  • 它和证书过期、域名不匹配是不同错误。那两种情况分别报 CERT_HAS_EXPIRED、ERR_TLS_CERT_ALTNAME_INVALID。看到 LEAF_SIGNATURE,先查证书链,不用先查域名。

二、根因清单:按出现频率排序

  1. 服务端只发了叶子证书,没发中间证书(最常见)。Let’s Encrypt、ZeroSSL 等签发的 cert.pem 只含叶子证书,Web 服务器必须配 fullchain.pem。
  2. 私有 CA / 自签名证书。Node 内置信任库自然不认识企业自建的根。
  3. Node 版本太旧。内置 CA 列表里没有新根(如 ISRG Root X1、部分政企根),升级 Node 或手动注入即可。
  4. 证书链顺序错误,或 fullchain 里混进了不相关的证书。
  5. 企业代理 / 杀毒软件做 TLS 中间人,用自己的根证书重签流量,客户端不信任该根。
  6. SNI 缺失。多域名共用 IP,客户端没发 SNI 时服务端返回默认站点的证书链。

一个高频困惑:浏览器和 curl 都正常,只有 Node 报错。原因是浏览器(以及 Windows CryptoAPI、部分 curl 构建)会依据证书里的 AIA 扩展自动下载中间证书,而 Node/OpenSSL 默认不会。所以「浏览器能打开」不能证明证书链完整。

三、三条命令定位问题(先别改代码)

命令 1:看服务端到底发了什么链。

openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts </dev/null

正常输出里 Certificate chain 段应有 2~3 个条目。如果只有 0 s:... 一条,并伴随下面这样的报错,根因就确认了——中间证书缺失:

CONNECTED(00000003)
depth=0 CN = api.example.com
verify error:num=20:unable to get local issuer certificate
verify return:1
depth=0 CN = api.example.com
verify error:num=21:unable to verify the first certificate
verify return:1
---
Certificate chain
 0 s:CN = api.example.com
   i:C=US, O=Let's Encrypt, CN = R3
---

命令 2:数一下链上有几张证书。

openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts </dev/null 2>/dev/null | grep -c 'BEGIN CERTIFICATE'

公网证书一般返回 2 或 3。返回 1 就是缺中间证书。

命令 3:用本地信任库显式验证一遍。

openssl s_client -connect api.example.com:443 -servername api.example.com -CAfile /etc/ssl/certs/ca-certificates.crt </dev/null 2>&1 | grep -E 'Verify return code|verify error'

期望结果是 Verify return code: 0 (ok)。若为 21 或 20,问题在服务端证书链;若为 19 (self-signed certificate in certificate chain),说明链里出现了不受信任的自签根,多半是私有 CA 或代理。

最后用 Node 复现一次,排除业务代码干扰:

node -e "require('https').get('https://api.example.com', r => { console.log('status', r.statusCode); process.exit(0) }).on('error', e => { console.error(e.code, '-', e.message); process.exit(1) })"

四、治本:服务端补全中间证书

这是唯一能同时修好所有客户端(Node、Java、Python、移动端、IoT 设备)的方案。核心只有一句话:把 cert.pem 换成 fullchain.pem。

Nginx:

server {
    listen 443 ssl;
    server_name api.example.com;

    ssl_certificate     /etc/letsencrypt/live/api.example.com/fullchain.pem;  # 不是 cert.pem
    ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;
}

Apache 2.4.8+:

SSLCertificateFile    /etc/letsencrypt/live/api.example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/api.example.com/privkey.pem

Node 自建 HTTPS 服务:

const fs = require('fs');
const https = require('https');

https.createServer({
  key:  fs.readFileSync('/etc/ssl/private/privkey.pem'),
  cert: fs.readFileSync('/etc/ssl/certs/fullchain.pem') // 关键:必须是 fullchain
}, app).listen(443);

当 CA 只给了两个文件时,手工拼接:

cat cert.pem intermediate.pem > fullchain.pem

顺序必须是「叶子证书 → 中间证书(→ 可选根证书)」。顺序错了,部分客户端会报同样的错。

验证拼接顺序是否正确:

openssl crl2pkcs7 -nocrl -certfile fullchain.pem | openssl pkcs7 -print_certs -noout

输出应形如:

subject=CN = api.example.com
issuer=C = US, O = Let's Encrypt, CN = R3

subject=C = US, O = Let's Encrypt, CN = R3
issuer=C = US, O = Internet Security Research Group, CN = ISRG Root X1

每一张的 issuer 必须等于下一张的 subject,对不上就是链断了。改完重载:nginx -t && nginx -s reload 或 systemctl reload apache2,再用第三节命令 2 确认证书数从 1 变成 2 或 3。

五、私有 CA / 企业内网:让 Node 信任你的根

如果第三节命令 2 返回 2~3 张、链是完整的,但链顶端是自家根证书,就需要让 Node 认识它。

方式 A:环境变量(推荐,零代码改动)

NODE_EXTRA_CA_CERTS=/etc/ssl/certs/corp-root-ca.pem node server.js
  • Node 7.3.0 起支持,追加到内置 CA 列表,不替换原有信任库。
  • 文件必须是 PEM 格式,可包含多张证书(根证书和中间证书一起放也行)。
  • 只在进程启动时读取一次,运行期改文件无效,必须重启进程。
  • 路径写错不会让进程退出,只会打印警告:Warning: Ignoring extra certs from /etc/ssl/certs/corp-root-ca.pem, load failed: error:02001002:system library:fopen:No such file or directory。看到这条先查路径和读权限。
  • Docker:docker run -e NODE_EXTRA_CA_CERTS=/certs/root.pem -v $PWD/root.pem:/certs/root.pem:ro my-app
  • Kubernetes:把证书挂进 ConfigMap 或 Secret,再在 Deployment 里注入同名 env。
  • npm 也读这个变量;若只是 npm 安装依赖失败,还可以执行 npm config set cafile /etc/ssl/certs/corp-root-ca.pem。

方式 B:在代码里指定 ca

const https = require('https');
const tls = require('tls');
const fs = require('fs');

const extra = fs.readFileSync('/etc/ssl/certs/corp-root-ca.pem', 'utf8');

const agent = new https.Agent({
  ca: [...tls.rootCertificates, extra] // ca 会覆盖默认信任库,必须显式合并
});

https.get('https://internal.example.com/health', { agent }, (res) => {
  console.log(res.statusCode);
});

最容易踩的坑:ca 选项是替换默认 CA 而不是追加。只传自家根证书,访问公网 HTTPS 就会集体失败。要么合并 tls.rootCertificates,要么干脆用环境变量。

不同 HTTP 客户端要分别处理:

  • axios:axios.get(url, { httpsAgent: agent })
  • node-fetch v2:fetch(url, { agent })
  • 原生 fetch / undici(Node 18+):不认 https.Agent,需要 setGlobalDispatcher(new Agent({ connect: { ca } }))

六、方案对比:选哪一个

方案 适用场景 作用范围 安全性 是否改代码
服务端补全 fullchain 公网证书、链不完整 所有客户端 最高,治本 否
NODE_EXTRA_CA_CERTS 私有 CA、企业根、代理 整个 Node 进程 高 否
https.Agent 的 ca 选项 只信任单个内部服务 指定请求 高 是
把根证书装进系统库 + –use-system-ca 企业统一管控的机器 整个进程 高 否
rejectUnauthorized: false 仅本地临时调试 指定请求 无,禁用校验 是
NODE_TLS_REJECT_UNAUTHORIZED=0 仅本地临时调试 整个进程 无,禁用校验 否

关于最后两项:它们会关闭证书校验,等于把中间人攻击的门打开,生产环境严禁。而且 Node 会打印显眼警告:Warning: Setting the NODE_TLS_REJECT_UNAUTHORIZED environment variable to '0' makes TLS connections and HTTPS requests insecure by disabling certificate verification. 看到这条警告出现在生产日志里,就应该当作故障处理。

七、常见报错对照与排查清单

报错 / err.code 含义 下一步
unable to verify the first certificate
UNABLE_TO_VERIFY_LEAF_SIGNATURE
链断了,追不到可信根 服务端补中间证书
self signed certificate in certificate chain
SELF_SIGNED_CERT_IN_CHAIN
链中出现自签根(私有 CA 或代理) 用 NODE_EXTRA_CA_CERTS 注入该根
DEPTH_ZERO_SELF_SIGNED_CERT 叶子证书本身就是自签的 换成正式证书,或注入该自签证书
unable to get local issuer certificate
UNABLE_TO_GET_ISSUER_CERT_LOCALLY
本地缺根或缺中间证书 同上,先查服务端链再查本地信任库
CERT_HAS_EXPIRED 证书过期 续期并重载服务
ERR_TLS_CERT_ALTNAME_INVALID 域名与 SAN 不匹配 改用证书里列出的域名,或重签证书
ERR_SSL_TLSV1_ALERT_UNKNOWN_CA 客户端与服务端信任锚不一致 核对双向 TLS 的 CA 配置

排查顺序建议:

  1. 用命令 2 数证书数,先排除「中间证书缺失」这个占比最高的原因。
  2. 用命令 1 看链顶是谁。链顶是知名公共 CA 却仍报错,就是 Node 版本旧或本地信任库不全。
  3. 链顶是陌生名字,基本可判定为私有 CA 或企业代理,走第五节。
  4. 确认证书有效期和 SAN,排除过期与域名不匹配。
  5. 检查是否有 HTTP(S)_PROXY 环境变量把请求劫持到了代理。
  6. 检查代码里是否有人偷偷设置了 ca、rejectUnauthorized,或用 undici 绕过了 agent。

八、FAQ

Q1:为什么浏览器和 curl 都正常,只有 Node 报错?

因为浏览器和部分系统 TLS 栈会通过证书的 AIA 扩展自动下载中间证书,Node/OpenSSL 默认不做这件事。服务端链不完整时,它们能自行补齐,Node 补不上,于是报 UNABLE_TO_VERIFY_LEAF_SIGNATURE。

Q2:设置了 NODE_EXTRA_CA_CERTS 却没生效?

依次检查:变量是否在启动 Node 的那个 shell 或容器里(env | grep NODE_EXTRA);路径是否为绝对路径且进程可读;文件是否为 PEM 且首行是 -----BEGIN CERTIFICATE-----;日志里有没有 Ignoring extra certs 警告;以及进程是否在设置变量之前就启动了。

Q3:能不能直接用 NODE_TLS_REJECT_UNAUTHORIZED=0 绕过?

只能用于本地临时验证。它关闭了整个进程的证书校验,所有 HTTPS 请求都会失去中间人防护,生产环境严禁使用。

Q4:中间证书从哪里获取?

Let’s Encrypt 的 chain.pem 或 fullchain.pem 就在 /etc/letsencrypt/live/域名/ 下;商业 CA 一般会在签发邮件或控制台提供「CA Bundle」「Intermediate Certificate」下载;也可以用 openssl s_client -showcerts 从其他配置正确的站点导出。

Q5:fullchain 里要不要放根证书?

通常不需要。客户端本地已有根证书,多发一张只会增加握手体积;而且部分客户端会对链中出现自签根给出警告。放叶子证书和中间证书即可。

Q6:为什么同一个接口,axios 能通、原生 fetch 不通?

Node 18+ 的原生 fetch 基于 undici,不走 https.Agent。要通过 setGlobalDispatcher(new Agent({ connect: { ca } })) 配置,或者统一改用 NODE_EXTRA_CA_CERTS 环境变量。

Q7:升级 Node 能解决吗?

只有在「证书链完整、链顶是公共根、但 Node 内置 CA 列表太旧」的情况下才有效。多数场景根因在服务端,升级 Node 并不能修好。Node 22.9+ 提供了 --use-system-ca 启动参数,可以直接复用操作系统信任库,适合企业统一管控的环境。