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。正确内容是叶子证书加中间证书。