node-postgres执行client.connect()抛出Error: timeout expired错误如何解决

• SSL连接配置缺失：这是该场景下最高发的原因。Heroku Postgres、ElephantSQL等云PostgreSQL服务均强制要求客户端使用SSL连接，psql、Postico等桌面工具默认自动开启SSL尝试，而node-postgres默认配置未开启SSL，会在TCP连接建立后卡在SSL握手阶段，直到触发连接超时。
• Node.js环境网络限制：系统防火墙、Node进程配置的全局代理规则可能禁止Node访问数据库的5432端口，而桌面数据库工具被规则放行。
• node-postgres版本兼容性问题：使用8.0以下的老旧版本pg包，存在已知的连接握手逻辑bug，或与当前Node.js版本不兼容。

• 先测试SSL配置有效性：直接在数据库配置中新增SSL参数后重试，确认是否为SSL导致的问题。
• 测试端口连通性：运行如下测试脚本，确认Node环境可以正常访问数据库的5432端口：

const net = require('net')
const client = new net.Socket()
client.connect(5432, 'hattie.db.elephantsql.com', () => {
  console.log('5432端口连通正常')
  client.destroy()
})
client.on('error', err => console.error('5432端口连通失败', err))

• 检查pg包版本：运行npm list pg查看当前安装的版本，若低于8.0建议升级。
• 开启debug日志：执行脚本时添加环境变量NODE_DEBUG=pg,net node 你的脚本文件名.js，查看日志确认是DNS解析异常、TCP连接失败还是TLS握手异常。

1. 补全SSL配置，修改数据库配置项如下：

const postgresOptions = {
  connectionString: 'postgres://REDACTED:REDACTED@hattie.db.elephantsql.com/REDACTED',
  connectionTimeoutMillis: 10000,
  ssl: {
    // 生产环境若需要更高安全性，可配置ca参数传入云服务官方提供的根证书
    rejectUnauthorized: false
  }
}

2. 若为网络代理导致的问题，将数据库域名加入Node的代理忽略列表：

# 临时生效（Mac/Linux）
export NO_PROXY=hattie.db.elephantsql.com,*.db.elephantsql.com,*.amazonaws.com
# Windows Powershell
$env:NO_PROXY = "hattie.db.elephantsql.com,*.db.elephantsql.com,*.amazonaws.com"

3. 升级pg包到最新稳定版：

npm install pg@latest

内容的提问来源于stack exchange，提问作者Tom Söderlund