Node mssql 连接 SQL Server Express 命名实例超时
结论
这个超时多半不在存储过程本身,问题出在 Node 里的 mssql/tedious 没能和 SQL Server Express 命名实例建立网络连接。sqlcmd 能连上,只说明它所在的环境里某种协议可用。如果是在本机连,可能走的是 Shared Memory 或 Named Pipes,这并不能证明远端 TCP、SQL Server Browser 和动态端口都正常。
常见原因按优先级:
- SQL Server Express 命名实例的 TCP/IP 没有启用,或者改完没重启 SQL Server 服务。
- SQL Server Browser 服务没有运行,或者 UDP 1434 被 Windows 防火墙或网络策略挡住,Node 就没法把
SQLEXPRESS01解析成实际 TCP 端口。 - 命名实例使用动态端口,防火墙没有放行该端口。
- 连接参数重复或互相冲突:比如
server里已经带了实例名,却又设置options.instanceName;或者server已经写成带实例名的字符串,instanceName还填着SQLEXPRESS01。 - 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 端口固定下来,再到防火墙放行这个端口。
排查步骤
- 在 SQL Server 主机上打开 SQL Server Configuration Manager,进入
SQL Server Network Configuration->Protocols for SQLEXPRESS01,确认TCP/IP已启用;改完要重启 SQL Server 服务。 - 确认
SQL Server Browser服务在运行。命名实例如果没有固定端口,Node 得靠它查实例端口。 - 查看实例当前 TCP 端口:在 SQL Server Configuration Manager 的
TCP/IP->IP Addresses->IPAll中看TCP Dynamic Ports或TCP Port。如果是动态端口,要么放行该端口,要么改成固定端口。 - 在 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 是否启用和端口监听。
备注:内容仅供参考。
