Docker容器内.NET Core 3.1 Web API连接宿主机SQL Server 2019预登录握手错误

核心问题定位 #

你遇到的问题本质是两个：

1. 宿主机上默认1433端口被另一个SQL Server实例占用，你要访问的SQLSERVER2019命名实例使用的是动态TCP端口，你之前指向1433端口的连接请求实际发到了错误的实例上，导致预登录握手失败
2. WSL2后端的Docker容器默认无法通过实例名解析SQL Server端口，SQL Browser服务的UDP 1434端口流量无法正常穿透WSL2与Windows宿主机的网络边界，所以带实例名的连接字符串会直接报错

解决方案 #

最优解：给SQLSERVER2019实例配置固定端口，直接指定端口连接 #

1. 打开SQL Server配置管理器，依次进入「SQL Server网络配置」→「<实例名>的协议」→ 右键TCP/IP选择属性
2. 切换到「IP地址」标签页，拉到页面最底部的「IPAll」配置段，清空「TCP动态端口」的内容，在「TCP端口」栏填写自定义的固定端口，比如1434，保存配置后重启SQLSERVER2019实例
3. 打开Windows Defender防火墙，添加入站规则，允许TCP 1434端口的入站流量，可单独限定来源为Docker的WSL2网段192.168.65.0/24
4. 连接字符串直接使用固定端口，无需填写实例名：

Server=host.docker.internal,1434;Database=xxx;MultipleActiveResultSets=true;UID=sa;PWD=xxx;Integrated Security=false;TrustServerCertificate=true

注意：通过docker run -e传递连接字符串时，不要用单引号包裹密码、Server字段，避免转义错误导致连接字符串无效。
5. 删除你之前docker run命令中所有-p 1433相关的端口映射参数，-p是将容器端口映射到宿主机，你需要的是容器访问宿主机服务，这类配置完全无用，反而可能导致端口冲突。

备选方案：升级SqlClient版本 #

如果完成上述配置后仍报预登录握手错误，将项目中引用的Microsoft.Data.SqlClient Nuget包升级到最新的2.x稳定版，3.x及以上版本对.NET Core 3.1的兼容性存在已知问题，旧版包对高版本TLS的适配也有bug。

验证步骤 #

你可以先启动一个基础镜像的临时容器，进入容器后用nc -zv host.docker.internal <你配置的固定端口>命令验证端口连通性，确认网络通路正常后再排查应用配置问题。

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