01. FastAPI 环境搭建uv 怎么安装包

先弄清楚四个名字

Python 是运行代码的解释器；FastAPI 是处理 HTTP 请求的框架；Uvicorn 是接收网络连接并运行应用的 ASGI 服务器；uv 负责安装 Python、管理虚拟环境和依赖。可以把它们想成语言、办事规则、接待窗口和工具箱。

本系列使用 Python 3.12、Pydantic 2、SQLAlchemy 2.0。命令默认在 Windows PowerShell 中执行。各章独立的 main.py 示例应放在不同练习目录，避免反复粘贴后路由重名。第 20～24 篇则共用一个数据库练习项目。

安装 uv，创建第一个环境

可以通过系统包管理器安装 uv：

winget install --id=astral-sh.uv -e

也可以使用官方安装脚本，二选一即可：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

安装后重新打开终端，再执行：

uv --version
uv python install 3.12
uv init --bare --python 3.12 fastapi-study
Set-Location fastapi-study
uv python pin 3.12
uv add "fastapi[standard]" "pydantic>=2,<3" uvicorn
uv run python --version
uv run python -c "import fastapi; print(fastapi.__version__)"

--bare 让初始结构简单明确；uv add 会修改 pyproject.toml、更新 uv.lock，并准备 .venv。uv run 会在该项目环境中执行程序，因此通常不用手动激活虚拟环境。

安装 uvicorn

uvicorn 是运行 FastAPI 应用的 ASGI 服务器，负责接收网络请求并交给应用处理。在 uv add 中直接加上 uvicorn 即可；如果需要支持 --reload 热重载等增强特性，可以安装带标准扩展的版本：

uv add "uvicorn[standard]"

安装完成后可以验证：

uv run uvicorn --version

之后在项目目录中通过 uv run uvicorn main:app --reload 即可启动服务（main:app 指 main.py 中的 app 对象）。

安装、卸载、复现环境

需求	命令	说明
添加运行依赖	uv add httpx	同时维护项目依赖声明
添加开发依赖	uv add --dev pytest	测试工具不混入生产依赖组
移除依赖	uv remove httpx	更新声明和锁文件
同步现有项目	uv sync --locked	锁文件与声明不一致时失败
查看依赖树	uv tree	查清间接依赖来源
升级指定依赖	uv lock --upgrade-package fastapi	之后执行 uv sync 并验证
临时运行工具	uvx ruff check .	工具隔离运行，不加入项目依赖

uv pip install 是兼容 pip 风格的底层安装方式，适合临时环境；它不会像 uv add 一样维护项目依赖声明。团队项目优先使用 uv add 和 uv sync。

提交 pyproject.toml、uv.lock 和 .python-version；不要提交 .venv、密码或真实 .env。锁文件固定本次解析结果，而版本范围表达允许升级的范围，两者分工不同。

导出包目录 和 安装包目录

导出包目录

• 查看安装包列表

uv pip list

• 当开发完毕后,我们需要移植这个项目.导出整个项目的所有依赖包.

uv pip freeze > requirements.txt

安装包

• 移植整个项目 需要安装包

uv pip install -r requirements.txt

常见问题与练习

• 找不到 uv：重启终端，检查 PATH，而不是在每个目录重新安装。
• IDE 提示缺包：将解释器切换到项目 .venv\Scripts\python.exe。
• 下载慢：先检查代理、网络和可信镜像设置；不要随意关闭证书验证。
• 不要把脚本命名为 fastapi.py、typing.py，否则可能遮蔽同名库。

练习：安装 httpx，运行一次导入，再卸载；比较 pyproject.toml 与 uv.lock 的变化。能解释“系统 Python”和“项目 Python”为何可能不同，就掌握了环境管理的核心。