Test-NetConnection Guide: Ports and TroubleshootingTest-NetConnection 完整指南：端口测试、网络诊断、结果解读、安全验证与故障排查

What is Test-NetConnection?什么是 Test-NetConnection？

The command is valuable because it preserves context that a bare success/failure check omits. A result can show which IP address DNS selected, which local interface and source address Windows chose, and whether ICMP and TCP outcomes differ. Those distinctions help prevent changes to the wrong firewall, DNS zone, or database server.该命令的价值在于保留了简单成功/失败检查会丢失的上下文：它能显示 DNS 选择的 IP、Windows 使用的本地网卡与来源地址，以及 ICMP 和 TCP 结果是否不同。这些差异有助于避免修改错误的防火墙、DNS Zone 或数据库服务器。

Test-NetConnection syntax for TCP port testing用于 TCP 端口测试的 Test-NetConnection 语法

Basic Test-NetConnection port example基础 Test-NetConnection 端口示例

Test-NetConnection -ComputerName db.example.internal -Port 5432

Replace the sanitized host and port with an endpoint you are authorized to test. Run the command from the same subnet, VM, jump host, or administrative context used by the application whenever possible. Testing from a laptop can follow different DNS, VPN, proxy, security-group, and egress paths.请把脱敏主机与端口替换成你获准测试的端点。应尽量从应用使用的同一子网、虚拟机、跳板机或管理上下文运行命令。从个人电脑测试时，DNS、VPN、代理、安全组和出站路径可能完全不同。

Test-NetConnection with detailed output使用详细输出的 Test-NetConnection

Test-NetConnection -ComputerName db.example.internal -Port 1433 -InformationLevel Detailed

Detailed output is best for an incident record because it exposes the address and path Windows actually selected. Redact internal hostnames or addresses when sharing outside the authorized troubleshooting group, but retain enough context for another engineer to reproduce the test.详细输出适合用于故障记录，因为它会展示 Windows 实际选择的地址与路径。向授权排障组以外分享时，应隐藏内部主机名或地址，同时保留足够上下文，以便其他工程师复现测试。

Test multiple database ports without treating them as a scanner批量测试数据库端口，但不要把命令当成扫描器

$ports = 1433, 3306, 5432, 1521
$ports | ForEach-Object {
  Test-NetConnection -ComputerName db.example.internal -Port $_ -InformationLevel Quiet
}

Use a small, explicit allowlist of expected ports and obtain authorization. A broad port range test changes the activity from targeted troubleshooting toward scanning, creates noisy evidence, and may violate policy. The built-in cmdlet tests one TCP port per invocation; automation should preserve the host, source, timestamp, port and purpose for each result.只应使用小范围、明确列出的预期端口，并提前获得授权。大范围端口测试会从定向排障转变为扫描，产生大量噪声，也可能违反安全策略。该命令每次调用测试一个 TCP 端口；自动化结果应保留主机、来源、时间、端口和测试目的。

How to read Test-NetConnection results如何解读 Test-NetConnection 结果

Can PingSucceeded be False while TcpTestSucceeded is True?PingSucceeded 为 False、TcpTestSucceeded 为 True 正常吗？

Yes. Ping uses ICMP, while -Port attempts TCP. Many networks block or deprioritize ICMP without blocking the application port. In that case, a ping warning does not invalidate a successful TCP result. Interpret each field according to its protocol and the question you are answering.正常。Ping 使用 ICMP，而 -Port 尝试 TCP。很多网络会阻止或降低 ICMP 优先级，但仍允许应用端口。因此 Ping 警告不会推翻成功的 TCP 结果。应根据各字段对应协议和当前问题分别解读。

Fix TcpTestSucceeded False with evidence, not guesses用证据排查 TcpTestSucceeded False，而不是猜测

What does TcpTestSucceeded False mean?TcpTestSucceeded False 表示什么？

It means the TCP connection attempt did not complete. It does not identify the cause by itself. The failure may occur before the target, at the target, or because the test selected an unexpected address or route. Record the complete output and the source context before changing configuration.它表示 TCP 连接尝试未完成，但不能单独说明原因。故障可能发生在到达目标之前、目标端，也可能因为测试选择了非预期地址或路由。修改配置前，应记录完整输出和来源上下文。

TcpTestSucceeded False troubleshooting sequenceTcpTestSucceeded False 排障顺序

1. Verify the target核对目标Confirm environment, hostname, actual listener port, protocol, and whether the endpoint is private, public, proxy, pooler, writer, or reader.确认环境、主机名、实际监听端口、协议，以及端点属于私网、公网、代理、连接池、写入还是只读。
2. Inspect name resolution检查名称解析Compare RemoteAddress with the intended endpoint. Test from the application environment because split DNS and VPN state can change the answer.把 RemoteAddress 与预期端点对比。由于 Split DNS 和 VPN 状态会改变解析结果，应从应用环境测试。
3. Inspect source and route检查来源与路由Check InterfaceAlias, SourceAddress, route table, VPN, subnet peering, private link, proxy, and return route.检查 InterfaceAlias、SourceAddress、路由表、VPN、子网对等连接、Private Link、代理与返回路由。
4. Check policy boundaries检查策略边界Review egress rules, network ACLs, security groups, host firewall, endpoint allowlists, and network appliances for the exact source and destination port.针对准确来源和目标端口，检查出站规则、网络 ACL、安全组、主机防火墙、端点白名单和网络设备。
5. Check the listener检查监听器Confirm the service is running and bound to the intended interface and port. A database can be healthy locally while not listening on a remotely reachable address.确认服务正在运行，并绑定预期网卡与端口。数据库可能在本机健康，但没有监听远程可达地址。

TcpTestSucceeded False but the application worksTcpTestSucceeded False 但应用仍可用的原因

The test and application may use different hosts, ports, proxies, DNS answers, IP families, source networks, or timing. The application may reuse an existing pooled connection while a new connection is blocked. Capture the application's effective endpoint and run the test inside the same workload context before concluding that the command is wrong.测试与应用可能使用不同主机、端口、代理、DNS 结果、IP 协议族、来源网络或时间窗口。应用也可能复用已有连接池会话，而新连接已经被阻止。应获取应用的实际端点，并在同一工作负载上下文中测试，再判断命令结果。

Use Test-NetConnection for database endpoints safely安全地使用 Test-NetConnection 测试数据库端点

Test-NetConnection is useful for PostgreSQL, MySQL, SQL Server, Oracle, MongoDB and other TCP endpoints because it does not need a username or password. Extract the authorized host and actual port from provider connection details or a sanitized connection URL. Do not assume a default when the environment uses a proxy, named instance, pooler, SSH tunnel, container mapping, or managed-service gateway.Test-NetConnection 不需要用户名或密码，因此适合测试 PostgreSQL、MySQL、SQL Server、Oracle、MongoDB 等 TCP 端点。应从供应商连接详情或脱敏连接 URL 中提取获准主机与实际端口。如果环境使用代理、命名实例、连接池、SSH 隧道、容器映射或托管服务网关，不要假设默认端口。

Does TcpTestSucceeded True prove the database is ready?TcpTestSucceeded True 能证明数据库就绪吗？

No. It proves only that a TCP handshake completed to a listener on the selected address and port. It does not prove that the listener speaks the expected database protocol, that TLS verifies, that credentials are accepted, that the account can open the requested database, that a health query succeeds, or that the service has production capacity.不能。它只能证明与所选地址和端口上的监听器完成了 TCP 握手，不能证明监听器使用预期数据库协议、TLS 验证通过、凭据有效、账号能打开目标数据库、健康查询成功或服务具备生产容量。

Test-NetConnection, Test-Connection, ping, and telnet differTest-NetConnection、Test-Connection、Ping 与 Telnet 的区别

Can Test-NetConnection test UDP ports?Test-NetConnection 能测试 UDP 端口吗？

No. The -Port parameter performs a TCP connection test. UDP has no TCP-style handshake, and a missing response can mean the service is blocked, silent by design, expecting a specific payload, or absent. Use an authorized protocol-aware client or service-specific health check instead of relabeling a TCP result as UDP evidence.不能。-Port 参数执行 TCP 连接测试。UDP 没有 TCP 式握手，未收到回复可能表示服务被阻止、按设计保持静默、需要特定数据包或根本不存在。应使用获准的协议感知客户端或服务专项健康检查，不能把 TCP 结果当成 UDP 证据。

How do I change the Test-NetConnection timeout?如何修改 Test-NetConnection 超时？

The Windows PowerShell Test-NetConnection cmdlet does not expose the same -TimeoutSeconds parameter available to modern PowerShell Test-Connection. Search results often mix the two commands. Check Get-Command Test-NetConnection -Syntax, $PSVersionTable, and the documentation for the installed version before copying a timeout example.Windows PowerShell 的 Test-NetConnection 没有现代 PowerShell Test-Connection 所提供的同名 -TimeoutSeconds 参数。搜索结果经常混淆两条命令。复制超时示例前，应检查 Get-Command Test-NetConnection -Syntax、$PSVersionTable 与当前安装版本文档。

Create a reproducible Test-NetConnection evidence record建立可复现的 Test-NetConnection 证据记录

• Context: UTC timestamp, Windows and PowerShell version, machine or workload, environment, VPN state, and administrator/non-administrator context.上下文：UTC 时间、Windows 与 PowerShell 版本、机器或工作负载、环境、VPN 状态及是否管理员运行。
• Sanitized target: database/service type, masked hostname when required, intended environment, port, private/public classification, and test authorization.脱敏目标：数据库/服务类型、必要时隐藏的主机名、目标环境、端口、公私网分类与测试授权。
• Observed path: remote address, interface alias, source address, and route or next-hop evidence when relevant.实际路径：远程地址、网卡别名、来源地址，以及必要时的路由或下一跳证据。
• Outcome: ping result, TCP result, duration, exact warning/error, and whether a subsequent TLS, login, or health-query test was attempted.结果：Ping 结果、TCP 结果、耗时、准确警告/错误，以及是否继续进行了 TLS、登录或健康查询测试。
• Comparison: known-good source, first failure time, recent deployment/network changes, intermittent versus constant behavior, and remediation owner.对比：已知正常来源、首次失败时间、近期部署/网络变更、间歇或持续行为，以及修复负责人。

How to automate Test-NetConnection without losing context如何在自动化 Test-NetConnection 时保留上下文

Automation should emit structured records rather than screenshots or colored console text. For every authorized target, store the requested hostname, resolved address, port, source address, interface, Boolean TCP result, timestamp, duration, environment, and run identifier. Limit concurrency so the job does not resemble a port scan or overload a fragile endpoint. Define failure thresholds carefully: one failed attempt can reflect a transient route change, while repeated success does not prove database login or workload health. Protect internal topology in logs, set retention according to policy, and attach the result to a change or incident only after secrets and unnecessary identifiers are removed.自动化应输出结构化记录，而不是截图或带颜色的控制台文本。对每个获准目标，记录请求主机名、解析地址、端口、来源地址、网卡、TCP 布尔结果、时间、持续时长、环境和运行标识。应限制并发，避免任务表现得像端口扫描或压垮脆弱端点。失败阈值要谨慎定义：单次失败可能来自短暂路由变化，而多次成功也不能证明数据库登录或工作负载健康。日志中的内部拓扑应受保护，保留期限应符合策略；只有移除密钥和不必要标识后，结果才能附加到变更或故障记录。

Test-NetConnection FAQTest-NetConnection 常见问题

What does Test-NetConnection do?Test-NetConnection 有什么作用？

It is a Windows PowerShell NetTCPIP cmdlet that provides ping, TCP port, tracing, and route-selection diagnostics depending on its parameters.它是 Windows PowerShell NetTCPIP 命令，可根据参数提供 Ping、TCP 端口、跟踪与路由选择诊断。

How do I test a port with Test-NetConnection?如何用 Test-NetConnection 测试端口？

Run Test-NetConnection -ComputerName <host> -Port <port> -InformationLevel Detailed from the application's network path.从应用网络路径运行 Test-NetConnection -ComputerName <host> -Port <port> -InformationLevel Detailed。

What does TcpTestSucceeded False mean?TcpTestSucceeded False 表示什么？

The TCP attempt did not complete. Investigate target, DNS, source interface, route, policy boundaries, listener state, and timing.TCP 尝试未完成，应检查目标、DNS、来源网卡、路由、策略边界、监听器状态与时间因素。

Can Test-NetConnection test UDP ports?Test-NetConnection 能测试 UDP 端口吗？

No. -Port tests TCP. Use an approved protocol-aware UDP test for the actual service.不能，-Port 测试 TCP；应针对实际服务使用获准的 UDP 协议测试。

How do I set a Test-NetConnection timeout?如何设置 Test-NetConnection 超时？

The Windows PowerShell cmdlet lacks the modern Test-Connection -TimeoutSeconds option. Verify the command and PowerShell version before using examples.Windows PowerShell 版本没有现代 Test-Connection -TimeoutSeconds 选项，应先确认命令与 PowerShell 版本。

Does TcpTestSucceeded True prove a database is working?TcpTestSucceeded True 能证明数据库正常吗？

No. It proves TCP reachability only, not database protocol, TLS, login, permissions, query success, capacity, or reliability.不能。它只证明 TCP 可达，不能证明数据库协议、TLS、登录、权限、查询成功、容量或可靠性。

Continue with a related guide继续阅读相关指南

Use these closely related guides to verify the next layer of the workflow without mixing separate troubleshooting or decision intents.可继续阅读以下紧密相关的指南，验证工作流的下一层，同时避免混淆不同的排障或决策意图。

• Database ports数据库端口
• SQL Server port 1433SQL Server 1433 端口
• MySQL port 3306MySQL 3306 端口

Official Test-NetConnection referencesTest-NetConnection 官方参考资料

• Microsoft Learn: Test-NetConnection (NetTCPIP)
• Microsoft Learn: Test-Connection in PowerShell 7.5
• Microsoft Learn: NetTCPIP module
• Microsoft troubleshooting example using TcpTestSucceeded