FastAPI: 安装与环境配置 — UV 极速包管理

Q: UV 和 pip 可以混用吗？

不建议。UV 管理 uv.lock 和虚拟环境，混用 pip 可能导致依赖冲突。坚持用 uv add / uv run 工作流。

Q: UV 安装失败怎么办？

确保有网络连接，检查系统是否支持 Rust 编译工具链。Windows 用户可使用 powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" 安装。

最后更新：2026-08-26

1. 你将学到

UV 安装与核心命令：uv init、uv add、uv run 的工作流
创建 PriceTracker 项目骨架：目录结构与分层约定
Uvicorn 开发服务器配置：--reload、--host、--port、--workers
.env 环境变量管理与 python-dotenv 集成
用 uv run uvicorn 一键启动开发服务

2. Alice 的真实故事

(1) 痛点：pip 装依赖慢如蜗牛

Alice 用 pip 安装 FastAPI 项目依赖，等了 3 分钟才装完。更糟的是，团队里 Bob 的 Python 3.11 和 Alice 的 3.12 版本不一致，虚拟环境冲突频发。每次 pip install -r requirements.txt 都像买彩票——不知道会不会因为某个锁文件版本冲突而失败。

(2) UV 的解法

UV 是 Astral 团队用 Rust 编写的 Python 包管理器，安装依赖速度比 pip 快 10-100 倍，内置虚拟环境管理和 Python 版本切换，一条命令搞定项目初始化。

BASH

# Initialize project and add FastAPI in one go
uv init pricetracker
cd pricetracker
uv add fastapi uvicorn
uv run uvicorn app.main:app --reload

(3) 收益

Alice 的依赖安装从 3 分钟降到 3 秒，Bob 和 Alice 的环境完全一致（uv.lock 锁定版本），CI/CD 构建时间减少 80%。

3. UV 包管理器基础

(1) UV 核心命令速查

命令	功能	pip 等价
`uv init`	初始化项目	手动创建 venv + requirements.txt
`uv add <pkg>`	添加依赖到 pyproject.toml	`pip install` + 手动更新 requirements.txt
`uv remove <pkg>`	移除依赖	`pip uninstall` + 手动更新
`uv run <cmd>`	在虚拟环境中运行命令	`source venv/bin/activate && cmd`
`uv sync`	同步所有依赖	`pip install -r requirements.txt`
`uv lock`	锁定依赖版本	`pip freeze > requirements.txt`
`uv python install 3.12`	安装 Python 版本	pyenv install 3.12

▶ 示例：UV 项目初始化

BASH

# Create project directory
uv init pricetracker
cd pricetracker

# This creates:
# pricetracker/
#   pyproject.toml
#   .python-version
#   hello.py
#   .venv/  (auto-created virtual environment)

TEXT 📖 仅展示

Initialized project pricetracker

▶ 示例：添加 FastAPI 依赖

BASH

# Add FastAPI and Uvicorn
uv add fastapi uvicorn[standard]

# Check pyproject.toml
cat pyproject.toml

TEXT 📖 仅展示

[project]
name = "pricetracker"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "fastapi>=0.115.0",
    "uvicorn[standard]>=0.30.0",
]

(2) UV vs pip vs Poetry 对比

维度	UV	pip	Poetry
安装速度	10-100x faster	基准	2-5x faster
锁文件	`uv.lock`	无	`poetry.lock`
虚拟环境	自动管理	手动 `venv`	自动管理
Python 版本管理	内置	无	需 pyenv
配置文件	`pyproject.toml`	`requirements.txt`	`pyproject.toml`
Rust 核心	是	否	否

4. PriceTracker 项目骨架

(1) 目录结构设计

graph TD
    Root[pricetracker/] --> App[app/]
    App --> Main[__init__.py]
    App --> MainPy[main.py]
    App --> Api[api/]
    Api --> Routes[routes/]
    Routes --> Products[products.py]
    Routes --> Prices[prices.py]
    Routes --> Auth[auth.py]
    App --> Models[models/]
    App --> Schemas[schemas/]
    App --> Services[services/]
    App --> Core[core/]
    Core --> Config[config.py]
    Core --> Security[security.py]
    App --> Db[db.py]
    Root --> Tests[tests/]
    Root --> Alembic[alembic/]
    Root --> Docker[docker/]
    Root --> Env[.env]
    Root --> Pyproject[pyproject.toml]

目录	职责	说明
`app/`	应用主包	所有业务代码
`app/api/routes/`	路由模块	按功能拆分端点
`app/models/`	SQLAlchemy 模型	数据库表映射
`app/schemas/`	Pydantic 模型	请求/响应校验
`app/services/`	业务逻辑	仓储层与服务层
`app/core/`	核心配置	配置、安全、依赖
`tests/`	测试	pytest 测试套件
`alembic/`	数据库迁移	Alembic 迁移脚本
`docker/`	容器配置	Dockerfile + Compose

▶ 示例：创建项目骨架

BASH

# Create all directories
mkdir -p app/api/routes app/models app/schemas app/services app/core
mkdir -p tests alembic docker

# Create __init__.py files
touch app/__init__.py app/api/__init__.py app/api/routes/__init__.py
touch app/models/__init__.py app/schemas/__init__.py
touch app/services/__init__.py app/core/__init__.py
touch tests/__init__.py

TEXT 📖 仅展示

CONTAINER ID   IMAGE     STATUS    
abc123         latest    Up 2 hours

▶ 示例：最小 FastAPI 应用 app/main.py

PYTHON

from fastapi import FastAPI

app = FastAPI(
    title="PriceTracker API",
    description="SaaS price tracking service for e-commerce",
    version="0.1.0",
)

@app.get("/health")
async def health_check():
    return {"status": "healthy", "service": "pricetracker"}

TEXT 📖 仅展示

# 函数定义成功

5. Uvicorn 开发服务器

(1) Uvicorn 核心参数

参数	默认值	说明
`--host`	`127.0.0.1`	监听地址，`0.0.0.0` 允许外部访问
`--port`	`8000`	监听端口
`--reload`	`False`	文件变更自动重启（仅开发用）
`--reload-dir`	`.`	监听目录，可指定多个
`--workers`	`1`	工作进程数（生产用，与 --reload 冲突）
`--log-level`	`info`	日志级别

▶ 示例：开发模式启动

BASH

# Start with hot reload - auto restart on code changes
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

TEXT 📖 仅展示

INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Started reloader process
INFO:     Started server process
INFO:     Waiting for application startup.
INFO:     Application startup complete.

▶ 示例：生产模式启动

BASH

# Production: multiple workers, no reload
uv run uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4

TEXT 📖 仅展示

# 命令执行成功

(2) 开发 vs 生产 Uvicorn 配置对比

配置	开发环境	生产环境
`--reload`	开启	关闭
`--workers`	1	CPU 核数 × 2 + 1
`--host`	127.0.0.1	0.0.0.0
`--log-level`	debug	info/warning
前置代理	无	Nginx/Traefik

6. 环境变量管理

(1) .env 文件与 python-dotenv

环境变量是 12-Factor App 的核心原则，敏感配置（数据库密码、JWT 密钥）绝不能硬编码。

▶ 示例：创建 .env 文件

INI

# .env - NEVER commit this file to git!
APP_NAME=PriceTracker
DEBUG=true
DATABASE_URL=postgresql+asyncpg://pricetracker:secret@localhost:5432/pricetracker
REDIS_URL=redis://localhost:6379/0
SECRET_KEY=your-super-secret-key-change-in-production
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

TEXT 📖 仅展示

// 执行成功

▶ 示例：Pydantic Settings 读取环境变量

PYTHON

# app/core/config.py
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    app_name: str = "PriceTracker"
    debug: bool = False
    database_url: str = "postgresql+asyncpg://localhost/pricetracker"
    redis_url: str = "redis://localhost:6379/0"
    secret_key: str = "change-me-in-production"
    algorithm: str = "HS256"
    access_token_expire_minutes: int = 30

    model_config = {"env_file": ".env", "env_file_encoding": "utf-8"}

settings = Settings()

TEXT 📖 仅展示

# 执行成功

▶ 示例：在 FastAPI 中使用配置

PYTHON

# app/main.py
from fastapi import FastAPI
from app.core.config import settings

app = FastAPI(
    title=settings.app_name,
    debug=settings.debug,
)

@app.get("/info")
async def app_info():
    return {
        "app": settings.app_name,
        "debug": settings.debug,
        "database": settings.database_url.split("@")[-1],  # Hide credentials
    }

TEXT 📖 仅展示

# 函数定义成功

(2) .gitignore 必备项

BASH

# Add to .gitignore
.env
.env.local
.env.production
.venv/
__pycache__/
*.pyc

文件	是否提交	原因
`.env`	否	含敏感信息
`.env.example`	是	团队参考模板
`uv.lock`	是	锁定依赖版本
`pyproject.toml`	是	项目配置

7. 综合示例

结合 UV 包管理、Pydantic Settings 配置和 Uvicorn 启动，展示从项目初始化到服务运行的完整流程。

PYTHON

# pyproject.toml 依赖：fastapi, uvicorn, pydantic-settings
from fastapi import FastAPI
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    app_name: str = "PriceTracker"
    debug: bool = False
    database_url: str = "postgresql+asyncpg://user:pass@localhost/pricetracker"

    model_config = {"env_file": ".env"}

settings = Settings()
app = FastAPI(title=settings.app_name, debug=settings.debug)

@app.get("/health")
async def health():
    return {"status": "ok", "app": settings.app_name}

@app.get("/info")
async def info():
    return {"app": settings.app_name, "debug": settings.debug}
# 启动：uv run uvicorn app.main:app --reload

TEXT 📖 仅展示

GET /health → {"status":"ok","app":"PriceTracker"}
GET /info → {"app":"PriceTracker","debug":false}

❓ 常见问题

Q UV 和 pip 可以混用吗？

A 不建议。UV 管理 uv.lock 和虚拟环境，混用 pip 可能导致依赖冲突。坚持用 uv add/uv run 工作流。

Q 为什么用 Uvicorn 而不是 Gunicorn？

A Uvicorn 是 ASGI 服务器，支持 async。Gunicorn 是 WSGI 服务器，不支持 async。生产环境可用 Gunicorn + Uvicorn Worker 混合模式。

Q --reload 和 --workers 能同时用吗？

A 不能。--reload 只支持单进程，生产环境用 --workers 多进程，不要开 --reload。

Q .env 文件放哪里？

A 放在项目根目录，与 pyproject.toml 同级。务必加入 .gitignore，同时提供 .env.example 给团队参考。

Q Pydantic Settings 和 python-dotenv 哪个好？

A 推荐 Pydantic Settings（pydantic-settings 包）。它支持类型校验、默认值、嵌套配置，比 python-dotenv 更安全更强大。

Q UV 安装失败怎么办？

A 确保有网络连接，检查系统是否支持 Rust 编译工具链。Windows 用户可使用 powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" 安装。

📖 小节

UV 用 Rust 编写，安装依赖比 pip 快 10-100 倍，内置虚拟环境和 Python 版本管理
PriceTracker 项目采用分层结构：api/routes、models、schemas、services、core 五层
Uvicorn 开发用 --reload 热重载，生产用 --workers 多进程
.env + Pydantic Settings 管理环境变量，敏感配置绝不硬编码
uv run uvicorn app.main:app --reload 一条命令启动完整开发服务

📝 作业

基础题（难度⭐）：用 uv init 创建项目，添加 fastapi 和 uvicorn 依赖，运行第一个 Hello World 端点。提示：uv add fastapi uvicorn
进阶题（难度⭐⭐）：创建 PriceTracker 项目骨架目录结构，编写 app/main.py 含 /health 端点，用 uv run uvicorn 启动并验证。提示：参考本文目录结构图
挑战题（难度⭐⭐⭐）：使用 Pydantic Settings 创建配置类，从 .env 文件读取 DATABASE_URL 和 SECRET_KEY，在 /info 端点返回应用名称（不暴露密钥）。提示：pip install pydantic-settings，即 uv add pydantic-settings

---|

Web-Tutorial 技术团队

由多位开发者共同维护的编程教程平台。每篇教程由对应领域的开发者编写和审核，确保内容准确可靠。如发现任何问题，欢迎向我们反馈。

关于我们

FastAPI: 安装与环境配置 — UV 极速包管理

1. 你将学到

2. Alice 的真实故事

(1) 痛点：pip 装依赖慢如蜗牛

(2) UV 的解法

(3) 收益

3. UV 包管理器基础

(1) UV 核心命令速查

▶ 示例：UV 项目初始化

▶ 示例：添加 FastAPI 依赖

(2) UV vs pip vs Poetry 对比

4. PriceTracker 项目骨架

(1) 目录结构设计

▶ 示例：创建项目骨架

▶ 示例：最小 FastAPI 应用 app/main.py

5. Uvicorn 开发服务器

(1) Uvicorn 核心参数

▶ 示例：开发模式启动

▶ 示例：生产模式启动

(2) 开发 vs 生产 Uvicorn 配置对比

6. 环境变量管理

(1) .env 文件与 python-dotenv

▶ 示例：创建 .env 文件

▶ 示例：Pydantic Settings 读取环境变量

▶ 示例：在 FastAPI 中使用配置

(2) .gitignore 必备项

7. 综合示例

❓ 常见问题

📖 小节

📝 作业

🙏 帮我们做得更好