Node.js 报 ERR_TLS_CERT_ALTNAME_INVALID:证书 SAN 不匹配的根因、修复方案与验证全流程
问题背景:ERR_TLS_CERT_ALTNAME_INVALID 到底在校验什么
在 Node.js 里访问 HTTPS 服务时,下面这条报错几乎全部来自同一个原因——你请求使用的主机名(或 IP)不在服务器证书的 SAN(Subject Alternative Name)列表里:
Error: Hostname/IP does not match certificate's altnames: IP: 203.0.113.10 is not in the cert's list:
DNS:example.com, DNS:www.example.com
at TLSSocket.onConnectSecure (node:_tls_wrap:1674:34)
at TLSSocket.emit (node:events:517:28)
code: 'ERR_TLS_CERT_ALTNAME_INVALID'
Node 的校验由 tls.checkServerIdentity(hostname, cert) 完成,hostname 取自连接选项的 servername,未设置时回退到 host。它只认 SAN 扩展里的 DNS: 与 IP Address: 条目,不再回退到 CN(RFC 9525 已废弃 CN 匹配,Chrome 58 起、Node 8 起同样如此)。因此「证书 CN 写的是 example.com」不构成任何豁免理由。
四类高频触发场景:用 IP 直连 HTTPS(公共 CA 默认不签 IP SAN);域名拼写或子域与证书不一致;通配符层级不匹配(*.example.com 既不覆盖 a.b.example.com,也不覆盖裸域 example.com);客户端未发 SNI,服务端返回了默认站点的证书。
还要记住当前的有效期规则:公共可信 TLS 证书单张最长 398 天(2020-09-01 起生效),Let’s Encrypt 为 90 天;CA/B Forum 已通过分阶段缩短方案(2026 年 3 月降至 200 天、2027 年 3 月降至 100 天、2029 年 3 月降至 47 天),证书轮换与监控排期需按此预留。
第一步:用 openssl 查清证书里到底有什么
排查第一步永远是「看证书」,不要猜。
# 按 SNI 抓取线上证书,只看关键字段
openssl s_client -connect 203.0.113.10:443 -servername example.com </dev/null 2>/dev/null
| openssl x509 -noout -subject -issuer -dates -ext subjectAltName
典型输出:
subject=CN = example.com
issuer=C = US, O = Let's Encrypt, CN = R11
notBefore=Mar 1 00:00:00 2025 GMT
notAfter=May 30 00:00:00 2025 GMT
X509v3 Subject Alternative Name:
DNS:example.com, DNS:www.example.com
这一步同时确认三件事:SAN 里有没有你用的那个 host、证书是否过期、由谁签发。然后做一组对照实验——把 -servername 去掉再执行一次。如果两次拿到的 subject 不同,说明服务端存在多个虚拟主机,你的客户端没发 SNI(或发错),拿到的是默认站点证书,这才是报错的真实原因,而不是证书本身有问题。
证书在本地文件时用:
openssl x509 -in fullchain.pem -noout -ext subjectAltName
# 检查尚未签发的 CSR 是否带 SAN(漏了必然返工)
openssl req -in server.csr -noout -text | grep -A2 'Subject Alternative Name'
# 校验链与主机名 / IP 是否匹配
openssl verify -CAfile ca.crt -verify_hostname app.internal server.crt
openssl verify -CAfile ca.crt -verify_ip 10.0.0.12 server.crt
在 Node 进程内也能直接打印对端证书:socket.getPeerCertificate().subjectaltname 返回形如 DNS:example.com, IP Address:10.0.0.12 的字符串,配合 tls.checkServerIdentity() 可离线复现校验结果。注意 getPeerCertificate() 默认只给叶子证书,要拿完整链需传 true,再沿 issuerCertificate 逐级向上取。
方案一:改用域名访问,或用 servername 声明校验身份
95% 的场景正确解法是「用域名访问」,而不是关掉校验。先确认解析:dig +short example.com、getent hosts example.com。Node 17 起 dns.lookup() 默认 verbatim: true,不再按 IPv4 优先排序,双栈环境下可能优先连 AAAA 记录;若该地址没有服务,表现为超时而非证书错误,排查时要区分。
不改 DNS 的临时验证手段是 curl 的 --resolve:
curl -v --resolve example.com:443:203.0.113.10 https://example.com/healthz
如果业务确实必须直连 IP(固定后端、容器内无 DNS),但证书是域名证书,正确做法是保留 IP 作为连接地址,用 servername 声明「以哪个身份校验证书」:
const https = require('https');
const req = https.request({
host: '203.0.113.10', // TCP 实际连到哪里
port: 443,
servername: 'example.com', // SNI + 证书主机名校验用的名字
path: '/api/health',
method: 'GET',
headers: { Host: 'example.com' }, // HTTP 层路由仍看 Host
}, (res) => {
console.log(res.statusCode, res.headers['content-type']);
res.resume();
});
req.on('error', (e) => console.error(e.code, e.message));
req.end();
要点:servername 同时决定 TLS 握手的 SNI 和 checkServerIdentity 的 hostname 参数(Node 12 及以上行为一致),设了它之后即使 host 是 IP 也能通过校验;但 Host 头必须单独设置,否则 Nginx / Ingress 的路由会落到默认 server 块。使用 keep-alive 的 https.Agent 时,连接按 servername 分池复用,不同域名不要共用一个 agent。
明确反对两种「伪修复」:rejectUnauthorized: false 和 NODE_TLS_REJECT_UNAUTHORIZED=0。它们关闭的是整条链的校验,等于放弃对中间人攻击的防护,还会在日志里留下 Warning: Setting the NODE_TLS_REJECT_UNAUTHORIZED environment variable to '0'。同理,checkServerIdentity: () => undefined 也只是把问题藏起来,并没有修复。
方案二:确实需要 IP 直连时,如何拿到含 IP SAN 的证书
如果 IP 是业务的稳定入口(IoT 设备、内网服务、无域名环境),就必须让证书真的包含该 IP。
公网 IP:商业 CA(DigiCert、Sectigo、ZeroSSL 等)支持 IP SAN,需在 SAN 中显式写入 IP:203.0.113.10,并通过文件验证或反向 DNS 证明对 IP 的控制权;私网地址(10/8、172.16/12、192.168/16)与保留地址不会被公共 CA 签发。Let’s Encrypt 长期不支持 IP SAN,2025 年起才开始为 IP 地址签发短期证书(有效期约 6 天,需较新客户端与更密集的续期调度),生产使用前要评估续期失败的兜底方案。
内网 IP / 自建服务:用内网 CA 签发,一次配置长期受益。
# 1) 建根 CA(有效期 10 年)
openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes
-keyout ca.key -out ca.crt -subj '/CN=Internal Root CA'
# 2) 服务器私钥 + CSR
openssl req -newkey rsa:2048 -nodes -keyout server.key -out server.csr
-subj '/CN=app.internal'
# 3) 关键:扩展文件里写全 SAN,DNS 与 IP 都要写
cat > san.cnf <<'EOF'
basicConstraints = CA:FALSE
keyUsage = digitalSignature, keyEncipherment
extendedKeyUsage = serverAuth
subjectAltName = DNS:app.internal, DNS:localhost, IP:10.0.0.12, IP:127.0.0.1
EOF
# 4) 签发,天数不要超过 398
openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial
-days 397 -sha256 -extfile san.cnf -out server.crt
三个常见坑:签发时忘加 -extfile 会得到一个没有 SAN 的证书,等于必然报 ERR_TLS_CERT_ALTNAME_INVALID;-days 超过 398 会被主流客户端拒绝;证书里必须带 extendedKeyUsage = serverAuth,否则部分客户端会拒绝把它用于服务端认证。
Node 侧配置示例:让客户端信任签发者
拿到含 IP SAN 的证书后,客户端还要信任签发它的 CA。三种注入方式,按粒度从细到粗:
// 方式 A:在 Agent 上显式指定 ca(推荐,粒度可控)
const https = require('https');
const fs = require('fs');
const ca = fs.readFileSync('/etc/ssl/internal-ca.crt');
const agent = new https.Agent({ ca, keepAlive: true, maxSockets: 64 });
https.get({
host: '10.0.0.12', port: 443, path: '/healthz', agent,
headers: { Host: 'app.internal' },
}, (res) => { /* ... */ });
# 方式 B:进程级环境变量,启动时读取一次,换证书必须重启进程
NODE_EXTRA_CA_CERTS=/etc/ssl/internal-ca.crt node server.js
// 方式 C:全局 agent,影响整个进程的 https 请求
https.globalAgent.options.ca = ca;
如果用的是 Node 18+ 内置的 fetch(undici 实现),它不认 agent 选项,需要设置 dispatcher:
const { Agent, setGlobalDispatcher } = require('undici');
const fs = require('fs');
setGlobalDispatcher(new Agent({
connect: { ca: fs.readFileSync('/etc/ssl/internal-ca.crt'), servername: 'app.internal' },
}));
NODE_EXTRA_CA_CERTS 由 tls 模块统一读取,因此对 https、fetch、axios(底层仍是 http/https)都生效,是容器里最省事的方式;但它只在进程启动时读一次,滚动更新证书后必须重启 Pod。axios 用户若要用 servername,写法是 httpsAgent: new https.Agent({ servername: 'example.com', ca }),并注意别在拦截器里再覆盖 Host。
方案对比:五条路径怎么选
| 方案 | 适用场景 | 浏览器/系统信任 | Node 改动 | 成本 | 主要风险 |
|---|---|---|---|---|---|
| 改用域名访问 | 有可控 DNS 的公网或内网服务 | 是 | 无(只改 URL) | 低 | DNS 被改指向会导致校验失败 |
| IP 连接 + servername 覆盖 | 必须固定 IP,证书为域名证书 | 是(浏览器需同法处理) | 中(Agent、Host 头) | 低 | Host 头漏设会路由到默认站点 |
| 公共 CA 签 IP SAN 证书 | 公网固定 IP 对外提供服务 | 是 | 无 | 高(商业 CA,需证明 IP 所有权) | IP 变更需重签 |
| 内网自建 CA + IP SAN | 内网、K8s、IoT | 否(需分发根证书) | 需注入 ca | 低 | 根证书分发与吊销管理 |
| rejectUnauthorized:false | 仅限一次性调试 | 否 | 有 | 无 | 完全失去 MITM 防护,禁止上线 |
两条判断依据:一是「谁来做信任锚」——面向公网用户的入口用公共 CA,纯内网东西向通信用内网 CA 更划算;二是「IP 是否长期稳定」——云上弹性 IP、容器 IP 会漂移,此时应把域名或 Service DNS 作为校验主体,而不是给 IP 签证书。另外注意公共证书 398 天上限与 Let’s Encrypt 90 天的差异,方案选型时要把续期自动化成本一起算进去。
常见错误排查:按 message 精确区分
下面这些报错经常被混为一谈,按 message 精确区分能省掉大量时间:
# 1) 缺 IP SAN
Hostname/IP does not match certificate's altnames: IP: 10.0.0.12 is not in the cert's list:
DNS:app.internal
code: 'ERR_TLS_CERT_ALTNAME_INVALID'
# 2) 通配符层级不匹配(用 a.b.example.com 访问 *.example.com 证书)
Hostname/IP does not match certificate's altnames: Host: a.b.example.com is not in the
cert's list: DNS:*.example.com
# 3) 裸域不被通配符覆盖
Hostname/IP does not match certificate's altnames: Host: example.com is not in the
cert's list: DNS:*.example.com
# 4) 链不完整或自签(注意:这不是 ALTNAME 错误)
unable to verify the first certificate code: 'UNABLE_TO_VERIFY_LEAF_SIGNATURE'
self signed certificate in certificate chain code: 'SELF_SIGNED_CERT_IN_CHAIN'
DEPTH_ZERO_SELF_SIGNED_CERT
排查顺序建议:① 用 openssl s_client 确认 SAN 内容;② 加/去 -servername 对比是否拿到不同证书,判断 SNI 问题;③ 打印 Node 实际使用的 hostname——很多人是在 Agent 或请求拦截器里覆盖了 servername,导致校验名与预期不一致;④ IPv6 场景下 host: '::1' 会以 ::1 参与校验,证书 SAN 必须写成 IP:::1,只写 IP:127.0.0.1 不生效;⑤ 确认没有在别处设置 NODE_TLS_REJECT_UNAUTHORIZED=0 掩盖真实错误,这类问题的典型特征是「本地能跑、线上报错」。
还有一类「看起来像证书问题」的假故障:请求超时或 ECONNREFUSED。证书校验发生在 TCP 建连与 TLS 握手之后,连不上时不会出现 ALTNAME 错误,不要混在同一分支里排查。
效果验证:三层校验 + 自检脚本
改完必须验证,而不是「不报错就算过」。
# 1) 离线校验证书本身
openssl verify -CAfile ca.crt -verify_hostname app.internal server.crt
openssl verify -CAfile ca.crt -verify_ip 10.0.0.12 server.crt
# 2) 线上用 curl 走完整链路(含 SNI 与 Host)
curl -v --cacert ca.crt --resolve app.internal:443:10.0.0.12 https://app.internal/healthz
# 3) 查看实际握手结果
openssl s_client -connect 10.0.0.12:443 -servername app.internal -CAfile ca.crt </dev/null 2>/dev/null
| grep -E 'Verify return code|subject='
Node 侧写一个自检脚本,直接复用生产配置:
const tls = require('tls');
const fs = require('fs');
const ca = fs.readFileSync('/etc/ssl/internal-ca.crt');
const s = tls.connect({ host: '10.0.0.12', port: 443, servername: 'app.internal', ca }, () => {
const cert = s.getPeerCertificate();
console.log('authorized =', s.authorized, s.authorizationError || '');
console.log('san =', cert.subjectaltname);
console.log('identity =', tls.checkServerIdentity('app.internal', cert)); // undefined 表示匹配
s.end();
});
把 authorized === true 且 checkServerIdentity() 返回 undefined 作为验收标准,写进 CI 或发布前检查脚本。最后补上监控:公共证书最长 398 天、Let’s Encrypt 90 天,建议到期前 30 天告警;同时把证书 SAN 覆盖的域名/IP 清单纳入配置管理,新增一个访问入口就同步检查证书覆盖范围,可以避免绝大多数线上复发。
常见问题
最常见原因是代码里连的是 IP,而浏览器地址栏用的是域名。其次是 Agent 或请求拦截器覆盖了 servername,使校验名与预期不一致;也可能是服务端多证书环境,Node 未发 SNI 拿到默认站点证书。用 openssl s_client 加与不加 -servername 对比即可定位。
能,但不要这么做。它关闭的是整条证书链与主机名校验,等于放弃中间人攻击防护,还会让其他证书错误一并被掩盖。正确做法是让证书 SAN 覆盖你使用的主机名或 IP,或在直连 IP 时用 servername 指定校验身份。
都不能。通配符只用于 DNS 名称且只匹配一级,*.example.com 不覆盖 example.com,也不覆盖 a.b.example.com,更不覆盖任何 IP。IP 必须在 SAN 中写成 IP:10.0.0.12 这样的独立条目,否则必然报 ALTNAME 错误。
不必。内网可自建根 CA,签发含 IP SAN 的证书,客户端通过 NODE_EXTRA_CA_CERTS 环境变量或 https.Agent 的 ca 选项注入信任即可。注意根证书私钥要妥善保管并规划吊销流程,否则校验就失去意义。
servername 作用于 TLS 层,决定 SNI 和证书主机名校验;Host 是 HTTP 头,决定 Nginx、Ingress 等应用层路由。直连 IP 时两者通常都要设成同一个域名,只设一个会出现校验通过但请求落到默认站点的情况。
公共可信 TLS 证书单张最长 398 天,Let’s Encrypt 为 90 天。CA/B Forum 已确定分阶段缩短至 200 天(2026 年 3 月)、100 天(2027 年 3 月)、47 天(2029 年 3 月),续期自动化需要提前适配。