FastAPI 应用调试实战直接在代码中运行 Uvicorn并在 VS Code 与 PyCharm 中断点调试【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi本文围绕 FastAPI 官方教程中的「调试Debugging」主题展开教你如何在编辑器中把调试器直接挂到 FastAPI 应用上——先在应用代码里显式导入并调用uvicorn.run()启动服务器再利用__name__ __main__的机制保证服务只在直接运行文件时启动最后在 Visual Studio Code 或 PyCharm 的调试器中启动程序并命中断点。读完本文你将掌握一套完整的 FastAPI 本地调试工作流并理解「直接在代码中启动 Uvicorn」与「命令行fastapi dev启动」两种方式的关系与适用场景。为什么要在代码里直接调用uvicornFastAPI 应用的常规运行方式是使用命令行工具启动 Uvicorn例如fastapi dev该命令由fastapi-cli提供入口封装见 fastapi/cli.py其中在缺少fastapi[standard]依赖时会提示安装pyproject.toml 中的standard依赖组包含了uvicorn[standard] 0.12.0。但调试场景有一个特殊需求编辑器调试器Debug Adapter是通过启动一个 Python 进程来附加断点的它要求你自己启动的解释器进程里运行着你的应用代码。如果服务器是由外部命令行工具拉起的调试器很难与之关联。因此官方调试教程给出的做法很直接在你的 FastAPI 应用里导入uvicorn并直接调用uvicorn.run()让服务器作为「当前脚本」的一部分启动。这样调试器只需要运行你的 Python 文件就能断点命中请求处理逻辑。在 FastAPI 应用中导入并直接运行uvicorn教程给出的完整可运行示例位于 docs_src/debugging/tutorial001_py310.py内容如下import uvicorn from fastapi import FastAPI app FastAPI() app.get(/) def root(): a a b b a return {hello world: b} if __name__ __main__: uvicorn.run(app, host0.0.0.0, port8000)几个要点import uvicornUvicorn 是 ASGI 服务器uvicorn.run()是它的编程式启动入口。注意它接收的是应用对象app而非模块字符串这正是本方案的关键——服务器在同一个解释器进程中启动host0.0.0.0监听所有网络接口便于局域网或容器外的设备访问开发服务器port8000FastAPI 生态的默认开发端口请求处理函数root()中只有几行普通 Python 代码a a、b b a这里就是在编辑器里设置断点的位置——当调试器启动该脚本后任意 HTTP 请求打到GET /时都会停在断点处可以查看/修改局部变量。保存为main.py后直接运行$ uv run python main.py即可启动服务。此时if __name__ __main__:块内的uvicorn.run(...)会被执行服务器在当前进程内启动。深入理解__name__ __main__if __name__ __main__:是 Python 的模块保护惯用法它的目的是让某段代码只在文件被直接执行时运行而在文件被其他模块导入时不运行。直接执行文件时假设文件名为myapp.py用如下命令运行$ uv run python myapp.pyPython 解释器会自动在该文件内部创建一个内置变量__name__其值为字符串__main__。因此判断条件成立这段代码uvicorn.run(app, host0.0.0.0, port8000)会被执行服务器随之启动。被其他模块导入时这个行为不会发生。比如另有一个importer.pyfrom myapp import app # 其他一些代码当myapp被导入时myapp.py内部自动创建的__name__变量的值不是__main__而是模块名myapp。于是uvicorn.run(app, host0.0.0.0, port8000)不会被执行——导入方拿到的只是app对象服务器是否启动完全由导入方决定。这个机制对调试场景的意义在于同一段代码可以兼容两种用法——开发调试时python myapp.py直接运行进程内自带服务器编辑器调试器可以直接接管生产部署或测试时from myapp import app导入应用对象交给外部进程管理器如fastapi run、Gunicorn/Uvicorn 的命令行多 worker 模式去启动避免导入即起服务器带来的端口冲突与进程混乱。关于__main__与__name__的更多细节可以参考 Python 标准库文档中的__main__章节此处不提供外部链接见 Python 官方文档「The Python Runtime →__main__模块」。用编辑器调试器运行你的代码因为 Uvicorn 服务器是从你的代码内部直接启动的你可以把整个 Python 程序你的 FastAPI 应用直接交给编辑器的调试器来运行断点、变量监视、调用栈全部可用。Visual Studio Code 的步骤打开侧边栏的Debug调试面板点击「Add configuration...」选择「Python」以「Python: Current File (Integrated Terminal)」方式运行调试器。随后 VS Code 会启动你的 FastAPI 代码作为服务器并会在你设置的断点处暂停行为与普通 Python 脚本调试一致。PyCharm 的步骤打开顶部Run菜单选择Debug...选项弹出一个上下文菜单选择要调试的文件例如main.py。PyCharm 会以调试模式启动该文件你的 FastAPI 服务器随之运行请求处理逻辑会在断点处暂停便于逐行执行与检查状态。两种编辑器的本质相同调试器以调试模式启动python main.py这个进程__name__ __main__判断成立uvicorn.run()在当前进程内启动 ASGI 服务器随后每个进入路由处理函数的请求都会触发断点。与fastapi dev/fastapi run的关系与选择建议从源码结构看仓库中的 fastapi/cli.py 只是把命令行入口委托给独立的fastapi-cli包from fastapi_cli.cli import main它负责按约定发现应用模块并拉起 Uvicorn。官方文档 docs/en/docs/fastapi-cli.md 说明了两种模式fastapi dev开发模式启动前会把环境变量FASTAPI_ENV设置为development若已设置则保留原值便于应用启动代码选择开发友好行为fastapi run生产模式。两种启动方式对比方式启动机制是否天然支持编辑器断点典型场景代码内uvicorn.run(app, ...)当前进程内启动 ASGI 服务器是——调试器直接启动该脚本进程本地开发、断点调试fastapi dev/fastapi run外部 CLI 发现并启动应用需额外配置「附加到已运行进程」或调试器启动参数日常开发带热重载、生产部署因此本文教程的价值在于当你需要逐行断点调试请求处理逻辑、依赖关系或序列化行为时把if __name__ __main__: uvicorn.run(...)这一行放进应用文件用编辑器调试器直接跑当前文件是成本最低、兼容性最好的路径。调试完成后这行代码保留下来也不会影响import app式的部署方式——这正是__name__ __main__惯用法的收益所在。小结在 FastAPI 应用文件顶部import uvicorn并在if __name__ __main__:块中调用uvicorn.run(app, host0.0.0.0, port8000)即可让服务器随脚本进程启动__name__ __main__保证直接python myapp.py运行时启动服务器被from myapp import app导入时则不启动兼顾调试与部署两种用法VS Code 用 Debug 面板的 「Python: Current File (Integrated Terminal)」PyCharm 用 Run → Debug... 选择目标文件即可在断点处暂停 FastAPI 的请求处理代码完整可运行示例见 docs_src/debugging/tutorial001_py310.py教程原文见 docs/es/docs/tutorial/debugging.md。【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 FastAPI 应用调试实战：直接在代码中运行 Uvicorn，并在 VS Code 与 PyCharm 中断点调试
FastAPI 应用调试实战直接在代码中运行 Uvicorn并在 VS Code 与 PyCharm 中断点调试【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi本文围绕 FastAPI 官方教程中的「调试Debugging」主题展开教你如何在编辑器中把调试器直接挂到 FastAPI 应用上——先在应用代码里显式导入并调用uvicorn.run()启动服务器再利用__name__ __main__的机制保证服务只在直接运行文件时启动最后在 Visual Studio Code 或 PyCharm 的调试器中启动程序并命中断点。读完本文你将掌握一套完整的 FastAPI 本地调试工作流并理解「直接在代码中启动 Uvicorn」与「命令行fastapi dev启动」两种方式的关系与适用场景。为什么要在代码里直接调用uvicornFastAPI 应用的常规运行方式是使用命令行工具启动 Uvicorn例如fastapi dev该命令由fastapi-cli提供入口封装见 fastapi/cli.py其中在缺少fastapi[standard]依赖时会提示安装pyproject.toml 中的standard依赖组包含了uvicorn[standard] 0.12.0。但调试场景有一个特殊需求编辑器调试器Debug Adapter是通过启动一个 Python 进程来附加断点的它要求你自己启动的解释器进程里运行着你的应用代码。如果服务器是由外部命令行工具拉起的调试器很难与之关联。因此官方调试教程给出的做法很直接在你的 FastAPI 应用里导入uvicorn并直接调用uvicorn.run()让服务器作为「当前脚本」的一部分启动。这样调试器只需要运行你的 Python 文件就能断点命中请求处理逻辑。在 FastAPI 应用中导入并直接运行uvicorn教程给出的完整可运行示例位于 docs_src/debugging/tutorial001_py310.py内容如下import uvicorn from fastapi import FastAPI app FastAPI() app.get(/) def root(): a a b b a return {hello world: b} if __name__ __main__: uvicorn.run(app, host0.0.0.0, port8000)几个要点import uvicornUvicorn 是 ASGI 服务器uvicorn.run()是它的编程式启动入口。注意它接收的是应用对象app而非模块字符串这正是本方案的关键——服务器在同一个解释器进程中启动host0.0.0.0监听所有网络接口便于局域网或容器外的设备访问开发服务器port8000FastAPI 生态的默认开发端口请求处理函数root()中只有几行普通 Python 代码a a、b b a这里就是在编辑器里设置断点的位置——当调试器启动该脚本后任意 HTTP 请求打到GET /时都会停在断点处可以查看/修改局部变量。保存为main.py后直接运行$ uv run python main.py即可启动服务。此时if __name__ __main__:块内的uvicorn.run(...)会被执行服务器在当前进程内启动。深入理解__name__ __main__if __name__ __main__:是 Python 的模块保护惯用法它的目的是让某段代码只在文件被直接执行时运行而在文件被其他模块导入时不运行。直接执行文件时假设文件名为myapp.py用如下命令运行$ uv run python myapp.pyPython 解释器会自动在该文件内部创建一个内置变量__name__其值为字符串__main__。因此判断条件成立这段代码uvicorn.run(app, host0.0.0.0, port8000)会被执行服务器随之启动。被其他模块导入时这个行为不会发生。比如另有一个importer.pyfrom myapp import app # 其他一些代码当myapp被导入时myapp.py内部自动创建的__name__变量的值不是__main__而是模块名myapp。于是uvicorn.run(app, host0.0.0.0, port8000)不会被执行——导入方拿到的只是app对象服务器是否启动完全由导入方决定。这个机制对调试场景的意义在于同一段代码可以兼容两种用法——开发调试时python myapp.py直接运行进程内自带服务器编辑器调试器可以直接接管生产部署或测试时from myapp import app导入应用对象交给外部进程管理器如fastapi run、Gunicorn/Uvicorn 的命令行多 worker 模式去启动避免导入即起服务器带来的端口冲突与进程混乱。关于__main__与__name__的更多细节可以参考 Python 标准库文档中的__main__章节此处不提供外部链接见 Python 官方文档「The Python Runtime →__main__模块」。用编辑器调试器运行你的代码因为 Uvicorn 服务器是从你的代码内部直接启动的你可以把整个 Python 程序你的 FastAPI 应用直接交给编辑器的调试器来运行断点、变量监视、调用栈全部可用。Visual Studio Code 的步骤打开侧边栏的Debug调试面板点击「Add configuration...」选择「Python」以「Python: Current File (Integrated Terminal)」方式运行调试器。随后 VS Code 会启动你的 FastAPI 代码作为服务器并会在你设置的断点处暂停行为与普通 Python 脚本调试一致。PyCharm 的步骤打开顶部Run菜单选择Debug...选项弹出一个上下文菜单选择要调试的文件例如main.py。PyCharm 会以调试模式启动该文件你的 FastAPI 服务器随之运行请求处理逻辑会在断点处暂停便于逐行执行与检查状态。两种编辑器的本质相同调试器以调试模式启动python main.py这个进程__name__ __main__判断成立uvicorn.run()在当前进程内启动 ASGI 服务器随后每个进入路由处理函数的请求都会触发断点。与fastapi dev/fastapi run的关系与选择建议从源码结构看仓库中的 fastapi/cli.py 只是把命令行入口委托给独立的fastapi-cli包from fastapi_cli.cli import main它负责按约定发现应用模块并拉起 Uvicorn。官方文档 docs/en/docs/fastapi-cli.md 说明了两种模式fastapi dev开发模式启动前会把环境变量FASTAPI_ENV设置为development若已设置则保留原值便于应用启动代码选择开发友好行为fastapi run生产模式。两种启动方式对比方式启动机制是否天然支持编辑器断点典型场景代码内uvicorn.run(app, ...)当前进程内启动 ASGI 服务器是——调试器直接启动该脚本进程本地开发、断点调试fastapi dev/fastapi run外部 CLI 发现并启动应用需额外配置「附加到已运行进程」或调试器启动参数日常开发带热重载、生产部署因此本文教程的价值在于当你需要逐行断点调试请求处理逻辑、依赖关系或序列化行为时把if __name__ __main__: uvicorn.run(...)这一行放进应用文件用编辑器调试器直接跑当前文件是成本最低、兼容性最好的路径。调试完成后这行代码保留下来也不会影响import app式的部署方式——这正是__name__ __main__惯用法的收益所在。小结在 FastAPI 应用文件顶部import uvicorn并在if __name__ __main__:块中调用uvicorn.run(app, host0.0.0.0, port8000)即可让服务器随脚本进程启动__name__ __main__保证直接python myapp.py运行时启动服务器被from myapp import app导入时则不启动兼顾调试与部署两种用法VS Code 用 Debug 面板的 「Python: Current File (Integrated Terminal)」PyCharm 用 Run → Debug... 选择目标文件即可在断点处暂停 FastAPI 的请求处理代码完整可运行示例见 docs_src/debugging/tutorial001_py310.py教程原文见 docs/es/docs/tutorial/debugging.md。【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考