Windows系统下Uvicorn彩色终端输出无法正常生效如何解决

问题现象 #

• Python环境安装fastapi框架时，执行pip install "fastapi[all]"完成全量依赖安装，期望通过Uvicorn正常运行服务
• 在系统自带命令提示符（Command Prompt）或PowerShell中启动服务时，Uvicorn的彩色终端输出显示乱码，无法正常展示颜色效果
  
• 预期正常的彩色输出效果如下：
  
• 已知该问题的触发原因是Windows原始终端默认不支持ANSI颜色转义序列，按照Uvicorn官方说明，其依赖colorama库实现Windows平台的彩色输出适配，单独测试colorama功能时可正常运行
• 临时规避方案为启动Uvicorn时添加--no-use-colors参数关闭颜色输出，保证日志内容可读，但无法实现彩色输出需求，启动命令示例：

uvicorn main:app --reload --no-use-colors

修复方案 #

方案1：入口文件主动初始化colorama（推荐，无额外依赖） #

该问题的核心原因是部分版本的Uvicorn不会主动触发colorama的Windows终端适配初始化，只需要在FastAPI应用入口文件的最顶部添加初始化代码即可：

1. 确认当前运行环境已安装colorama（全量安装FastAPI时会自动安装，若缺失可执行pip install colorama补装）
2. 在你的应用入口文件（通常为main.py）最顶部加入如下初始化代码，再正常编写FastAPI相关逻辑：

# 注意这两行要放在所有FastAPI、Uvicorn相关导入的最前面
from colorama import init
init(autoreset=True)

from fastapi import FastAPI
app = FastAPI()

# 后续路由、业务逻辑代码保持原有写法即可

3. 直接使用原有命令启动服务，无需添加--no-use-colors参数即可正常显示彩色输出：

uvicorn main:app --reload

方案2：更换原生支持ANSI转义的终端 #

Windows 10 1809以上版本、Windows 11系统可直接安装使用Windows Terminal，该终端原生支持ANSI颜色转义序列，无需做任何代码或配置修改，启动Uvicorn即可正常展示彩色日志。

方案3：开启原始终端的VT100支持（适合不想改代码/换终端的场景） #

通过修改注册表给系统自带的命令提示符、PowerShell开启虚拟终端支持，操作前建议备份注册表避免配置异常：

1. 按Win+R组合键，输入regedit回车打开注册表编辑器
2. 定位到路径计算机\HKEY_CURRENT_USER\Console
3. 查找名为VirtualTerminalLevel的DWORD值，若不存在则手动新建该值，将数值数据设置为1，基数选择十六进制
4. 关闭注册表编辑器，重启终端后再启动Uvicorn即可正常显示彩色输出。

排查提示：如果使用虚拟环境运行项目，需要确认执行启动命令的虚拟环境中安装了匹配版本的uvicorn和colorama，避免虚拟环境隔离导致依赖加载失效。

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