PAYATHON 2026

Node mssql 连接 SQL Server Express 命名实例超时

数据小陈

结论

这个超时多半不在存储过程本身,问题出在 Node 里的 mssql/tedious 没能和 SQL Server Express 命名实例建立网络连接。sqlcmd 能连上,只说明它所在的环境里某种协议可用。如果是在本机连,可能走的是 Shared Memory 或 Named Pipes,这并不能证明远端 TCP、SQL Server Browser 和动态端口都正常。

常见原因按优先级:

  1. SQL Server Express 命名实例的 TCP/IP 没有启用,或者改完没重启 SQL Server 服务。
  2. SQL Server Browser 服务没有运行,或者 UDP 1434 被 Windows 防火墙或网络策略挡住,Node 就没法把 SQLEXPRESS01 解析成实际 TCP 端口。
  3. 命名实例使用动态端口,防火墙没有放行该端口。
  4. 连接参数重复或互相冲突:比如 server 里已经带了实例名,却又设置 options.instanceName;或者 server 已经写成带实例名的字符串,instanceName 还填着 SQLEXPRESS01。
  5. Node 所在机器到 SQL Server 主机的 TCP 端口不通。如果是认证失败,一般会直接报登录错误,不会拖到 15000ms 才报 ETIMEOUT。

推荐连接写法

下面两种写法选一种即可。

方式 A:主机名 + 实例名,依赖 SQL Server Browser

import sql from 'mssql';

const config: sql.config = {
  user: process.env.ServiceAccountUsername,
  password: process.env.ServiceAccountPassword,
  server: 'MyServerName', // 只写主机名或 IP,不要在这里再拼示例名
  database: 'DB1',
  connectionTimeout: 30000,
  requestTimeout: 30000,
  options: {
    instanceName: 'SQLEXPRESS01',
    encrypt: true,
    trustServerCertificate: true,
  },
};

export async function connect() {
  return await sql.connect(config);
}

用这种方式时,SQL Server Browser 必须处于运行状态,防火墙要放行 UDP 1434,还要放行实例实际使用的 TCP 端口。

方式 B:主机名 + 固定 TCP 端口,推荐用于远程连接

import sql from 'mssql';

const config: sql.config = {
  user: process.env.ServiceAccountUsername,
  password: process.env.ServiceAccountPassword,
  server: 'MyServerName',
  port: 1433, // 换成 SQL Server 实际固定端口
  database: 'DB1',
  connectionTimeout: 30000,
  requestTimeout: 30000,
  options: {
    encrypt: true,
    trustServerCertificate: true,
  },
};

export async function connect() {
  return await sql.connect(config);
}

固定端口后就别再设 options.instanceName 了,免得两套解析逻辑混在一起。SQL Server Express 命名实例最好在 SQL Server Configuration Manager 里把 TCP 端口固定下来,再到防火墙放行这个端口。

排查步骤

  1. 在 SQL Server 主机上打开 SQL Server Configuration Manager,进入 SQL Server Network Configuration -> Protocols for SQLEXPRESS01,确认 TCP/IP 已启用;改完要重启 SQL Server 服务。
  2. 确认 SQL Server Browser 服务在运行。命名实例如果没有固定端口,Node 得靠它查实例端口。
  3. 查看实例当前 TCP 端口:在 SQL Server Configuration Manager 的 TCP/IP -> IP Addresses -> IPAll 中看 TCP Dynamic Ports 或 TCP Port。如果是动态端口,要么放行该端口,要么改成固定端口。
  4. 在 Node 所在机器上测试端口连通性。Windows 可用:
Test-NetConnection MyServerName -Port 1433

如果使用动态端口,把 1433 换成实际端口。测试 UDP 1434 时可用 telnet、nc 或端口扫描工具,Test-NetConnection 对 UDP 支持不直观。 5. 在 Node 所在机器上用强制 TCP 的 sqlcmd 再试一次:

sqlcmd.exe -S tcp:MyServerName,1433 -d DB1 -U User1 -P Password1 -Q 'select 1'

如果这里也超时,说明问题出在 SQL Server 网络、端口或防火墙,不在 Node 代码。 6. 检查 server 参数。推荐 server: 'MyServerName' 加 options.instanceName: 'SQLEXPRESS01',或者 server: 'MyServerName' 加 port: 1433。不要把主机名和实例名拼成同一个字符串后又设置 instanceName。 7. 如果连接错误从 ETIMEOUT 变成登录失败,再检查 SQL 登录是否启用、是否开启混合身份验证、账号是否有 DB1 权限。超时阶段一般还没走到权限校验。

代码注意事项

  • 别在全局 config 上反复改 server、database、options.instanceName 后复用连接池,多个请求并发时容易互相污染。建议每次按参数生成新配置,或者启动时创建固定连接池。
  • encrypt: true 配 trustServerCertificate: true 适合自签名证书的测试环境;生产环境应换可信证书,并谨慎使用 trustServerCertificate。
  • connectionTimeout 只是等待上限,解决不了连接问题。先把端口和实例解析弄通,再把超时时间调大用于诊断。
  • 如果 Web 服务和 SQL Server 在同一台机器上,可先用 server: '127.0.0.1' 或 localhost 验证本机 TCP;如果本机 TCP 也不通,优先查 TCP/IP 是否启用和端口监听。

备注:内容仅供参考。