FastAPI本地部署过程中出现WinError 10061连接被拒绝错误，本质是客户端尝试连接本地服务时，目标地址和端口没有对应的服务在监听，导致连接请求被系统直接拒绝。这个错误在Windows环境下部署FastAPI时较为常见，需要从服务启动、网络配置、系统环境多个维度排查。
常见错误触发场景
开发者在本地运行FastAPI应用后，使用浏览器、Postman或者脚本请求接口时，突然弹出包含WinError 10061的报错信息，常见的请求场景包括访问接口文档地址、调用业务接口等。比如执行下面的测试请求代码时就会触发该错误：
import requests
# 尝试访问本地FastAPI接口
try:
resp = requests.get("http://127.0.0.1:8000/docs")
print(resp.status_code)
except Exception as e:
print(f"请求出错: {e}")
具体排查与解决步骤
1. 确认FastAPI服务是否正常启动
首先要检查服务启动过程有没有异常，很多时候是服务启动失败导致没有监听端口。正常的FastAPI启动命令如下，启动后终端会输出监听地址和端口信息：
# 使用uvicorn启动FastAPI应用，app是文件名，app是FastAPI实例名 uvicorn app:app --host 127.0.0.1 --port 8000 --reload
如果启动时出现模块导入错误、语法错误等问题，需要先修复代码问题，确保服务能够正常启动，终端显示类似Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)的提示才说明服务启动成功。
2. 检查监听地址和端口是否匹配
如果服务启动正常，需要确认请求的地址和端口和服务监听的配置完全一致。默认情况下uvicorn监听127.0.0.1:8000，如果启动时修改了host或者port参数，请求的时候也要同步修改。比如启动时指定了端口为8080：
uvicorn app:app --host 0.0.0.0 --port 8080
那么请求的时候就需要访问http://127.0.0.1:8080或者http://本地IP:8080，如果还是用8000端口请求就会出现连接被拒绝的错误。
3. 排查端口占用问题
如果配置的端口被其他程序占用，FastAPI服务可能无法正常监听该端口，或者启动后实际没有绑定到目标端口。可以通过命令查看端口占用情况：
# Windows查看8000端口占用情况 netstat -ano | findstr ":8000"
如果查询到有进程占用了目标端口，可以选择关闭占用端口的进程，或者修改FastAPI启动的端口，比如换成8001端口重新启动服务。
4. 检查防火墙设置
如果服务监听的是0.0.0.0地址，需要确认Windows防火墙没有拦截该端口的入站连接。可以暂时关闭防火墙测试，如果关闭后能够正常连接，就需要在防火墙入站规则中新增对应端口的允许规则，开放FastAPI使用的端口。
验证解决效果
完成上述排查操作后，重新启动FastAPI服务，再用之前的请求代码测试，如果能够正常返回200状态码或者接口文档页面，说明WinError 10061错误已经解决。如果还是存在问题，可以检查是否有代理软件拦截了本地请求，或者尝试重启电脑后再次测试。
FastAPIWinError_10061本地部署连接被拒绝端口占用修改时间：2026-06-09 03:42:21