使用mssql npm模块同时指定命名实例与端口的连接问题

核心问题解答 #

SQL Server的命名实例与指定端口并非设计上互斥。命名实例默认依赖SQL Browser服务动态获取端口，但管理员可以为命名实例绑定固定端口，此时实例既保留名称标识，又有明确的端口号——你能通过SSMS用“命名实例+端口”连接成功，就是这种配置的直接证明。

mssql模块连接失败的原因 #

mssql模块的文档提示“连接命名实例时请勿设置port”，是因为当你指定命名实例名称时，模块会默认尝试通过SQL Browser服务（UDP 1434端口）解析该实例对应的端口；如果同时手动设置port参数，会触发逻辑冲突，导致连接失败。

可行解决方案 #

方案1：直接使用域名+固定端口连接（推荐，无需依赖SQL Browser） #

放弃指定实例名，直接用目标服务器域名+固定端口配置，同时注意不要给端口号加前导零（JavaScript中0开头的数字会被解析为八进制，01234实际对应十进制的668，这大概率是你连接失败的原因之一）：

{ 
  server: 'servername.com', 
  port: 1234 // 去掉前导零，使用十进制端口号
}

方案2：保留实例名，依赖SQL Browser解析端口 #

如果必须指定实例名，需要满足两个前提：

• 目标服务器上的SQL Browser服务处于运行状态
• 服务器防火墙开放了UDP 1434端口
  此时不要设置port参数，配置如下：

{ 
  server: 'servername.com/namedinstance01'
}

额外排查点 #

• 确认端口号的正确性：联系数据库管理员核实目标实例绑定的固定端口是否为1234
• 检查本地/服务器防火墙：确保你应用所在服务器能访问目标数据库的对应端口（TCP 1234或UDP 1434）

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