解决openapi-typescript中自签名证书验证问题

在使用openapi-typescript工具生成TypeScript类型定义时，如果API端点使用了自签名HTTPS证书，开发者可能会遇到DEPTH_ZERO_SELF_SIGNED_CERT错误。本文将详细介绍这一问题的背景、原因及解决方案。

问题背景

当开发者尝试从使用自签名HTTPS证书的OpenAPI端点生成类型定义时，Node.js的默认安全设置会阻止这种连接，抛出DEPTH_ZERO_SELF_SIGNED_CERT错误。这种情况常见于开发环境，特别是当API服务运行在本地或内网时。

错误原因分析

Node.js的TLS/SSL模块默认会验证服务器证书的有效性。自签名证书由于不是由受信任的证书颁发机构(CA)签发，无法通过验证，导致连接被拒绝。这是Node.js的安全机制，旨在防止中间人攻击。

解决方案

在开发环境中，可以通过临时禁用Node.js的证书验证来解决这个问题。具体方法如下：

1. 设置环境变量NODE_TLS_REJECT_UNAUTHORIZED=0，这会告诉Node.js跳过TLS证书验证
2. 在生成类型定义前设置这个环境变量
3. 生成完成后恢复默认设置

实现示例

创建一个shell脚本来自动化这个过程：

#!/bin/sh

# 从.env文件中读取API端点URL
PUBLIC_API_URL=$(dotenv -p PUBLIC_API_URL)

if [ -z "$PUBLIC_API_URL" ]; then
  echo "请确保.env文件中已设置PUBLIC_API_URL"
  exit 1
fi

echo "临时禁用TLS证书验证..."
export NODE_TLS_REJECT_UNAUTHORIZED=0

# 生成类型定义
openapi-typescript $PUBLIC_API_URL -o src/lib/types/openapi.d.ts

echo "类型定义生成完成"

然后在package.json中添加脚本命令：

{
  "scripts": {
    "generate:types": "sh scripts/generate-types.sh"
  }
}

安全注意事项

1. 此解决方案仅适用于开发环境，切勿在生产环境中禁用证书验证
2. 对于生产环境，应该使用由受信任CA签发的有效证书
3. 如果必须使用自签名证书，可以考虑将证书添加到系统的信任存储中

替代方案

如果不想全局禁用证书验证，可以考虑：

1. 使用HTTP协议进行开发（但现代浏览器对HTTP有限制）
2. 使用工具如mkcert生成本地信任的开发证书
3. 配置Node.js只信任特定的自签名证书

通过以上方法，开发者可以在保证开发便利性的同时，兼顾安全性需求。