问题：Uvicorn启动时报错"uvicorn.error"，如何排查？

Question

**问题描述：** 在使用 Uvicorn 启动 FastAPI 或 ASGI 应用时，控制台输出报错信息 `uvicorn.error`，导致服务启动失败。此类错误通常由配置不当、模块导入失败或端口冲突等原因引起，需结合日志进一步排查。

Answer 1

一、问题概述

在使用 Uvicorn 启动 FastAPI 或 ASGI 应用时，控制台输出报错信息 uvicorn.error，导致服务启动失败。此类错误通常由配置不当、模块导入失败或端口冲突等原因引起，需结合日志进一步排查。

该问题在生产环境或本地调试中都可能出现，尤其是在模块路径错误、依赖未安装、配置参数不匹配等情况下。

二、常见错误场景与日志示例

以下是几种常见的 uvicorn.error 日志输出示例：

• ERROR: [Errno 98] Address already in use —— 端口被占用
• ERROR: No module named 'app' —— 模块导入失败
• ERROR: Invalid ASGI callable —— ASGI 应用对象无效
• ERROR: Could not import module 'main' —— 指定的模块无法加载

三、问题分析流程

为系统性地排查 uvicorn.error 错误，建议按照以下流程进行分析：

graph TD
    A[启动 Uvicorn] --> B{是否出现 uvicorn.error?}
    B -- 是 --> C[查看完整日志]
    C --> D[判断错误类型]
    D --> E[端口冲突/模块导入/配置错误]
    E --> F[根据类型采取对应措施]
    B -- 否 --> G[服务正常启动]

四、常见解决方案

针对不同类型的错误，采取不同的解决策略：

错误类型	可能原因	解决方法
端口冲突	其他进程占用端口	更换端口或终止占用进程
模块导入失败	路径错误或模块未安装	检查模块路径、使用 python -m 启动或安装依赖
配置错误	ASGI 应用对象错误或参数不正确	检查 app 实例、配置参数是否正确

五、进阶调试技巧

对于复杂项目或跨平台部署，建议使用以下调试技巧：

1. 启用 Uvicorn 的 --debug 模式以获取更详细的日志输出
2. 使用 lsof -i :<port>（Linux/macOS）或 netstat（Windows）查看端口占用情况
3. 在 __init__.py 中打印调试信息，确认模块加载路径
4. 使用 py-spy 或 strace 跟踪进程行为
5. 通过 docker 构建隔离环境，复现并排查问题