如何修复 Axios 自签名证书错误
Axios 自签名证书错误,是指当 Node.js 的 HTTPS 模块拒绝一张并非由受信任证书颁发机构(CA)签发的 SSL 证书时,抛出的运行时错误。它表现为 SELF_SIGNED_CERT_IN_CHAIN、UNABLE_TO_VERIFY_LEAF_SIGNATURE 或 DEPTH_ZERO_SELF_SIGNED_CERT。根本原因几乎总是客户端或服务端缺失或错误的 CA 信任链。
如何修复 Axios 自签名证书错误?
生产环境中的正确修复方法,是通过 httpsAgent 的 ca 选项,把你证书的 PEM 文件加载到 Axios 中——这会显式信任该证书,而不会禁用所有 SSL 验证。仅用于开发时,设置 rejectUnauthorized: false 会完全绕过验证,但这会产生中间人攻击漏洞,绝不能进入生产环境。实现永久修复的最快途径,是用 Let's Encrypt 提供的免费 CA 签名证书替换你的自签名证书。
Node.js 中是什么导致了 Axios 自签名证书错误?
Axios 把 HTTPS 连接委托给 Node.js 内置的 https 模块,该模块会根据受信任证书颁发机构列表验证每张服务器证书。当服务器出示一张自签名证书——而非由 DigiCert 或 Let's Encrypt 等公认 CA 签发的证书时——Node.js 会拒绝握手,Axios 随即抛出以下三种错误代码之一:
- SELF_SIGNED_CERT_IN_CHAIN —— 该证书是自签名的,不在受信任 CA 列表中
- UNABLE_TO_VERIFY_LEAF_SIGNATURE —— 证书链不完整,缺少中间证书
- DEPTH_ZERO_SELF_SIGNED_CERT —— 服务器的证书既是最终实体又是颁发者
这些错误最常出现在本地开发服务器、内部预发布 API 以及证书自动生成而非由 CA 签发的 Docker 容器中。值得注意的是,Axios 与 fetch 在此处表现不同——Node 18+ 中原生 fetch API 同样拒收自签名证书,但其错误消息不同。
如何在开发中临时修复 Axios SSL 错误?
在本地开发期间,针对 Node.js axios certificate verify failed 错误,最快的解决办法是对特定请求禁用证书验证:
const https = require('https'); const axios = require('axios'); const agent = new https.Agent({ rejectUnauthorized: false // 仅用于开发 }); axios.get('https://your-local-api.com', { httpsAgent: agent }) .then(response => console.log(response.data)) .catch(error => console.error(error));
这行得通,但 rejectUnauthorized: false 标志会禁用所有证书验证——意味着你的应用会静默接受过期、已吊销或伪造的证书。作为稍微安全一些的回退方案,你可以在回退之前捕获特定的错误码:
axios.get('https://your-api.com') .catch(error => { if (error.code === 'DEPTH_ZERO_SELF_SIGNED_CERT') { const insecureAgent = new https.Agent({ rejectUnauthorized: false }); return axios.get('https://your-api.com', { httpsAgent: insecureAgent }); } throw error; });
在为 Node.js 开发团队的工作中,最常见的错误是把这种权宜之计提交到共享环境变量文件中——它会在无人察觉的情况下,一直延续到预发布和生产构建中。
你还可以为 Node.js 进程全局设置环境变量:
NODE_TLS_REJECT_UNAUTHORIZED=0 node your-script.js
在 Axios 中禁用 SSL 安全吗?
不安全。
这种做法仅适用于你自己控制的机器上的隔离本地测试。在任何共享、预发布或面向互联网的环境中,它都会造成难以察觉的证书伪造攻击漏洞。
如何在生产环境中修复 Axios SSL 错误?(正确方法)
对于超出 localhost 的任何环境,有两种方法——一种是信任你的特定证书,另一种是永久消除问题。
方案一:把自签名证书加入 Axios 信任库
当你确实需要使用自签名证书时——例如私有网络中的内部微服务——这是正确的修复方法:
const fs = require('fs'); const https = require('https'); const axios = require('axios'); const cert = fs.readFileSync('./certs/your-cert.pem'); const agent = new https.Agent({ ca: cert // 仅信任这张证书 }); axios.get('https://your-internal-api.com', { httpsAgent: agent });
这严格比 rejectUnauthorized: false 更安全,因为它只信任某一张特定证书,而不是接受任何证书。证书文件路径应来自环境变量,而非硬编码字符串。
方案二:替换自签名证书(推荐)
针对 certificate chain 中的 axios self signed certificate 错误,最彻底的解决办法是停止使用自签名证书。Let's Encrypt 签发免费、被所有主流运行时信任的 CA 签名证书:
sudo certbot certonly --standalone -d yourdomain.com
签发后,配置你的服务器使用生成的 fullchain.pem 和 privkey.pem 文件。由于信任链完整,Axios 将不再抛出证书错误。
对于在 Axios 中使用正规 CA 签名证书的情况,你通常根本无需任何配置——Node.js 在所有 ≥12 版本中默认信任 Let's Encrypt 证书。
如何在 React 与 Vite 中修复 Axios 证书错误?
当使用 Vite 开发服务器开发 React 应用时,自签名证书错误会出现在浏览器控制台,因为 Vite 通过其自身的 Node.js 进程代理 API 请求。可通过在 vite.config.js 中配置代理来修复:
export default defineConfig({ server: { proxy: { '/api': { target: 'https://your-api.com', changeOrigin: true, secure: false // 仅对此代理目标禁用证书检查 } } } });
secure: false 选项把证书绕过限定在 Vite 的代理层,而不是整个应用。你的生产构建不受影响,因为 Vite 开发服务器配置不会包含在构建产物中。对于 TypeScript 中 axios ssl error 的比较,修复方式相同——https.AgentOptions 的 TypeScript 类型完全支持 ca 和 rejectUnauthorized 字段。
如何修复 Axios Docker SSL 证书错误?
当 Axios 在 Docker 容器内运行并连接到使用自签名证书的主机时,容器的信任库不包含该证书。解决办法是在构建阶段把 PEM 文件加入容器的 CA 证书包:
COPY ./certs/your-cert.pem /usr/local/share/ca-certificates/your-cert.crt RUN update-ca-certificates
这种方式在系统层面注册证书,因此容器内所有 Node.js 进程(包括 Axios)都信任它,而无需改动任何代码。证书文件必须使用 .crt 扩展名并放在 /usr/local/share/ca-certificates/ 目录中,update-ca-certificates 才能正确处理它。
对于生产环境的 Docker 部署,更好的实践是通过密钥管理器(AWS Secrets Manager、HashiCorp Vault)把正规签发的 CA 签名证书挂载到容器中,而不是把它烘焙进镜像。
如何全局配置 Axios 处理 SSL 证书?
对于向同一自签名端点发出大量 HTTPS 请求的应用,可在 Axios 实例上配置默认 httpsAgent,而不是每个请求都重复配置:
const https = require('https'); const axios = require('axios'); const fs = require('fs'); const agent = new https.Agent({ ca: fs.readFileSync(process.env.SSL_CERT_PATH) }); const apiClient = axios.create({ baseURL: 'https://your-api.com', httpsAgent: agent }); // 来自 apiClient 的所有请求都使用此自定义代理 apiClient.get('/endpoint').then(/* ... */);
使用 process.env.SSL_CERT_PATH 使证书路径在各环境间可配置,无需改动代码。这种模式同样适用于多服务架构中添加自定义 CA 的场景——每个服务都有自己的证书。
从业者笔记
在审查了数十个 Node.js 代码库之后,我发现 rejectUnauthorized: false 一旦添加就很少被移除——它从开发者的笔记本电脑一路经由 CI 进入生产环境,却无人标记,因为应用一直在正常运行。最安全的习惯是把任何出现该标志的情况都视为测试失败条件:写一条 lint 规则或 CI 检查,阻止这种模式合并到任何非开发分支。用 ca 选项显式信任某个特定 PEM 文件只需多写三行代码,就能彻底消除安全风险。有疑问时,花三十分钟获取一张 Let's Encrypt 证书——问题就会永久消失。
最终思考
Axios 自签名证书错误有清晰的修复层级:rejectUnauthorized: false 仅用于隔离的本地测试;当必须在受控环境中信任某张特定自签名证书时,传入显式的 ca 证书;对于任何超出 localhost 可访问的内容,用 CA 签名证书替换自签名证书。httpsAgent 配置模式为你提供精确、限定范围的控制,而无需全局禁用安全性。
每个发出 HTTPS 请求的生产 Node.js 应用,都应在部署前验证其证书链。
常见问题(FAQ)
什么是 Axios 自签名证书错误,为什么会发生?
当 Node.js 的 HTTPS 模块无法根据受信任 CA 验证服务器的 SSL 证书时,Axios 就会抛出自签名证书错误。
错误代码包括 SELF_SIGNED_CERT_IN_CHAIN、DEPTH_ZERO_SELF_SIGNED_CERT 和 UNABLE_TO_VERIFY_LEAF_SIGNATURE。它发生在证书自生成而非由 Let's Encrypt 或 DigiCert 等公认 CA 签发的开发服务器、内部 API 和预发布环境中。
如何在本地测试中禁用 Axios 的 SSL 验证?
把 { httpsAgent: new https.Agent({ rejectUnauthorized: false }) } 作为配置选项传给你的 Axios 请求,或在运行 Node.js 进程前设置 NODE_TLS_REJECT_UNAUTHORIZED=0 环境变量。
两种方法都会绕过所有证书验证,必须严格限制在本地开发中使用——绝不要提交到预发布或生产配置。
在 Axios 中设置 rejectUnauthorized false 安全吗?
不安全。
设置 rejectUnauthorized: false 会完全禁用证书验证,使你的应用接受任何证书——包括伪造、过期或已吊销的证书。这会为中间人攻击制造直接途径。仅在你控制的本地机器上、连接你自己的服务器时使用。
Axios 中的 UNABLE_TO_VERIFY_LEAF_SIGNATURE 错误是什么?
此错误表示服务器的 SSL 证书存在,但 Axios 无法验证其颁发者,因为证书链中缺少中间 CA 证书。
服务器只出示了最终实体证书,而非完整证书链。解决办法是配置服务器提供完整证书包——通常是 fullchain.pem 文件——而不只是域名证书。
如何向 Axios 添加自定义 CA 证书?
用 fs.readFileSync('./your-cert.pem') 读取 PEM 文件,并把它传给 https.Agent 的 ca 字段:new https.Agent({ ca: certBuffer })。
通过 httpsAgent 把这个代理附加到你的 Axios 配置。这会指示 Node.js 信任那张特定证书,同时继续对所有其他 HTTPS 连接强制执行验证。
为什么 Axios 特别显示 DEPTH_ZERO_SELF_SIGNED_CERT?
当深度为零的证书(服务器自身的证书)既是最终实体又是其自身的颁发者时,就会出现 DEPTH_ZERO_SELF_SIGNED_CERT。
换句话说,证书链只有一张证书,且它是自签名的。这正是 mkcert 等开发工具在生成的证书未加入系统或应用信任库时抛出的错误。请检查你受信任的证书颁发机构配置以解决它。