跳到主要内容

Node.js SELF_SIGNED_CERT_IN_CHAIN 完全排查指南:定位拦截源、修复证书链与生产级配置

你跑 npm install 或者启动 Node 服务时,终端甩出一行 Error: self signed certificate in certificate chain,整个 CI 直接挂掉。这条报错和证书过期、域名不匹配都不一样,它说的是:OpenSSL 在验证证书链时,链的中间出现了自签名证书,而这张证书不在 Node 的信任库里。本文按“看清错误 → 定位来源 → 分场景修复 → 对照排错”的顺序给出可直接复制的命令。

一、先看清错误:这条报错到底在说什么

Node 用 OpenSSL 做 TLS 校验,校验方式是自底向上走完整条链:叶子证书 → 中间证书 → 根证书。走到某一张时发现它是自签名的(subject 与 issuer 相同),且不在信任库中,于是抛出这个错误码。

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:959:8)
    ...
  code: 'SELF_SIGNED_CERT_IN_CHAIN'

npm 侧通常长这样:

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

node-fetch / axios / undici 等上层库会把原始错误包一层:

FetchError: request to https://api.example.com/v1/users failed, reason: self signed certificate in certificate chain
    at ClientRequest.<anonymous> (node_modules/node-fetch/lib/index.js:1491:11)
  type: 'system',
  errno: 'SELF_SIGNED_CERT_IN_CHAIN',
  code: 'SELF_SIGNED_CERT_IN_CHAIN'

关键区分:DEPTH_ZERO_SELF_SIGNED_CERT 表示叶子证书本身就是自签名(多半是站点自己签的);SELF_SIGNED_CERT_IN_CHAIN 表示链的中间或顶端混进了自签名证书(多半是代理替换或 fullchain 配错);UNABLE_TO_VERIFY_LEAF_SIGNATURE 则是链不完整、缺中间证书。三者修复方式完全不同,不要混用。

二、四类根因,先对号入座

  • 站点自签名证书:内网服务、测试环境、自建 API 直接用了 openssl req -x509 生成的证书。
  • 企业 TLS 检查代理:公司网络对 HTTPS 做中间人解密,把上游证书替换成企业 CA 签发的证书,而这张企业根证书不在 Node 的信任库里。
  • 服务端 fullchain 配置错误:部署时把自签根证书一起塞进 fullchain.pem,或者链顺序颠倒、中间证书缺失。
  • npm / CI 环境配置:cafile 指向了错误文件、strict-ssl 被改过、或 CI runner 走了公司代理。

这里有个高频困惑值得先说清楚:浏览器和 curl 都正常,只有 Node 报错。原因是浏览器与 curl 读的是操作系统信任库,而 Node 默认使用自己打包的 Mozilla CA 列表。企业根证书装在系统里,Node 根本看不见——这就是 NODE_EXTRA_CA_CERTS 存在的意义。

三、5 分钟定位:三步锁定拦截来源

第一步,换网络。把机器切到手机热点,重跑一次失败的命令。如果立刻恢复正常,基本可以确定是公司网络的 TLS 检查代理在替换证书。

# 切热点前后各跑一次,对比输出
curl -vI https://registry.npmjs.org/ 2>&1 | grep -E 'subject|issuer|SSL certificate'

第二步,看真实证书链。用 openssl 把服务端下发的整条链打出来:

openssl s_client -connect registry.npmjs.org:443 -servername registry.npmjs.org -showcerts </dev/null

只取叶子证书的 subject / issuer / 指纹:

openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null 
  | openssl x509 -noout -subject -issuer -fingerprint -sha256 -dates

如果 issuer 是 CN=Corp TLS Inspection CA、CN=Zscaler Root CA、CN=Fortinet Untrusted CA 之类的名字,来源就明确了——企业代理。如果 issuer 是 CN=example.com 这种自指的名字,那就是站点自签或服务端 fullchain 配错。

第三步,用 Node 复现最小用例,确认是 Node 层而非某个库的问题:

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

四、场景 A:企业 TLS 检查代理 —— 用 NODE_EXTRA_CA_CERTS 信任根证书

拿到公司根证书(PEM 格式,通常是 .pem 或 .crt,注意不是 DER 二进制),然后通过环境变量追加到 Node 的信任链:

# Linux / macOS
 export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/corp-root-ca.pem
node app.js

# 单条命令临时生效
NODE_EXTRA_CA_CERTS=/path/to/corp-root-ca.pem node app.js

# Windows PowerShell
$env:NODE_EXTRA_CA_CERTS = 'C:certscorp-root-ca.pem'
node app.js

几个必须知道的细节:

  • 该变量只在进程启动时读取一次,改完要重启进程,热更新无效。
  • 它是追加到 Node 自带信任库,不是替换,所以不会影响对公网站点的校验。
  • 一个文件里可以放多张证书,直接按 PEM 块首尾相接即可。
  • 如果文件路径写错或格式不对,Node 会打印 Warning: Ignoring extra certs from ... , load failed: error:...:no start line,此时证书实际未生效。
  • 需要 Node 7.3 及以上;老版本只能走 --use-openssl-ca 或代码里 ca: fs.readFileSync(...)。

如果系统信任库已经装好了企业根证书,也可以让 Node 直接读系统库,省去单独维护:

NODE_OPTIONS=--use-openssl-ca node app.js

代理环境下还别忘了让 Node 走代理本身:

export HTTPS_PROXY=http://proxy.corp.example.com:8080
export HTTP_PROXY=http://proxy.corp.example.com:8080

五、场景 B:服务端证书链配置 —— 只部署 fullchain,别混入自签根

如果你是被访问方(自建 API、内网服务),正确的做法是换正规 CA 证书,并确保部署的是按顺序排列的 fullchain:叶子证书 → 中间证书 →(可选,一般不放)根证书。顺序错了或者少了中间证书,客户端同样会报链验证失败。

部署前先检查文件里的证书顺序:

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

输出应当是 subject=你的域名 在前,subject=中间 CA 在后。如果第一行就是 subject=CN=Self Signed Root,说明根证书被塞到了链首——这正是 SELF_SIGNED_CERT_IN_CHAIN 的典型成因。

nginx 正确配置:

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

    ssl_certificate     /etc/nginx/ssl/fullchain.pem;   # 叶子 + 中间
    ssl_certificate_key /etc/nginx/ssl/privkey.pem;
    ssl_protocols       TLSv1.2 TLSv1.3;
}

改完用 openssl 从客户端视角复验一次,确认服务端下发的链是完整的:

openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts </dev/null 
  | grep -E 'depth=|verify return code'
# 期望看到:verify return code: 0 (ok)

自签名证书只在纯内网、可控客户端的场景下使用;一旦有外部调用方,就必须换正规 CA,否则每个调用方都得配一遍 NODE_EXTRA_CA_CERTS。

六、场景 C:npm / CI 环境配置

npm 的证书配置和 Node 的 NODE_EXTRA_CA_CERTS 是两套独立机制,经常出现“Node 好了但 npm 还报错”。先查现状:

npm config get cafile
npm config get strict-ssl
npm config get proxy
npm config get https-proxy
npm config list -l | grep -i ssl

指向企业根证书即可修复:

npm config set cafile /path/to/corp-root-ca.pem
npm config set strict-ssl true

# yarn / pnpm 同理
yarn config set cafile /path/to/corp-root-ca.pem
pnpm config set cafile /path/to/corp-root-ca.pem

也可以直接写进项目或用户级 .npmrc:

cafile=/path/to/corp-root-ca.pem
strict-ssl=true
registry=https://registry.npmjs.org/

CI 流水线里没有交互式 shell,务必在 pipeline 的环境变量中显式注入:

# GitLab CI / GitHub Actions 通用写法
export NODE_EXTRA_CA_CERTS=$CI_PROJECT_DIR/certs/corp-root-ca.pem
export NPM_CONFIG_CAFILE=$CI_PROJECT_DIR/certs/corp-root-ca.pem
npm ci

Docker 构建时要注意一个坑:把证书拷进 /usr/local/share/ca-certificates 并执行 update-ca-certificates 只更新了系统信任库,Node 默认仍然不读它。要么显式设置 ENV NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/corp-root-ca.crt,要么加 --use-openssl-ca。

七、方案对比:选哪个取决于你是客户端还是服务端

方案 适用场景 安全性 作用范围 备注
NODE_EXTRA_CA_CERTS 企业代理、私有 CA 高 当前进程及其子进程 只追加不替换,PEM 格式,启动时读取一次
npm config set cafile npm / yarn / pnpm 安装依赖 高 当前用户的 npm 配置 与 Node 变量互相独立,需分别配置
NODE_OPTIONS=--use-openssl-ca 系统信任库已含企业根 中高 当前进程 依赖 OS 证书库,容器内常需额外维护
服务端换正规 CA / 修正 fullchain 自建对外服务 高 全局,一劳永逸 根治方案,调用方无需任何配置
NODE_TLS_REJECT_UNAUTHORIZED=0 仅本地临时调试 极低 当前进程 关闭全部 TLS 校验,严禁进入生产
npm config set strict-ssl false 仅本地临时调试 极低 当前 npm 配置 等同放弃校验,易被中间人攻击

八、故障排查:真实报错对照表

报错信息 含义 处理方向
Error: self signed certificate in certificate chain(SELF_SIGNED_CERT_IN_CHAIN) 链中出现自签名证书 确认是否企业代理;是则配 NODE_EXTRA_CA_CERTS;否则查服务端 fullchain
npm ERR! code SELF_SIGNED_CERT_IN_CHAIN npm 请求 registry 被拦截 同时设置 npm config set cafile 与 NODE_EXTRA_CA_CERTS
FetchError: request to https://... failed, reason: self signed certificate in certificate chain node-fetch 包装后的原始错误 看 errno/code 字段,本质同上,不要只看外层 message
unable to verify the first certificate(UNABLE_TO_VERIFY_LEAF_SIGNATURE) 服务端没下发中间证书 补齐 fullchain,不是自签名问题
DEPTH_ZERO_SELF_SIGNED_CERT / self signed certificate 叶子证书本身就是自签名 换正规证书,或客户端信任该自签证书
error:0A000086:SSL routines::certificate verify failed OpenSSL 3 的通用校验失败信息 Node 17+ 常见,需回溯到具体错误码再判断
CERT_HAS_EXPIRED 证书已过期 续签并重载服务,与自签名无关
Warning: Ignoring extra certs from ... , load failed: error:...:no start line NODE_EXTRA_CA_CERTS 文件格式或路径错误 确认是 PEM 文本而非 DER 二进制,路径可读

另外两个容易被忽略的检查点:

# 1. 确认 Node 版本与 OpenSSL 版本(Node 17+ 切换到 OpenSSL 3,报错文案会变)
node -p "process.version + ' / ' + process.versions.openssl"

# 2. 确认环境变量真的传进了子进程
env | grep -i -E 'node_extra_ca|npm_config|proxy'

九、FAQ

Q1:为什么浏览器访问正常,Node 却报 SELF_SIGNED_CERT_IN_CHAIN?
浏览器读操作系统信任库,Node 默认用自带的 Mozilla CA 列表。企业根证书装进系统后浏览器就信任了,Node 看不到,因此需要 NODE_EXTRA_CA_CERTS 或 --use-openssl-ca。

Q2:NODE_EXTRA_CA_CERTS 能一次指定多张证书吗?
不能通过多个路径指定,但可以把多张 PEM 证书首尾相接写进同一个文件,Node 会全部加载。

Q3:设置了 NODE_EXTRA_CA_CERTS 为什么还是报错?
按顺序排查:文件是否为 PEM 文本(head -1 应看到 -----BEGIN CERTIFICATE-----)、路径在当前 shell 是否可读、进程是否重启过、以及报错到底来自 Node 还是 npm(npm 有独立的 cafile)。

Q4:可以直接用 NODE_TLS_REJECT_UNAUTHORIZED=0 吗?
只适合在本地临时验证问题是否由证书引起。它会关闭该进程的全部 TLS 校验,包括对公网站点的校验,属于把门拆了而不是配钥匙,绝不能进入生产或 CI 默认配置。

Q5:为什么 Node 里跑得通,npm install 还是挂?
npm 走自己的 cafile / strict-ssl / proxy 配置链,与 Node 的信任库是两套。两边都要配。

Q6:Docker 镜像里怎么配最省事?
在 Dockerfile 里 COPY 证书后用 ENV NODE_EXTRA_CA_CERTS=/path/corp-root-ca.crt 固定下来;如果还想复用系统库,再补 ENV NODE_OPTIONS=--use-openssl-ca。不要依赖构建机的环境变量。

Q7:自签名证书能不能用于生产?
仅在完全可控的内网、且所有调用方都能统一注入信任证书时可以,但运维成本高、轮换麻烦。有外部调用方时应使用正规 CA。

Q8:根证书要不要放进服务端的 fullchain?
一般不需要。客户端本身已持有根证书,多放一张根证书既增加握手体积,也容易因为把自签根混进去而触发 SELF_SIGNED_CERT_IN_CHAIN。正确内容是叶子证书加中间证书。