官方使用
FastAPI 官方 Dockerfile 中用了两次：
RUN --mount=type=cache,target=/root/.cache/uv \--mount=type=bind,source=uv.lock,target=uv.lock \--mount=type=bind,source=pyproject.toml,target=pyproject.toml \uv sync --frozen --no-install-project # ✅ 第一次RUN --mount=type=cache,target=/root/.cache/uv \uv sync # ✅ 第二次
这是 uv 官方推荐的优化构建流程，目的是 最大程度复用缓存，加快构建速度，同时支持源码变化重装依赖。
🔍 第一次 uv sync --frozen --no-install-project
📌 作用是：
• ✅ 只安装依赖（不安装你项目代码）
• ✅ 使用 lock 文件精确控制版本
• ✅ 构建中间层缓存（intermediate layer）
✔️ 只要你没改 pyproject.toml 或 uv.lock，这一层永远不需要重建！
这是 Docker 构建中非常重要的一环 —— 利用文件不变来缓存 layer，加快构建速度。
🔄 第二次 uv sync
📌 作用是：
• ✅ 安装你项目的源码（也就是 app/ 本身）
• 因为第一次用了 --no-install-project，项目代码没有装进去
🚨 如果你更新了项目源码，但没改 pyproject.toml，就只会触发第二次构建。
你可以类比为：
# 第一次，只安装依赖，不装项目代码
pip install --no-deps --require-hashes -r requirements.txt# 第二次，把你的项目当成 package 装进环境里
pip install .
# 是 Python 项目中非常重要的一步，表示 将你当前目录（.）下的项目当作一个 Package 安装到当前 Python 环境中。这样你每次写代码改的是 .py 文件而不是依赖，Docker 就不会重新构建冗余层 ✅
| 第一次 uv sync --frozen --no-install-project | 第二次 uv sync |
|---|---|
| 安装依赖项（构建缓存层） | 安装项目本身 |
| 不会安装你 app/ 源码 | 会装源码到虚拟环境 |
| 对应 lock 文件（更可控） | 快速重建项目层 |
| 有利于构建性能 | 有利于热更新和本地测试 |
可以，但你就会失去 中间层缓存优化的好处，每次改 .py 都会重新装全部依赖 ❌
✅ 为什么 FastAPI 官方不写 COPY？
因为他们使用的是 BuildKit 的多阶段构建 + bind mount 优化方案：
• 第一次 RUN uv sync --frozen --no-install-project 使用挂载的 pyproject.toml 和 uv.lock 安装依赖（但不安装项目）
• 最终会在后面阶段，再使用 COPY . . 把项目代码拷贝进来| 步骤 | 是否合理 | 说明 |
|---|---|---|
| 设置基础镜像 | ✅ | python:3.12-slim 节省体积 |
| 使用 uv 构建 | ✅ | 快速高效、现代依赖工具 |
| 缓存依赖安装层 | ✅ | 加速构建、复用缓存 |
| 分阶段 COPY + uv sync | ✅ | 减少变更触发重装 |
| PYTHONPATH=. | ✅ | 适配 from app.xxx 导入 |
| CMD 使用 uvicorn | ✅ | 适合线上部署、ASGI 原生 |
开箱即用的Dockfile
FROM python:3.12-slim AS builderWORKDIR /app# 设置时区为 UTC+8
ENV TZ=Asia/Shanghai
RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezoneCOPY --from=ghcr.io/astral-sh/uv:0.5.11 /uv /uvx /bin/ENV PATH="/app/.venv/bin:$PATH"
ENV UV_COMPILE_BYTECODE=1
ENV UV_LINK_MODE=copy# 复制项目文件到容器中
COPY . /app/RUN --mount=type=cache,target=/root/.cache/uv \--mount=type=bind,source=uv.lock,target=uv.lock \--mount=type=bind,source=pyproject.toml,target=pyproject.toml \uv sync --frozen --no-install-projectENV PYTHONPATH=.CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--log-level", "warning"]
)
)
)
