002、环境搭建从零配置Python、虚拟环境与FastAPI项目骨架昨天帮同事排查一个线上问题服务在本地跑得好好的一上测试环境就报Python版本冲突。日志里赫然一行ModuleNotFoundError: No module named typing_extensions——典型的依赖环境不一致引发的惨案。这类问题在团队协作中太常见了今天咱们就从头把环境搭建的坑填平。Python安装别用系统自带的很多教程让你直接apt-get install python3生产环境千万别这么干。系统自带的Python版本往往滞后且权限管理混乱。去官网下载安装包或者用pyenv管理才是正道。我习惯用pyenv切换版本像换衣服一样方便# 安装pyenvMac用brewLinux用git clonecurlhttps://pyenv.run|bash# 安装指定Python版本pyenvinstall3.11.6# 选LTS版本别追最新# 设为全局默认pyenv global3.11.6验证安装时多看一眼架构python -c import platform; print(platform.machine())。去年在ARM服务器上跑x64编译的Python性能损失了30%才被发现。虚拟环境每个项目都要隔离见过有人把包装在全局环境里半年后项目都跑不起来了。虚拟环境不是可选项是必须项。Python自带的venv就够用# 创建项目目录mkdirfastapi_projectcdfastapi_project# 创建虚拟环境名字用.venv隐藏起来避免误删python-mvenv .venv# 激活环境Windows用.venv\Scripts\activatesource.venv/bin/activate激活后命令行前面会出现(.venv)提示。VSCode用户记得按CtrlShiftP选解释器指向.venv里的python.exe不然调试时用的还是全局环境。依赖管理requirements.txt已经过时了现在都用pyproject.toml配合pip-tools。先创建个基础文件# pyproject.toml [build-system] requires [setuptools61.0] build-backend setuptools.build_meta [project] name fastapi_project version 0.1.0 dependencies [ fastapi0.104.0, uvicorn[standard]0.24.0, # 带上standard自动装uvloop和httptools ] [project.optional-dependencies] dev [ pytest7.4.0, black23.0, # 格式化代码用 mypy1.0, # 类型检查 ]然后生成锁文件确保一致性# 安装pip-toolspipinstallpip-tools# 生成requirements.txt给Docker用pip-compile --output-filerequirements.txt pyproject.toml# 安装所有依赖pipinstall-rrequirements.txt锁文件要提交到Git这样所有机器上的依赖版本完全一致。遇到过因为pytest版本差异本地测试全过CI流水线报错的情况。项目骨架别从单文件开始新手喜欢把所有代码写进main.py超过500行就失控了。推荐这个结构fastapi_project/ ├── .venv/ # 虚拟环境.gitignore忽略 ├── app/ │ ├── __init__.py # 空文件让Python识别为包 │ ├── main.py # FastAPI实例和路由注册 │ ├── api/ # 路由层 │ │ ├── __init__.py │ │ └── v1/ # 版本隔离 │ │ ├── __init__.py │ │ ├── endpoints/ │ │ └── models.py │ ├── core/ # 配置、安全等核心逻辑 │ └── services/ # 业务逻辑层 ├── tests/ # 测试代码 ├── pyproject.toml └── requirements.txtmain.py先写个最小可运行版本fromfastapiimportFastAPIfromcontextlibimportasynccontextmanager# 用生命周期管理数据库连接池asynccontextmanagerasyncdeflifespan(app:FastAPI):# 启动时初始化print(Starting up...)yield# 关闭时清理print(Shutting down...)# 这里别用__name__生产环境有坑appFastAPI(lifespanlifespan,titleMy API)app.get(/health)asyncdefhealth_check():健康检查端点K8s用得上return{status:ok}启动命令也别直接uvicorn main:app写个脚本# run.sh#!/bin/bashsource.venv/bin/activate uvicorn app.main:app--host0.0.0.0--port8000--reload调试配置VSCode用户看这里在.vscode/launch.json里配置{version:0.2.0,configurations:[{name:FastAPI Debug,type:python,request:launch,module:uvicorn,args:[app.main:app,--reload],jinja:true,justMyCode:false// 能进第三方库调试}]}这样能在断点里看到请求上下文排查身份验证问题时特别有用。几个容易翻车的点第一别在虚拟环境里装jupyter这类重型工具会污染环境。第二Windows用户注意文件路径分隔符曾经有个bug是Linux正常Windows报错最后发现是硬编码了/tmp。第三团队里统一Python版本用.python-version文件声明echo 3.11.6 .python-version。环境配置看似基础却是项目稳定性的地基。我习惯在项目README最前面加个“环境检查清单”新同事按步骤执行能避免80%的环境问题。下次咱们往这个骨架里填肉——聊聊怎么设计API路由和请求验证。
002、环境搭建：从零配置Python、虚拟环境与FastAPI项目骨架
发布时间：2026/8/1 2:01:26
002、环境搭建从零配置Python、虚拟环境与FastAPI项目骨架昨天帮同事排查一个线上问题服务在本地跑得好好的一上测试环境就报Python版本冲突。日志里赫然一行ModuleNotFoundError: No module named typing_extensions——典型的依赖环境不一致引发的惨案。这类问题在团队协作中太常见了今天咱们就从头把环境搭建的坑填平。Python安装别用系统自带的很多教程让你直接apt-get install python3生产环境千万别这么干。系统自带的Python版本往往滞后且权限管理混乱。去官网下载安装包或者用pyenv管理才是正道。我习惯用pyenv切换版本像换衣服一样方便# 安装pyenvMac用brewLinux用git clonecurlhttps://pyenv.run|bash# 安装指定Python版本pyenvinstall3.11.6# 选LTS版本别追最新# 设为全局默认pyenv global3.11.6验证安装时多看一眼架构python -c import platform; print(platform.machine())。去年在ARM服务器上跑x64编译的Python性能损失了30%才被发现。虚拟环境每个项目都要隔离见过有人把包装在全局环境里半年后项目都跑不起来了。虚拟环境不是可选项是必须项。Python自带的venv就够用# 创建项目目录mkdirfastapi_projectcdfastapi_project# 创建虚拟环境名字用.venv隐藏起来避免误删python-mvenv .venv# 激活环境Windows用.venv\Scripts\activatesource.venv/bin/activate激活后命令行前面会出现(.venv)提示。VSCode用户记得按CtrlShiftP选解释器指向.venv里的python.exe不然调试时用的还是全局环境。依赖管理requirements.txt已经过时了现在都用pyproject.toml配合pip-tools。先创建个基础文件# pyproject.toml [build-system] requires [setuptools61.0] build-backend setuptools.build_meta [project] name fastapi_project version 0.1.0 dependencies [ fastapi0.104.0, uvicorn[standard]0.24.0, # 带上standard自动装uvloop和httptools ] [project.optional-dependencies] dev [ pytest7.4.0, black23.0, # 格式化代码用 mypy1.0, # 类型检查 ]然后生成锁文件确保一致性# 安装pip-toolspipinstallpip-tools# 生成requirements.txt给Docker用pip-compile --output-filerequirements.txt pyproject.toml# 安装所有依赖pipinstall-rrequirements.txt锁文件要提交到Git这样所有机器上的依赖版本完全一致。遇到过因为pytest版本差异本地测试全过CI流水线报错的情况。项目骨架别从单文件开始新手喜欢把所有代码写进main.py超过500行就失控了。推荐这个结构fastapi_project/ ├── .venv/ # 虚拟环境.gitignore忽略 ├── app/ │ ├── __init__.py # 空文件让Python识别为包 │ ├── main.py # FastAPI实例和路由注册 │ ├── api/ # 路由层 │ │ ├── __init__.py │ │ └── v1/ # 版本隔离 │ │ ├── __init__.py │ │ ├── endpoints/ │ │ └── models.py │ ├── core/ # 配置、安全等核心逻辑 │ └── services/ # 业务逻辑层 ├── tests/ # 测试代码 ├── pyproject.toml └── requirements.txtmain.py先写个最小可运行版本fromfastapiimportFastAPIfromcontextlibimportasynccontextmanager# 用生命周期管理数据库连接池asynccontextmanagerasyncdeflifespan(app:FastAPI):# 启动时初始化print(Starting up...)yield# 关闭时清理print(Shutting down...)# 这里别用__name__生产环境有坑appFastAPI(lifespanlifespan,titleMy API)app.get(/health)asyncdefhealth_check():健康检查端点K8s用得上return{status:ok}启动命令也别直接uvicorn main:app写个脚本# run.sh#!/bin/bashsource.venv/bin/activate uvicorn app.main:app--host0.0.0.0--port8000--reload调试配置VSCode用户看这里在.vscode/launch.json里配置{version:0.2.0,configurations:[{name:FastAPI Debug,type:python,request:launch,module:uvicorn,args:[app.main:app,--reload],jinja:true,justMyCode:false// 能进第三方库调试}]}这样能在断点里看到请求上下文排查身份验证问题时特别有用。几个容易翻车的点第一别在虚拟环境里装jupyter这类重型工具会污染环境。第二Windows用户注意文件路径分隔符曾经有个bug是Linux正常Windows报错最后发现是硬编码了/tmp。第三团队里统一Python版本用.python-version文件声明echo 3.11.6 .python-version。环境配置看似基础却是项目稳定性的地基。我习惯在项目README最前面加个“环境检查清单”新同事按步骤执行能避免80%的环境问题。下次咱们往这个骨架里填肉——聊聊怎么设计API路由和请求验证。
的进阶指南)
