Node.js 报 ERR_TLS_CERT_ALTNAME_INVALID:IP 或域名与证书 SAN 不匹配的完整修复指南
问题背景与根因:Node.js 为什么拒绝这张证书
ERR_TLS_CERT_ALTNAME_INVALID 是 Node.js 在 TLS 握手完成之后、执行主机名校验(RFC 6125)失败时抛出的错误码,由内部函数 tls.checkServerIdentity() 产生。关键点在于:Node 不读证书的 CN(Common Name),只认 SAN(subjectAltName)扩展。所以只要请求 URL 里的 host——不管是域名还是 IP 字面量——不在 SAN 列表中,握手能成功,但校验阶段直接抛错,请求根本到不了业务代码。
三个高频触发场景:
- 用 IP 直连 HTTPS:公共 CA 默认不签 IP SAN(IP 归属难验证),证书里往往只有
DNS:api.example.com;即使签了 IP,也必须出现IP Address:203.0.113.10条目,DNS 条目不能顶替。 - 访问名与签发名不一致:证书签的是
api.example.com,代码里却访问api.internal.example.com;或访问example.com而证书只有*.example.com(通配符不覆盖裸域,也不覆盖多级子域)。 - 中间设备换证:CDN 回源、WAF、企业 HTTPS 代理会返回另一张证书,其 SAN 与客户端请求名不符。
两个必须更新的认知:其一,公共信任 TLS 证书最长有效期已压到 398 天,并按 CA/Browser Forum 计划在 2026-03-15 起降为 200 天、2027-03-15 起 100 天、2029-03-15 起 47 天,Let’s Encrypt 仍是 90 天,轮换更频繁意味着 SAN 配错的暴露窗口更短;其二,自 2025 年起 Let’s Encrypt 已可签发带 IP SAN 的短期证书(约 6 天),IP 直连不再只有商业 CA 一条路。至于 rejectUnauthorized: false 或 NODE_TLS_REJECT_UNAUTHORIZED=0,那是关掉校验,不是修复。
先看清证书里有什么:三条命令定位 SAN
不要猜,先把服务端真实返回的证书抓下来。
# 1) 域名方式,看 SAN、有效期、签发者
openssl s_client -connect api.example.com:443 -servername api.example.com </dev/null 2>/dev/null
| openssl x509 -noout -subject -issuer -dates -ext subjectAltName
# 2) IP 直连,看是否返回同一张证书(比对指纹)
openssl s_client -connect 203.0.113.10:443 </dev/null 2>/dev/null
| openssl x509 -noout -fingerprint -sha256 -ext subjectAltName
# 3) 本地证书文件自检
openssl x509 -in server.crt -noout -ext subjectAltName
openssl req -in server.csr -noout -text | grep -A2 'Subject Alternative Name'
正常输出形如:
X509v3 Subject Alternative Name:
DNS:api.example.com, DNS:*.api.example.com
如果这里只有 DNS 条目,用 IP 访问就必然报 ERR_TLS_CERT_ALTNAME_INVALID;如果第 1 条和第 2 条打印的 SHA-256 指纹不同,说明请求被代理或负载均衡接到了别的证书上,问题不在 Node。
再用一个最小 Node 脚本确认错误来源:
// check.js
const tls = require('node:tls');
const host = process.argv[2];
const socket = tls.connect(
{ host, port: 443, servername: process.env.SNI || undefined },
() => {
const c = socket.getPeerCertificate(true);
console.log('authorized =', socket.authorized);
console.log('authorizationError =', socket.authorizationError);
console.log('subjectaltname =', c.subjectaltname);
socket.end();
}
);
socket.on('error', (e) => { console.error(e.code, e.message); process.exit(1); });
执行 node check.js 203.0.113.10,会看到 authorized = false 与 authorizationError = ERR_TLS_CERT_ALTNAME_INVALID,同时打印证书实际的 SAN 列表,根因当场确认。注意 servername 的作用:Node 调用 checkServerIdentity 时优先用它作为校验名,同时用它发送 SNI,所以把它设成域名相当于「用域名去验 IP」,前提是这个 IP 确实是该域名的地址。
完整实操步骤:把访问名和 SAN 对齐
第 1 步,统一入口域名。把代码、配置、环境变量里的 https://203.0.113.10 全部换成 https://api.example.com。域名解析可以用 DNS,也可以临时写 hosts:
echo '203.0.113.10 api.example.com' | sudo tee -a /etc/hosts
getent hosts api.example.com # 验证解析
dig +short api.example.com
容器里用 docker run --add-host api.example.com:203.0.113.10 ...,Kubernetes 用 hostAliases,避免改动镜像内 DNS。
第 2 步,补齐证书 SAN。把所有真实访问名一次性签进去,别只签一个:
certbot certonly --nginx
-d api.example.com -d www.example.com -d example.com
--deploy-hook 'systemctl reload nginx'
Let’s Encrypt 证书 90 天有效,确认续期定时器存在:systemctl list-timers | grep certbot,并做一次演练 certbot renew --dry-run。公共信任证书单张最长 398 天,别指望签长期证书省事。
第 3 步,确需 IP 直连时的三条路。① 向商业 CA 申请含 IP SAN 的证书,需要提供 IP 归属证明(一般只受理公网 IP),有效期同样受 398 天限制;② 使用 Let’s Encrypt 的 IP 证书能力(2025 年起提供,短期约 6 天,需 ACME 客户端支持对应 profile 与高频续期);③ 内网自建 CA 签发 IP SAN 证书,把根证书通过 NODE_EXTRA_CA_CERTS 注入 Node 进程。
第 4 步,代码侧不再拼接 IP。把 baseURL、健康检查地址、回调地址全部收敛到配置项,并在启动时断言:
const u = new URL(process.env.API_BASE_URL);
if (/^d+.d+.d+.d+$/.test(u.hostname)) {
throw new Error('API_BASE_URL must use a DNS name covered by the cert SAN');
}
第 5 步,验证后再灰度。先在预发环境跑通 curl --resolve 与 Node 脚本,再切生产流量,验证方法见文末一节。
配置示例:Nginx 服务端 + Node 客户端 + 自建 CA
服务端(Nginx)务必下发完整链,否则客户端会报 unable to verify the first certificate:
server {
listen 443 ssl;
http2 on;
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;
ssl_session_cache shared:SSL:10m;
location / { proxy_pass http://127.0.0.1:3000; }
}
内网自建 CA 并签发含 IP SAN 的证书(一条龙命令):
openssl req -x509 -newkey rsa:2048 -nodes -days 3650
-keyout ca.key -out ca.crt -subj '/CN=Internal Root CA'
cat > san.cnf <<'EOF'
subjectAltName=DNS:app.internal,IP:10.0.0.12,IP:127.0.0.1
extendedKeyUsage=serverAuth
keyUsage=digitalSignature,keyEncipherment
basicConstraints=CA:FALSE
EOF
openssl req -newkey rsa:2048 -nodes -keyout server.key -out server.csr -subj '/CN=app.internal'
openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial
-out server.crt -days 397 -extfile san.cnf
Node 客户端注入私有根证书,并把校验名固定为域名:
const https = require('node:https');
const fs = require('node:fs');
const agent = new https.Agent({
ca: fs.readFileSync('/etc/ssl/certs/internal-ca.crt'),
keepAlive: true,
minVersion: 'TLSv1.2',
});
https.get('https://10.0.0.12/health', {
agent,
servername: 'app.internal', // 校验名与 SNI 都用域名
headers: { Host: 'app.internal' },
}, (res) => {
console.log(res.statusCode);
res.resume();
});
不想改代码就用环境变量注入根证书:NODE_EXTRA_CA_CERTS=/etc/ssl/certs/internal-ca.crt node app.js。它只在进程启动时读取一次,换了证书必须重启,热加载无效。若证书本身就带 IP SAN,URL 直接写 IP 也能通过校验,无需自定义 checkServerIdentity。
方案对比:五种做法怎么选
| 方案 | 适用场景 | 有效期 / 成本 | Node 侧改动 | 风险与限制 |
|---|---|---|---|---|
| 改用域名访问(推荐) | 绝大多数公网与内网服务 | Let’s Encrypt 90 天免费;商业 CA 最长 398 天 | 无,仅改配置 | 依赖 DNS 或 hosts 正确解析 |
| 商业 CA 签发 IP SAN 证书 | 必须用公网 IP 直连、无法加 DNS | 按张计费;不超过 398 天 | 无 | 需 IP 归属证明;私网 IP 基本不受理 |
| Let’s Encrypt IP 证书 | 公网 IP、可自动化续期 | 约 6 天,需高频续期 | 无 | 客户端与 ACME 账户需支持;断更即失效 |
| 内网自建 CA + IP SAN | 内网、测试环境、IoT | 自定,建议不超过 398 天 | 配 ca 或 NODE_EXTRA_CA_CERTS |
根证书需分发到所有客户端;私钥管理成本高 |
关闭校验(rejectUnauthorized: false) |
仅本地临时调试 | — | 一行代码 | 等同放弃身份认证,可被任意中间人攻击,生产禁用 |
补一张 SAN 匹配规则速查表,排查时对照即可:
| 证书 SAN 条目 | 匹配 example.com | 匹配 a.example.com | 匹配 a.b.example.com | 匹配 203.0.113.10 |
|---|---|---|---|---|
DNS:example.com |
是 | 否 | 否 | 否 |
DNS:*.example.com |
否 | 是 | 否 | 否 |
IP Address:203.0.113.10 |
否 | 否 | 否 | 是 |
结论很直接:能上域名就不要用 IP。IP 直连的每个方案都要额外付出证书成本或信任链维护成本,而证书有效期缩短到 398 天甚至更短之后,这些成本只会更高。
常见错误排查:真实报错逐条对
1)SAN 里完全没有可匹配条目
Error [ERR_TLS_CERT_ALTNAME_INVALID]: Hostname/IP does not match certificate's altnames:
IP: 203.0.113.10 is not in the cert's list:
注意冒号后面是空的——表示证书里一个可匹配条目都没有(或全是 DNS)。处理:改用域名访问,或重新签发含 IP Address:203.0.113.10 的证书。
2)有 SAN 但不含你用的名字
... is not in the cert's list:
DNS:api.example.com
典型原因是域名拼错、用了内网别名,或误以为 *.example.com 能覆盖裸域。用第 2 节的 openssl x509 -ext subjectAltName 对照即可。
3)自建 CA 没被信任
Error: unable to verify the first certificate
Error: self-signed certificate in certificate chain
链不完整或根证书没注入。Nginx 用 fullchain.pem;Node 设 ca 或 NODE_EXTRA_CA_CERTS,改完必须重启进程。
4)curl 侧同样报错
curl: (60) SSL: no alternative certificate subject name matches target host name '203.0.113.10'
用 curl -vI --resolve api.example.com:443:203.0.113.10 https://api.example.com 验证域名路径是否正常,从而区分是证书问题还是 DNS 问题。
5)加了 IP SAN 仍报错。先怀疑中间设备:openssl s_client -connect 203.0.113.10:443 -showcerts 看实际下发证书的指纹,与源站比对;再怀疑 TLS 会话复用拿到旧证书,客户端加 agent: false 或重启进程复测。企业代理做 HTTPS 中间人时,需要把企业根证书导入信任库。
6)证书过期伪装成不匹配。顺手查有效期:openssl x509 -in server.crt -noout -dates -checkend 2592000,剩余不足 30 天会返回非 0 退出码,适合放进巡检脚本。
效果验证:三条命令确认修复到位
第一,链校验:
openssl verify -CAfile ca.crt -untrusted chain.pem server.crt
# 期望输出:server.crt: OK
第二,握手与 SAN 断言(可直接放进 CI):
openssl s_client -connect api.example.com:443 -servername api.example.com </dev/null 2>/dev/null
| openssl x509 -noout -ext subjectAltName | grep -q 'DNS:api.example.com'
&& echo SAN_OK || echo SAN_MISSING
第三,Node 侧真实请求:
node -e "
const https=require('node:https');
https.get('https://api.example.com/health',{timeout:5000},r=>{
console.log('status',r.statusCode,'authorized',r.socket.authorized);
console.log('san',r.socket.getPeerCertificate().subjectaltname);
r.resume();r.on('end',()=>process.exit(0));
}).on('error',e=>{console.error(e.code,e.message);process.exit(1);});
"
期望看到 authorized true 和包含目标名的 SAN 列表。若仍报错,用 NODE_DEBUG=tls node app.js 看握手细节;也可以临时设 NODE_TLS_REJECT_UNAUTHORIZED=0 只为确认「关掉校验就能通」,验证完立刻删除,绝不能带上线。
最后把验证固化成巡检:证书剩余有效期、SAN 是否覆盖全部线上域名、指纹是否与预期一致,三项都做告警。证书有效期已缩短到 398 天并会继续缩短,靠人工记忆续期迟早出事。
常见问题
因为 Node.js 只校验 SAN(subjectAltName),自 Node 12 起不再回退到 CN。用 openssl x509 -noout -ext subjectAltName 确认 SAN 是否包含实际访问名,缺失就重新签发。
不能。通配符只匹配单个 DNS 标签,也不匹配 IP 字面量。用 IP 访问必须让证书里出现 IP Address:203.0.113.10 这样的条目,或者干脆改用域名访问。
能绕过报错,但等于关闭全部证书校验,任何中间人都可冒充服务端,Node 还会打印警告。仅限本地临时调试,生产环境请改用正确 SAN 或注入私有 CA。
支持。Let’s Encrypt 自 2025 年起可签发含 IP SAN 的短期证书,有效期约 6 天,需要 ACME 客户端支持对应 profile 并保证高频自动续期,否则过期即失效。
不会。浏览器、操作系统、Node 各自维护信任库,需分别导入根证书;Node 用 NODE_EXTRA_CA_CERTS 环境变量或 https.Agent 的 ca 选项,且只在进程启动时读取一次。
最长 398 天,并将在 2026-03-15 降至 200 天、2027-03-15 降至 100 天、2029-03-15 降至 47 天;Let’s Encrypt 免费证书固定 90 天,续期自动化必须到位。