跳到主要内容

Node.js ERR_TLS_CERT_ALTNAME_INVALID 完全解决指南:IP 与域名 SAN 不匹配

问题背景与根因:为什么用 IP 访问 HTTPS 必然触发 ERR_TLS_CERT_ALTNAME_INVALID

Node.js 在 TLS 握手完成后会调用 tls.checkServerIdentity(hostname, cert) 做主机名校验:把请求 URL 里的 host 与证书 subjectAltName(SAN)中的 DNS 名称、IP 地址逐项比对。只要 host 不在 SAN 列表里,就抛出 ERR_TLS_CERT_ALTNAME_INVALID。Node 从 v15 起完全忽略证书的 CN 字段,只看 SAN——这是很多“证书明明写了域名”却仍然报错的根本原因。

典型报错长这样:

Error: certificate subjectAltName does not match 203.0.113.10
    at TLSSocket.onConnectSecure (node:_tls_wrap:1674:34)
  code: 'ERR_TLS_CERT_ALTNAME_INVALID'

在 Node 18/20/22 上措辞略有差异,也可能是:

Error: Hostname/IP does not match certificate's altnames: IP: 203.0.113.10 is not in the cert's list:
    DNS:api.example.com
  code: 'ERR_TLS_CERT_ALTNAME_INVALID'

根因分两层。第一层是技术层:公共 CA 受 CA/Browser Forum 基线要求约束,只能为“申请人可证明控制权”的公网 IP 签发,流程繁琐、按 IP 计价;内网地址(10/8、172.16/12、192.168/16、127.0.0.1、::1)任何公共 CA 都不会签。所以 https://10.0.0.12 这种写法,证书里根本没有对应 IP SAN,报错是必然的。第二层是常见触发场景:容器健康检查直连 Pod IP、Kubernetes Service ClusterIP 探活、内网微服务互调、CDN 回源、老代码把域名硬编码成 IP。

先用两条命令确认证书里到底有什么:

# 1. 拉取对端证书并查看 SAN(注意加 -servername 触发 SNI)
openssl s_client -connect 203.0.113.10:443 -servername api.example.com </dev/null 2>/dev/null 
  | openssl x509 -noout -subject -ext subjectAltName -dates

# 2. 用 Node 复现,拿到确切的错误码
node -e "require('https').get('https://203.0.113.10/health',r=>console.log(r.statusCode)).on('error',e=>console.log(e.code,'|',e.message))"

如果第一条命令输出的 SAN 里只有 DNS:api.example.com,而第二条用 IP 访问,结论就确定了:要么改访问方式(方案一),要么换证书(方案二/三)。curl 的对应报错是 curl: (60) SSL: no alternative certificate subject name matches target host name '203.0.113.10',可以交叉验证,避免误判成证书链问题。

方案一:改用域名访问,并保证 DNS、SNI 与 Host 头三者对齐

最省事的做法是别用 IP。但“改成域名”不止是改一行 URL,要同时满足三件事:DNS 解析到目标机器、TLS 层发出正确的 SNI、证书 SAN 含该域名。任何一环缺失都会回到同一个报错。

操作步骤:

  1. 加解析并验证:dig +short api.example.com;内网可用 /etc/hosts 或 CoreDNS 自定义解析。
  2. 核对证书 SAN:openssl x509 -in fullchain.pem -noout -ext subjectAltName,确认含 DNS:api.example.com。
  3. 验证握手:openssl s_client -connect 203.0.113.10:443 -servername api.example.com,看输出的 subject= 是不是期望的那张证书。
  4. 改代码,把 URL 里的 IP 换成域名。

若确实必须“TCP 连 IP、校验用域名”,https.request 支持 servername(SNI)+ 自定义 checkServerIdentity:

const https = require('https');
const tls = require('tls');

const req = https.request({
  host: '203.0.113.10',          // TCP 连到 IP
  servername: 'api.example.com', // SNI 与证书匹配
  port: 443,
  path: '/health',
  method: 'GET',
  // 关键:用域名做主机名校验,而不是用 IP
  checkServerIdentity: (host, cert) => tls.checkServerIdentity('api.example.com', cert),
}, (res) => { console.log(res.statusCode); res.resume(); });
req.on('error', (e) => console.error(e.code, e.message));
req.end();

注意:checkServerIdentity 只覆盖主机名比对,证书链校验(ca、有效期、吊销)照常执行,所以这不是“关校验”。但必须确保 203.0.113.10 就是 api.example.com 的真实地址,否则等于给自己开后门。

curl 侧等价写法:curl --resolve api.example.com:443:203.0.113.10 https://api.example.com/health -v。fetch/undici 侧(Node 18+ 内置 fetch 基于 undici)不能传 checkServerIdentity,必须用 Agent:

const { Agent, setGlobalDispatcher } = require('undici');
setGlobalDispatcher(new Agent({
  connect: {
    servername: 'api.example.com',
    checkServerIdentity: (h, c) => tls.checkServerIdentity('api.example.com', c),
  },
}));
const res = await fetch('https://203.0.113.10/health');

还要区分两件事:HTTP 的 Host 头(虚拟主机路由)和 TLS 的 SNI(证书选择)。Nginx 上 server_name 与默认 server 决定了“SNI 不匹配时返回哪张证书”,默认站点证书常常是另一张,于是出现“证书里有域名却报 ALTNAME_INVALID”。检查方法:openssl s_client 不加 -servername 与加 -servername 各跑一次,对比输出的 subject。

方案二:为 IP 申请含 IP SAN 的证书(CSR 与 OpenSSL 实操)

公网 IP 只能找少数商业 CA(如 DigiCert、Sectigo 的 IP 证书产品),需要提供 IP 归属证明,通常按 IP 数量计价,有效期同样受限,绝大多数业务不划算。所以这里给两条路:公网 IP 走商业 CA,内网 IP 走自建 CA(下一节)。无论哪条路,都要先生成带 IP SAN 的 CSR。手写配置比 -addext 更可控、更容易进版本库:

cat > san.cnf <<'EOF'
[req]
distinguished_name = dn
req_extensions     = v3_req
prompt             = no

[dn]
C  = CN
O  = Example Inc
CN = 203.0.113.10

[v3_req]
basicConstraints = CA:FALSE
keyUsage         = critical, digitalSignature, keyEncipherment
extendedKeyUsage = serverAuth
subjectAltName   = @alt

[alt]
IP.1  = 203.0.113.10
IP.2  = 10.0.0.12
DNS.1 = api.example.com
EOF

openssl req -new -newkey rsa:2048 -nodes 
  -keyout server.key -out server.csr -config san.cnf

# 确认 CSR 里已经带上 IP SAN
openssl req -in server.csr -noout -text | grep -A2 'Subject Alternative Name'

关键提醒:CSR 里的 SAN 只是“申请”,最终以签发出的证书为准。不少 CA 的下单页面会忽略 CSR 中的 SAN,要求你在网页表单里逐个填写 IP;拿到证书后必须回验:

openssl x509 -in server.crt -noout -ext subjectAltName -dates
# 期望看到 IP Address:203.0.113.10

部署时证书链要完整,Nginx 必须用 fullchain(叶子证书 + 中间证书),否则客户端会报 UNABLE_TO_VERIFY_LEAF_SIGNATURE:

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

    ssl_certificate     /etc/nginx/ssl/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/server.key;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_session_cache   shared:SSL:10m;

    location /health { return 200 'ok'; }
}

有效期事实:按 CA/Browser Forum 现行要求,公共 TLS 证书单张有效期上限为 398 天(自 2020-09-01 起执行);Let’s Encrypt 免费证书固定 90 天,官方推荐用 certbot 或 acme.sh 自动续期。行业已通过分阶段缩短方案,2026 年起上限将进一步压缩到 200 天以内并继续下调,所以“一次性买三年”早已不可行,自动化续期是必选项。自建 CA 的私有证书不受此限制,但仍建议控制在 397 天以内并做好轮换,避免客户端缓存与合规审计问题。

方案三:内网自建 CA,签发 IP 证书并在 Node 中注入信任

这是内网 IP 直连最现实的做法,全流程四条命令。第一步建根 CA(私钥务必离线保管):

openssl genrsa -out ca.key 4096
openssl req -x509 -new -nodes -key ca.key -sha256 -days 3650 -out ca.crt 
  -subj '/C=CN/O=Example Inc/CN=Example Internal Root CA' 
  -addext 'basicConstraints=critical,CA:TRUE,pathlen:0' 
  -addext 'keyUsage=critical,keyCertSign,cRLSign'

第二步签发服务器证书,复用上一节的 san.cnf:

openssl x509 -req -in server.csr 
  -CA ca.crt -CAkey ca.key -CAcreateserial 
  -out server.crt -days 397 -sha256 
  -extfile san.cnf -extensions v3_req

openssl verify -CAfile ca.crt server.crt
# server.crt: OK

-days 397 别超过 398,这是私有证书也建议遵守的行业惯例。第三步让 Node 信任。三种方式按场景选:

a) 环境变量(追加到默认根证书,最省事):NODE_EXTRA_CA_CERTS=/etc/ssl/example-ca.crt node app.js。注意只在进程启动时读取一次;是追加不是替换;路径写错 Node 会直接启动失败。

b) 请求级 ca 选项:

const https = require('https');
const fs = require('fs');

https.get('https://10.0.0.12/health', {
  ca: fs.readFileSync('/etc/ssl/example-ca.crt'),
  servername: '10.0.0.12',
}, (res) => { console.log(res.statusCode); res.resume(); });

c) undici/fetch:new Agent({ connect: { ca: fs.readFileSync('/etc/ssl/example-ca.crt') } }),配合 setGlobalDispatcher 或按请求传 dispatcher。

本地开发更推荐 mkcert,它会自动生成含 127.0.0.1、::1 的 SAN 并安装本地根证书:

mkcert -install
mkcert 127.0.0.1 ::1 localhost api.local
# 生成 127.0.0.1+3.pem / 127.0.0.1+3-key.pem

切勿用 NODE_TLS_REJECT_UNAUTHORIZED=0 绕过。Node 会打印警告,且它是进程级全局开关,等于把同进程内所有出站 HTTPS 的证书校验全部关掉,风险远大于收益。同理,不要在生产镜像里长期保留这个变量。

配置示例:https / axios / undici 与自定义 checkServerIdentity

下面是可直接粘贴运行的三种客户端写法,共同点是“显式信任私有 CA”,而不是关校验。

// 1) 原生 https:只信任私有 CA,并打印对端 SAN 便于排查
const https = require('https');
const fs = require('fs');

const agent = new https.Agent({
  ca: fs.readFileSync('/etc/ssl/example-ca.crt'),
  keepAlive: true,
  minVersion: 'TLSv1.2',
});

https.get('https://10.0.0.12:8443/health', { agent }, (res) => {
  console.log(res.statusCode, res.socket.getPeerCertificate().subjectaltname);
  res.resume();
}).on('error', (e) => console.error(e.code, e.message));
// 2) axios:通过 httpsAgent 注入 CA
const axios = require('axios');
const https = require('https');
const fs = require('fs');

const client = axios.create({
  baseURL: 'https://10.0.0.12:8443',
  httpsAgent: new https.Agent({ ca: fs.readFileSync('/etc/ssl/example-ca.crt') }),
  timeout: 5000,
});
// 3) 自定义校验:保留标准 SAN 校验,再叠加业务白名单
const tls = require('tls');

function checkIdentity(expected) {
  return (hostname, cert) => {
    const err = tls.checkServerIdentity(expected, cert); // 仍做标准 SAN 比对
    if (err) return err;
    if (cert.subject && cert.subject.OU !== 'platform') {
      return new Error('unexpected certificate OU: ' + cert.subject.OU);
    }
    return undefined; // 返回 undefined 才表示通过
  };
}

要点清单:checkServerIdentity 返回 Error 即失败,返回 undefined 才通过,抛异常同样失败;该回调在证书链校验之后执行,不能替代 ca;通配符 *.example.com 只匹配一级子域,不匹配 example.com 本身,也不匹配 a.b.example.com;IP SAN 比对是规范化后逐字节匹配,::1 与 0:0:0:0:0:0:0:1 视为相同;fetch(undici)不支持在请求选项里传 checkServerIdentity,必须走 Agent 的 connect。另外,若同时需要访问公网 HTTPS,ca 选项是替换而非追加,需自行拼接系统根证书,此时优先用 NODE_EXTRA_CA_CERTS。

方案对比表格:四种做法怎么选

选型只看三个变量:IP 是否公网可达、能否控制 DNS、客户端能否分发根证书。下表把成本与维护量摊开对比。

方案 适用场景 证书来源 有效期 Node 侧改动 成本与维护
域名 + 公共证书(首选) 公网服务、DNS 可控 Let’s Encrypt / DigiCert 90 天 / 最长 398 天 无,默认信任 低,需自动续期
公网 IP SAN 商业证书 必须 IP 直连公网 少数商业 CA ≤ 398 天 无 高,按 IP 计价 + 归属证明
内网自建 CA K8s、私有 IP、微服务互调 自建 OpenSSL CA 自定,建议 ≤ 397 天 NODE_EXTRA_CA_CERTS 或 ca 中,需分发根证书并轮换
mkcert 本地开发 127.0.0.1 / localhost 调试 本地根 CA 默认 2 年以上 无需改动 低,仅限开发机

信任配置方式也要分清作用域,配错就会出现“本地好了线上还报错”:

配置方式 作用范围 追加还是替换 备注
NODE_EXTRA_CA_CERTS 整个进程 追加 启动时读一次,路径错误直接启动失败
https.Agent({ ca }) 该 Agent 的请求 替换默认根 需访问公网时要自行拼接系统根证书
undici Agent connect.ca 该 dispatcher 替换 fetch 场景必须用这个
NODE_TLS_REJECT_UNAUTHORIZED=0 整个进程 关闭校验 禁止用于生产,会打印警告

再强调两个时间事实,避免沿用旧资料:公共 TLS 证书最长有效期是 398 天,不是 825 天;Let’s Encrypt 是 90 天,不是 1 年。两者都要求把续期写进流水线,用 certbot renew --deploy-hook 'nginx -s reload' 或 acme.sh 的 --reloadcmd 完成热加载。如果内网自建 CA 的根证书计划长期使用,建议同时维护 CRL 或改用 step-ca 这类支持 ACME 的内部 CA,把“发证 + 续期 + 轮换”自动化,否则两年后必然出现一批同时过期的节点。

常见错误排查:从真实报错定位到具体原因

下面这些报错在 Node 项目里出现频率最高,按“报错原文 → 原因 → 处理”对照即可。

报错 原因 处理
ERR_TLS_CERT_ALTNAME_INVALID: Hostname/IP does not match certificate's altnames: IP: 10.0.0.12 is not in the cert's list: DNS:api.example.com 证书无该 IP SAN 改域名访问,或重签含 IP SAN 的证书
SAN 里明明有该域名,仍报 ALTNAME_INVALID SNI 未正确发送,服务端返回默认站点证书 设置 servername;Nginx 配 default_server 兜底
UNABLE_TO_VERIFY_LEAF_SIGNATURE / SELF_SIGNED_CERT_IN_CHAIN 缺中间证书,链不完整 ssl_certificate 指向 fullchain.pem
DEPTH_ZERO_SELF_SIGNED_CERT 自签证书未被信任 加 ca 选项或 NODE_EXTRA_CA_CERTS
CERT_HAS_EXPIRED / CERT_NOT_YET_VALID 证书过期,或容器系统时间偏差 openssl x509 -noout -dates,并检查 date -u
TypeError: fetch failed 且看不到原因 真实错误被包在 cause 里 打印 e.cause.code 与 e.cause.message

两个高频坑值得单独说明。其一,走企业代理时,代理会做 MITM 换发自签证书,SAN 是代理的域名,于是报 ALTNAME_INVALID——此时要么把代理根证书加进 ca,要么把内网域名写进 NO_PROXY。其二,Node 18+ 的 fetch 报 TypeError: fetch failed 时,真正的 ERR_TLS_CERT_ALTNAME_INVALID 藏在 error.cause 里,只打印外层信息会误判成网络问题。

标准排查命令,一次看全 subject、issuer、SAN 和有效期:

openssl s_client -connect 10.0.0.12:8443 -servername 10.0.0.12 -showcerts </dev/null 2>/dev/null 
  | openssl x509 -noout -subject -issuer -dates -ext subjectAltName

openssl verify -CAfile /etc/ssl/example-ca.crt -untrusted intermediate.pem server.crt

效果验证:三条命令确认修复到位

改完不要只看“接口通了”,要确认走的确实是可信 TLS。第一,openssl 看握手结果,期望 Verify return code: 0 (ok):

openssl s_client -connect 10.0.0.12:8443 -servername 10.0.0.12 
  -CAfile /etc/ssl/example-ca.crt </dev/null 2>/dev/null 
  | grep -E 'Verify return code|subject='

第二,curl 交叉验证证书校验路径:

curl --cacert /etc/ssl/example-ca.crt https://10.0.0.12:8443/health -sv 2>&1 
  | grep -E 'SSL certificate verify|subjectAltName'

第三,用 Node 自己确认,直接读 socket.authorized 与 authorizationError,这比看业务日志准确得多:

const tls = require('tls');
const fs = require('fs');

const s = tls.connect({
  host: '10.0.0.12', port: 8443, servername: '10.0.0.12',
  ca: fs.readFileSync('/etc/ssl/example-ca.crt'),
}, () => {
  console.log('authorized:', s.authorized);
  console.log('authorizationError:', s.authorizationError);
  console.log('peer SAN:', s.getPeerCertificate().subjectaltname);
  s.end();
});

期望输出 authorized: true、authorizationError: null,且 peer SAN 里能看到目标 IP。若 authorized 为 false,authorizationError 会直接给出原因字符串,比业务层报错更早暴露问题。

上线前再补三步。一是用 testssl.sh --severity HIGH https://10.0.0.12:8443 或 SSL Labs 扫一遍协议与套件;二是把到期监控接进 cron:openssl x509 -in server.crt -noout -checkend 2592000(30 天内到期返回非 0),配合告警;三是回归检查探活配置,确认 K8s 的 httpGet 探针、容器 healthcheck、负载均衡后端地址都已从 IP 改成域名或已注入 CA,避免“代码修好了、探针还在报错”的假性复发。

常见问题

因为 Node 会把 URL 里的 host(这里是 IP)与证书 SAN 中的 IP 地址逐项比对,而公共 CA 不会为内网或未验证的公网 IP 签发 IP SAN,比对必然失败。Node 15 起不再回退校验 CN 字段,所以只要 SAN 里没有该 IP,就一定抛这个错。

可以。给 https.request 传自定义 checkServerIdentity,让它在链校验通过后返回 undefined,或用 tls.checkServerIdentity(‘域名’, cert) 换一个期望值。证书链、有效期仍然校验,风险可控,但只建议在 IP 固定、证书已知的内网场景使用。

能给公网 IP 签,但只有少数商业 CA 提供该产品,需要提交 IP 归属证明,按 IP 数量计价,有效期同样受 398 天上限约束。内网地址如 10/8、192.168/16、127.0.0.1 任何公共 CA 都不会签发,只能自建 CA。

大概率是 SNI 没发对。用 IP 连接且未设置 servername 时,服务端返回默认站点证书,那张证书的 SAN 是别的域名。用 openssl s_client 分别加和不加 -servername 对比 subject 即可确认,修复方式是设 servername 或配置 default_server。

Let’s Encrypt 签发的证书有效期为 90 天,官方推荐用 certbot 或 acme.sh 自动续期。它只对域名签发,不支持 IP SAN,所以内网 IP 直连场景只能自建 CA 或使用 mkcert 生成含 IP SAN 的本地证书。

不能。*.example.com 只匹配一级子域,不匹配 example.com 本身,也不匹配 a.b.example.com,更不匹配任何 IP 地址。IP 必须在 SAN 中以 iPAddress 类型显式列出,并按规范化形式逐字节匹配。