应直接使用预编译的 ghcr.io/astral-sh/uv 镜像，避免 pip install uv；按需选择带 Python 和系统标签的确定版本镜像，严格对齐 requires-python；依赖安装应前置并仅 COPY pyproject.toml 和 uv.lock 以提升缓存命中率；开发用 uvx run + UV_NO_DEV=0 实现热重载；生产禁用 UV_PYTHON_DOWNLOADS 并以非 root 用户运行。
直接用预编译 uv 镜像，别 pip install uv
在 Docker 容器里手动 pip install uv 是最常见也最不推荐的做法——它会多出一层构建时间、引入不必要的 Python 构建依赖（比如 gcc），还可能因镜像源或网络问题失败。官方维护的 ghcr.io/astral-sh/uv 镜像已预装 Rust 编译好的二进制 uv 和对应 Python 版本，开箱即用。
实操建议：
- 优先选用带明确 Python 版本和系统标签的镜像，例如
ghcr.io/astral-sh/uv:python3.12-bookworm-slim（Debian 系统）或ghcr.io/astral-sh/uv:python3.12-alpine（Alpine 系统） - 避免使用
latest标签，防止某天 CI 构建突然失败——镜像 tag 应与pyproject.toml中的requires-python严格对齐 - 若必须用
python:3.12-slim基础镜像，再装 uv，请加--no-cache-dir并指定清华源：RUN pip install --no-cache-dir -i https://pypi.tuna.tsinghua.edu.cn/simple/ uv
uv.lock 变更触发 rebuild，不是 COPY . . 后才装依赖
Docker 缓存失效是构建慢的主因。很多人把 uv.lock 和代码一起 COPY . .，导致每次改一行业务代码，RUN uv sync 都得重跑——完全浪费了 uv 的并行解析和缓存能力。
正确做法是把依赖安装拆到靠前层，且只拷贝锁文件：
-
COPY pyproject.toml uv.lock ./—— 这两份文件变更频率低，缓存命中率高 -
RUN uv sync --no-dev—— 生产环境跳过 dev-dependencies，减小镜像体积 -
COPY . .放在依赖安装之后 —— 业务代码修改不影响前面所有层 - 注意：如果项目用了
[tool.uv]配置节（如index或link-mode），也要确保pyproject.toml在这步就存在
开发模式下用 UV_NO_DEV=0 + watch，别硬编码 uv run
Docker Compose 的 watch 功能配合 uv 能实现真正的热重载，但容易踩两个坑：一是忘记启用 dev 依赖，二是误用 uv run 启动服务（它会每次新建 venv，极慢）。
关键配置点：
- 在
compose.yml的 service env 中显式设UV_NO_DEV=0，否则uv sync默认跳过[project.optional-dependencies.dev] - 用
uvx run替代uv run：前者复用已安装环境，启动快；后者每次检查 venv 状态，开销大 -
watch指令中务必ignore: [.venv/]—— 否则容器内自动生成的.venv会被同步回宿主机，破坏本地环境 - 开发时 CMD 推荐写成：
sh -c "uv sync && exec uvx run uvicorn main:app --reload --host 0.0.0.0:8000"
生产镜像禁用 UV_PYTHON_DOWNLOADS，且用非 root 用户
线上容器若意外触发 uv 下载新 Python 版本（比如 uv python install 3.13），会导致启动失败或安全风险。同时，默认 root 权限运行 Python 服务是 Docker 安全红线。
必须做的几件事：
- 在 Dockerfile 中加
ENV UV_PYTHON_DOWNLOADS=0，强制 uv 只用基础镜像自带的 Python - 用
USER指令切换用户：RUN groupadd -g 1001 -r appuser && useradd -r -u 1001 -g appuser appuser，再USER appuser - 确保
COPY的文件权限兼容非 root 用户（如COPY --chown=appuser:appuser . .） - 若用了多阶段构建，最终 stage 不要保留 builder 阶段的
/root/.cache/uv—— 它没用还占空间
真正麻烦的不是写对这几行，而是团队里有人悄悄在 pyproject.toml 里加了 [tool.uv.python] 配置，又没同步更新 Dockerfile 的 UV_PYTHON_DOWNLOADS 状态——上线前务必 grep 一遍。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
