跳到主要内容

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 天,续期自动化必须到位。