使用Knex连接Node.js后端与MSSQL数据库时出现连接错误

问题描述 #

• 克隆3个月前可正常运行的Node.js后端仓库，本地部署后调用接口时，无法连接本地及远程MSSQL数据库，抛出连接错误
• 使用完全相同的凭据，通过Microsoft SQL Server Management Studio（MSSM）可正常连接目标数据库
• 已尝试的无效操作：
  • 升级所有项目依赖至最新版本
  • 启用SQL Server的TCP/IP协议
  • 更换远程MSSQL服务器测试
  • 在不同机器部署并调用接口

附相关截图：

• 本地/远程数据库连接错误截图
• 项目依赖截图
• Tedious连接配置对象截图
• 环境变量（.env文件）截图

排查与解决步骤 #

1. 核对Tedious连接配置细节 #

逐一确认配置项，避免细节遗漏：

• server字段：本地数据库需明确指定实例名（如.\SQLEXPRESS）、localhost或127.0.0.1，MSSM自动识别的实例名Tedious无法直接复用
• port字段：默认TCP端口为1433，命名实例需确认实际监听端口（SQL Server配置管理器→SQL Server网络配置→实例名→TCP/IP→IP地址→TCP端口）
• authentication.type：SQL Server身份验证设为'default'并提供userName/password；Windows身份验证设为'ntlm'
• 强制开启options.enableArithAbort: true，部分SQL Server环境依赖此选项
• 远程自签名证书服务器需添加options.trustServerCertificate: true，避免证书验证失败

示例正确配置（SQL Server身份验证）：

const config = {
  server: process.env.DB_SERVER,
  port: parseInt(process.env.DB_PORT),
  authentication: {
    type: 'default',
    options: {
      userName: process.env.DB_USER,
      password: process.env.DB_PASS
    }
  },
  options: {
    database: process.env.DB_NAME,
    trustServerCertificate: true,
    enableArithAbort: true,
    connectTimeout: 30000
  }
};

2. 验证环境变量加载正确性 #

• 确认.env变量名与代码读取逻辑完全匹配（注意大小写）
• 在代码中添加日志，打印实际读取的配置值，排查空值或错误赋值：

console.log('实际加载的DB配置:', {
  server: process.env.DB_SERVER,
  port: process.env.DB_PORT,
  user: process.env.DB_USER,
  database: process.env.DB_NAME
});

3. 检查SQL Server权限与状态 #

• 在MSSM中确认登录账号未被锁定/禁用，且拥有目标数据库的连接权限
• 检查服务器是否启用混合模式身份验证（右键服务器→属性→安全性→勾选“SQL Server和Windows身份验证模式”）
• 查看SQL Server错误日志（MSSM→管理→SQL Server日志），提取具体登录失败原因（如权限不足、账号错误）

4. 排查网络与防火墙问题 #

• 本地数据库：检查Windows防火墙是否允许SQL Server监听端口通过
• 远程数据库：用telnet 远程IP 端口或Test-NetConnection 远程IP -Port 端口测试端口连通性，确认远程防火墙开放对应端口
• 命名实例未指定固定端口时，需确保UDP 1434端口（SQL Server浏览器服务）开放

5. 核对Tedious版本兼容性 #

最新版Tedious可能与旧版SQL Server存在兼容问题：

• 回退到3个月前项目使用的Tedious版本（查看历史提交的package.json）
• 参考Tedious官方文档，确认目标SQL Server版本对应的兼容版本范围

6. 捕获详细错误信息 #

在代码中添加完整错误日志，精准定位问题：

const connection = new Connection(config);
connection.on('connect', (err) => {
  if (err) {
    console.error('连接错误详情:', JSON.stringify(err, null, 2));
    console.error('错误堆栈:', err.stack);
    return;
  }
  // 连接成功逻辑
});

常见错误代码对应问题：

• ECONNREFUSED：端口未开放或服务器未监听
• LOGIN_FAILED：账号密码错误或权限不足
• CERTIFICATE_VERIFY_FAILED：证书验证失败，需开启trustServerCertificate

内容的提问来源于stack exchange，提问作者Dasith Rathnasinghe