Uvicorn需显式指定--host 0.0.0.0和--port 8080才能对外提供服务，0.0.0.0仅支持IPv4；双栈需--host None或::；禁用--reload上线，优先用命令行而非脚本内uvicorn.run()。
直接用命令行改端口和绑定IP最可靠
Uvicorn 默认监听 127.0.0.1:8000，外部设备无法访问。要改端口或让局域网/公网能连上，必须显式传 --host 和 --port 参数，不能依赖默认值。
-
--host 0.0.0.0表示监听所有 IPv4 接口（包括本机 IP），不是“任意地址”的模糊说法，而是明确的 INADDR_ANY -
--port 8080或--port=8080都行，但不能带引号，比如--port "8080"会报错invalid literal for int() - 如果只写
--port 8080不写--host，它仍会绑定到127.0.0.1:8080，外网还是访问不了 - 完整推荐命令：
uvicorn main:app --host 0.0.0.0 --port 8080
想同时支持 IPv4 和 IPv6？别用 0.0.0.0
0.0.0.0 只管 IPv4，哪怕系统开了 IPv6，::1 或公网 IPv6 地址也连不上。真要双栈，得把 --host 设为 None 或 ::：
-
--host None：Uvicorn 调用getaddrinfo()，自动创建 IPv4 + IPv6 两组 socket（前提：系统未禁用 IPv6，且内核支持IPV6_V6ONLY=0） -
--host ::：只监听 IPv6 所有接口，此时curl http://[::1]:8000能通，但curl http://127.0.0.1:8000会失败 - 验证是否真双栈：
ss -tuln | grep :8000应同时看到*:8000（IPv4）和*:[::]:8000（IPv6）两行
在 Python 脚本里调 uvicorn.run() 容易出问题
很多人在 main.py 末尾写 uvicorn.run("main:app", host="0.0.0.0", port=8000)，看似简洁，但实际埋了坑：
Uvicorn 0.52.1
下载
Uvicorn 0.52.1 是 Python ASGI Web 服务器，提供异步应用服务及 WebSocket 支持，常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包，可使用 pip 安装，并由包管理器处理所需依赖。
- PyCharm、VSCode 的调试器进程模型会干扰
uvicorn的 socket 绑定逻辑，尤其在 Windows 或容器里，--host可能被静默忽略 - 某些 uvicorn 版本（如 0.29.x、0.52.1）对
host=None的处理不一致，脚本内调用时可能 fallback 到 IPv4-only - IDE 的 “Run” 按钮本质是执行
python main.py，而 uvicorn 希望你以模块方式启动：python -m uvicorn main:app ... - 正确做法：删掉脚本里的
uvicorn.run()，一律走终端命令；非要用 IDE 启动，就建 Run Configuration，Module name 填uvicorn，Parameters 填完整参数
生产环境别只改端口，还得关掉开发特性
开发时加 --reload 很方便，但上线后必须去掉——它和 --workers 冲突，且 fork 子进程会导致服务短暂不可用：
-
--reload和--workers不能共存，Uvicorn 启动直接报错 - 生产建议用
--workers 4（CPU 核数 × 2 + 1），配合 Nginx 做反向代理和负载均衡 - 如果用 Gunicorn 管理 Uvicorn Worker，绑定写法完全不同：
--bind 0.0.0.0:8000是 Gunicorn 参数，不是 Uvicorn 的--host/--port - 防火墙、云服务器安全组、Docker
--sysctl设置都得同步检查，光改代码没用
改端口和 IP 看似简单，真正卡住人的往往不是参数名，而是 host 值语义差异、IDE 运行机制、以及 IPv6 在不同环境下的实际行为。动手前先确认你用的是哪种启动方式，再决定参数怎么传。
