跳到主要内容

Node.js SELF_SIGNED_CERT_IN_CHAIN 排查指南:代理根证书、fullchain 与 npm cafile

在 Node.js 里看到 SELF_SIGNED_CERT_IN_CHAIN,几乎总是同一个原因:证书链的某一环是自签名证书,而 Node 不信任它。麻烦在于它有三个来源完全不同的成因——站点自己签的证书、公司网络里的 TLS 检查代理、以及服务端把证书链拼错了——三者的修法互相冲突,用错方案会掩盖真实问题。下面按「先定位来源、再对症修复」的顺序给出可直接复制的命令。

一、错误含义:Node 为什么比浏览器更挑剔

Node 的 TLS 校验使用内置的 Mozilla CA 列表,默认不读取操作系统的钥匙串。这就是最常见的困惑来源:代理根证书被 IT 装进了系统信任库,浏览器和 curl 都正常,只有 Node 报错——因为它根本没看那里。

校验器沿着 leaf → intermediate → root 向上走,一旦发现某张证书的 issuer 等于它自己的 subject(自签),且不在信任列表里,就抛出:

Error: self signed certificate in certificate chain
    at TLSSocket.onConnectSecure (node:_tls_wrap:1674:34)
    at TLSSocket.emit (node:events:518:28)
    at TLSSocket._finishInit (node:_tls_wrap:1070:8) {
  code: 'SELF_SIGNED_CERT_IN_CHAIN'
}

注意区分 DEPTH_ZERO_SELF_SIGNED_CERT:那是叶子证书本身就是自签的(本地开发常见),而 SELF_SIGNED_CERT_IN_CHAIN 是链中间混进了自签证书(代理常见)。两者的排查方向不同。

二、五分钟定位:是谁在替换证书

第一步,换网络。用手机热点重跑同一条命令。热点下正常、公司网内报错,基本可锁定企业代理或防火墙的 TLS 检查。

第二步,看证书链的 issuer。

openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts </dev/null 2>/dev/null | grep -E '^ *[is]:'

正常站点会看到公共 CA,例如 i:C = US, O = Let's Encrypt, CN = R3。如果出现 i:CN = Corp TLS Inspection CA、O = Zscaler、O = Netskope、O = Palo Alto Networks 之类的名字,就是代理在中间签发了自己的证书。

第三步,用 Node 复现并拿到 code。

node -e 'require("https").get("https://api.example.com", r => console.log("OK", r.statusCode)).on("error", e => console.log(e.code, "-", e.message))'

若 curl -vI https://api.example.com 显示 SSL certificate verify ok,而上面这行报 SELF_SIGNED_CERT_IN_CHAIN,说明系统信任库里有代理根、Node 没有——直接跳到场景 A。

三、场景 A:企业 TLS 检查代理(最常见)

代理用一张自签根证书现场签发目标站点的证书,链路变成 代理根(自签)→ 目标站点。修法是让 Node 显式信任这张根证书。

1. 从链上导出证书,最后一张通常是代理根。

mkdir -p /tmp/chain && cd /tmp/chain
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts </dev/null 2>/dev/null | awk '/BEGIN CERTIFICATE/{c++; f="cert" c ".pem"} f{print > f} /END CERTIFICATE/{f=""}'
ls -1 cert*.pem
openssl x509 -in cert2.pem -noout -subject -issuer -dates

2. 确认它是自签的(subject 与 issuer 完全一致),然后放到一个稳定路径:

sudo cp cert2.pem /usr/local/share/ca-certificates/corp-tls-inspection-ca.crt
sudo update-ca-certificates     # Debian/Ubuntu;RHEL 系用 update-ca-trust

3. 让 Node 指向它,并重启进程。

export NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/corp-tls-inspection-ca.crt
node -e 'require("https").get("https://api.example.com", r => console.log("OK", r.statusCode)).on("error", e => console.log(e.code, e.message))'

几个必须知道的细节:

  • 文件必须是 PEM 格式;可以一个文件里拼多张证书(cat a.pem b.pem > bundle.pem),但环境变量只能指向一个路径。
  • Node 只在进程启动时读取一次,改完环境变量必须重启 node / npm / 构建脚本。
  • 用绝对路径。systemd、Docker、K8s、Jenkins agent 都不会继承你终端里的 export。
  • 文件不存在、为空或不可读时,Node 只打一条警告然后继续跑,很容易误判为「设了没用」:
    Warning: Ignoring extra certs from `/etc/ssl/certs/corp-ca.pem`, as the file could not be read: ENOENT: no such file or directory
    Warning: Ignoring extra certs from `/etc/ssl/certs/corp-ca.pem`, as the file is empty
  • 不要用 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.

四、场景 B:服务端证书链配错

如果你是被访问的一方(报错来自用户、监控探活或下游 CI),问题在证书链本身。两条铁律:

  • 只部署 fullchain(叶子证书 + 中间证书),绝不要把自签根证书拼进去。
  • 根证书应由客户端信任库提供。服务端多发一张自签根,除了让链变长、触发 SELF_SIGNED_CERT_IN_CHAIN,没有任何好处。

检查实际发出的链:

openssl s_client -connect www.example.com:443 -servername www.example.com -showcerts </dev/null 2>/dev/null | grep -E '^ *[is]:'
openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt fullchain.pem
# RHEL / CentOS 的 bundle 路径:/etc/pki/tls/certs/ca-bundle.crt

nginx 正确写法(指向 fullchain,而不是只含叶子的 cert.pem):

ssl_certificate     /etc/nginx/ssl/fullchain.pem;
ssl_certificate_key /etc/nginx/ssl/privkey.pem;

三种典型症状:只发叶子证书 → 客户端报 UNABLE_TO_GET_ISSUER_CERT_LOCALLY;把自签根也拼进 fullchain → 报 SELF_SIGNED_CERT_IN_CHAIN;中间证书顺序颠倒 → 浏览器可能容忍,Java 和旧版客户端直接失败。

五、场景 C:npm、yarn、pnpm 与 CI 环境

npm 本身是 Node 进程,NODE_EXTRA_CA_CERTS 对它同样有效;但它还有一套独立的 cafile 配置。两套都要对,否则会出现「npm 装包好了,构建脚本里的 node 还报错」。

npm config get cafile
npm config get strict-ssl
npm config get registry

典型报错:

npm ERR! code SELF_SIGNED_CERT_IN_CHAIN
npm ERR! errno SELF_SIGNED_CERT_IN_CHAIN
npm ERR! request to https://registry.npmjs.org/@scope/pkg failed, reason: self signed certificate in certificate chain

推荐修法(前两条),第三条只在完全可控的内网临时排障时使用:

# 1) 让 npm 信任代理根
npm config set cafile /usr/local/share/ca-certificates/corp-tls-inspection-ca.crt

# 2) 让 npm 派生出的 node 子进程也信任
export NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/corp-tls-inspection-ca.crt

# 3) 不推荐:关闭 npm 的证书校验
# npm config set strict-ssl false

写进 ~/.npmrc 时注意 cafile 是绝对路径,不要把带本机路径的配置提交进仓库:

# ~/.npmrc
cafile=/usr/local/share/ca-certificates/corp-tls-inspection-ca.crt
registry=https://registry.npmjs.org/

yarn 与 pnpm 同理:

yarn config get cafile
yarn config set cafile /usr/local/share/ca-certificates/corp-tls-inspection-ca.crt
pnpm config set cafile /usr/local/share/ca-certificates/corp-tls-inspection-ca.crt

容器与 CI 里没有你的 shell 环境,必须显式注入:

# Dockerfile
COPY corp-tls-inspection-ca.crt /usr/local/share/ca-certificates/corp-ca.crt
RUN update-ca-certificates
ENV NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/corp-ca.crt
# GitHub Actions
- name: Trust corporate CA
  run: echo "$CORP_CA_PEM" > "$RUNNER_TEMP/corp-ca.pem"
- name: Install
  run: npm ci
  env:
    NODE_EXTRA_CA_CERTS: ${{ runner.temp }}/corp-ca.pem

六、方案对比:哪种修法适合你的场景

方案 适用场景 配置方式 生效范围 风险
NODE_EXTRA_CA_CERTS=/path/ca.pem 代理拦截、私有 CA 环境变量 当前进程及其子进程 低,首选
npm config set cafile 仅 npm 安装 npm 配置 npm 自身 低
npm config set strict-ssl false 临时排障 npm 配置 npm 自身 高,关闭校验
NODE_TLS_REJECT_UNAUTHORIZED=0 不要用于 CI / 生产 环境变量 所有 TLS 连接与子进程 极高,全面失防
服务端只部署 fullchain 你是服务提供方 nginx / Apache 配置 所有客户端 无,属正确做法
update-ca-certificates curl、浏览器、Java、git 系统信任库 系统级程序 Node 默认不读,需配合方案 1
node --use-system-ca / NODE_USE_SYSTEM_CA=1 较新 Node 想直接复用系统库 启动参数 / 环境变量 该进程 实验性,注意版本差异
new https.Agent({ ca }) 只放行单个请求 代码内 单个请求 低,粒度最细

说明:--use-system-ca 与 NODE_USE_SYSTEM_CA=1 在 Node 22.15+ / 23.4+ 提供,仍属实验性,升级前请以官方文档为准。只放行单个请求的写法:

const https = require("node:https");
const fs = require("node:fs");
const ca = fs.readFileSync("/usr/local/share/ca-certificates/corp-ca.crt");
https.get("https://internal.example.com", { ca }, (res) => console.log(res.statusCode));

七、真实报错逐条对照

报错 / code 含义 处理
self signed certificate in certificate chain / SELF_SIGNED_CERT_IN_CHAIN 链中存在自签证书且不受信任 代理场景设 NODE_EXTRA_CA_CERTS;服务端场景从 fullchain 移除自签根
DEPTH_ZERO_SELF_SIGNED_CERT 叶子证书本身自签(depth 0) 用 mkcert 生成并信任,或对该请求传 ca
UNABLE_TO_VERIFY_LEAF_SIGNATURE 服务器只发了叶子证书,缺中间证书 部署 fullchain.pem
UNABLE_TO_GET_ISSUER_CERT_LOCALLY 本地找不到签发者证书 补齐中间证书或客户端 CA
CERT_HAS_EXPIRED 证书已过期 续期;代理场景检查代理自身证书
ERR_TLS_CERT_ALTNAME_INVALID / hostname/IP does not match certificate's altnames SAN 与访问域名不匹配 检查 SNI、访问域名与证书 SAN 列表
error:0A000086:SSL routines::certificate verify failed OpenSSL 层校验失败 用 s_client -showcerts 看链,定位是哪一环断了
npm ERR! code SELF_SIGNED_CERT_IN_CHAIN npm 未信任代理根 npm config set cafile + NODE_EXTRA_CA_CERTS

另一种常见错位:裸 node 正常、npm 报错。这往往不是证书问题,而是 npm 走了代理:

npm config get proxy
npm config get https-proxy
env | grep -i _proxy

如果代理地址已失效,npm 会连到错误的主机,返回的证书自然对不上,报错信息却仍然是 SELF_SIGNED_CERT_IN_CHAIN,很容易被误判。

八、FAQ

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

因为 Node 用内置 Mozilla CA 列表,默认不读系统信任库。IT 把代理根装进系统钥匙串只解决了 curl、浏览器、Java,Node 需要额外的 NODE_EXTRA_CA_CERTS。较新版本可用 --use-system-ca 改变这个行为。

NODE_EXTRA_CA_CERTS 能指向多个文件吗?

只能指向一个路径,但该文件可以是拼接了多张 PEM 证书的 bundle:cat a.pem b.pem > bundle.pem,然后指向 bundle。

设置了环境变量还是报同样的错?

按顺序查:① 是否重启了进程(值只在启动时读取);② 路径是否为绝对路径且文件可读;③ 日志里是否出现 Warning: Ignoring extra certs from ...;④ 导出的到底是不是链上那张自签根(对比 subject/issuer);⑤ 报错是否其实来自 npm 的 cafile 而非 Node 本身。

需要把证书装进系统信任库吗?

对 Node 不是必需的。装系统库能同时修好 curl、git、Java;只做 NODE_EXTRA_CA_CERTS 则只影响 Node 进程。生产镜像里推荐两者都做,避免不同工具行为不一致。

能不能只对某一个请求放行?

可以,且比全局关闭安全得多——给该请求传 ca 或使用独立 Agent。用内置 fetch(undici)时需要换成 undici 的 Agent 并通过 dispatcher 传入,https.Agent 对 fetch 无效。

生产环境可以用 NODE_TLS_REJECT_UNAUTHORIZED=0 吗?

不可以。它关闭全部证书校验,任何中间人都能解密和篡改流量,而且这个变量会被子进程继承,影响面远超预期。它只适合一次性、断网的本地调试,用完立即 unset。

SELF_SIGNED_CERT_IN_CHAIN 和 DEPTH_ZERO_SELF_SIGNED_CERT 有什么区别?

DEPTH_ZERO_SELF_SIGNED_CERT 是叶子证书自己签自己(depth 0);SELF_SIGNED_CERT_IN_CHAIN 是链中更深的位置出现了自签证书(通常是代理根)。前者多发生在本地开发,后者多发生在企业网络。

Docker 构建时 npm 报错、本地却正常?

构建阶段没有你的 shell 环境。把 CA 文件 COPY 进镜像,RUN update-ca-certificates,并 ENV NODE_EXTRA_CA_CERTS=...;注意 ENV 必须写在执行 npm ci 的那条 RUN 之前,否则无效。