S
SkillsMD 发现、学习和掌握最新的 AI 技术 Skills。基于真实社区数据，为开发者提供最权威的 AI 工具导航。
关于 聚焦 AI 技术 Skills 每周数据更新 中英双语文档 © 2026 SkillsMD. All rights reserved.
Python Dockerfile构建指南：使用uv和多阶段构建优化容器化部署 | SkillsMD
首页 / Skills / build-python-dockerfiles Python Dockerfile构建指南：使用uv和多阶段构建优化容器化部署 build-python-dockerfiles by baggiponte/skills
npx skills add https://github.com/baggiponte/skills --skill build-python-dockerfiles🇨🇳 中文介绍 构建 Python Dockerfile
使用此技能通过 uv 和多阶段构建为 Python 项目编写 Dockerfile。默认模式基于 Hynek Schlawack 的文章 使用 uv 构建生产就绪的 Python Docker 容器 。
工作流程
检测项目是已打包（可安装）还是未打包（从复制的源代码运行）。
选择基础镜像策略：
对于通用 Python 服务，默认使用 python:<version>-slim。
当系统包或组织标准基础镜像很重要时，使用像 ubuntu:noble 这样的操作系统镜像。
保持构建和运行时在相同的发行版系列上。
除非用户有硬性要求，否则避免使用 Alpine。
在复制源代码之前安装依赖项，以便锁文件更改和应用代码更改保持在不同的层中。
将依赖项同步和应用安装保持在单独的 uv sync 步骤中。
选择与应用类型匹配的运行时命令模式。
根据本文档中的清单验证最终的 Dockerfile。
必需的构建模式
🇺🇸 English Build Python Dockerfiles
Use this skill to author Dockerfiles for Python projects using uv and multi-stage builds. The default pattern is based on Hynek Schlawack's article Production-ready Python Docker Containers with uv .
Workflow
Detect whether the project is packaged (installable) or unpackaged (run from copied source).
Choose a base image strategy:
Default to python:<version>-slim for generic Python services.
Use an OS image like ubuntu:noble when system packages or org-standard base images matter.
Keep build and runtime on the same distro family.
Avoid Alpine unless the user has a hard requirement.
Install dependencies before copying source so lockfile changes and app code changes stay in separate layers.
Keep dependency sync and app install in separate uv sync steps.
Pick the runtime command pattern that matches the app type.
Verify the final Dockerfile against the checklist in this file.
Required build patterns
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者，精准高效
联系我们
按可能更改频率的逆序添加层。
在复制源代码之前安装依赖项，以最大化缓存命中率。
将依赖项同步和应用安装保持在单独的 RUN uv sync 步骤中。
为 uv 缓存使用 BuildKit 缓存挂载。
使用 UV_PROJECT_ENVIRONMENT=/app 并将 /app 复制到运行时镜像中。
使用 UV_COMPILE_BYTECODE=1 字节编译 Python 文件以加快启动速度。
在运行时以非 root 用户身份运行。
对于部署构建，优先使用 uv sync --locked。
默认设置
从 ghcr.io/astral-sh/uv:<version> 复制 uv。
设置：
UV_LINK_MODE=copyUV_COMPILE_BYTECODE=1UV_PYTHON_DOWNLOADS=neverUV_PROJECT_ENVIRONMENT=/app
当基础镜像有多个 Python 解释器或 uv 无法清晰推断出预期的解释器时，设置 UV_PYTHON。
为 uv 缓存使用 BuildKit 缓存挂载，通常是 /root/.cache/uv 或 /root/.cache。
切勿通过 ENV 将密钥硬编码到 Dockerfile 中。
基础模板 # syntax=docker/dockerfile:1.9
FROM python:3.13-slim AS build
COPY --from=ghcr.io/astral-sh/uv:0.8.15 /uv /uvx /bin/
ENV UV_LINK_MODE=copy \
UV_COMPILE_BYTECODE=1 \
UV_PYTHON_DOWNLOADS=never \
UV_PROJECT_ENVIRONMENT=/app
WORKDIR /src
COPY pyproject.toml uv.lock ./
RUN --mount=type=cache,target=/root/.cache/uv \
uv sync --locked --no-dev --no-install-project
COPY . /src
RUN --mount=type=cache,target=/root/.cache/uv \
uv sync --locked --no-dev --no-editable
FROM python:3.13-slim AS final
ENV PATH="/app/bin:$PATH"
STOPSIGNAL SIGINT
RUN groupadd --system app && useradd --system --gid app --home-dir /app app
COPY --from=build --chown=app:app /app /app
USER app
WORKDIR /app
CMD ["python", "-m", "your_package"]
如果项目未打包，请跳过第二个 uv sync 步骤，并在复制 /app 后将源代码复制到运行时镜像中。
如果项目有大量的操作系统级构建依赖项，请使用更完整的构建镜像，并仅在最终镜像中安装运行时库。
如果项目需要 shell 入口点或信号处理包装器，请使用显式的 ENTRYPOINT 脚本并保留 STOPSIGNAL SIGINT。
当使用操作系统镜像而不是 python:<version>-slim 时，请显式安装确切的运行时 Python 包，并在需要时设置 UV_PYTHON。
入口点模式
ASGI (FastAPI, Starlette, Quart) EXPOSE 8000
CMD ["uvicorn", "your_package.main:app", "--host", "0.0.0.0", "--port", "8000"]
Django (WSGI) EXPOSE 8000
CMD ["gunicorn", "--bind", "0.0.0.0:8000", "your_project.wsgi:application"]
Flask 或通用 WSGI EXPOSE 8000
CMD ["gunicorn", "--bind", "0.0.0.0:8000", "your_package.wsgi:app"]
后台工作进程 CMD ["python", "-m", "your_package.worker"]
CLI 或批处理任务容器 ENTRYPOINT ["python", "-m", "your_package.cli"]
对 CMD 和 ENTRYPOINT 使用 JSON 数组语法。
最终清单
使用了多阶段构建。
uv 是从官方镜像复制的。依赖项安装在复制源代码之前进行。
当应用打包时，依赖项同步和应用安装是分开的。
为 uv 使用了 BuildKit 缓存挂载。
设置了 UV_PROJECT_ENVIRONMENT=/app 并将 /app 复制到运行时镜像中。
运行时镜像以非 root 用户身份运行。
当可执行文件位于项目环境中时，PATH 包含 /app/bin。
启动命令是明确的并与应用类型匹配。
没有密钥被硬编码到镜像中。
可选但推荐：STOPSIGNAL SIGINT。
可选但推荐：为网络服务设置 EXPOSE。
可选但推荐：一个排除 VCS 数据、缓存、构建产物和本地虚拟环境的 .dockerignore。
输出约定
返回一个完整的 Dockerfile。
简要说明假设（Python 版本、打包与未打包、启动命令）。
在缺少时添加一个简短的 .dockerignore 建议。
build
final
Add layers in inverse order of likely change frequency.
Install dependencies before copying source to maximize cache hits.
Keep dependency sync and app install in separate RUN uv sync steps.
Use BuildKit cache mounts for the uv cache.
Use UV_PROJECT_ENVIRONMENT=/app and copy /app into runtime image.
Byte-compile Python files for faster startup with UV_COMPILE_BYTECODE=1.
Run as non-root in runtime.
Prefer uv sync --locked for deployment builds.
Default settings
Copy uv from ghcr.io/astral-sh/uv:<version>.
Set:
UV_LINK_MODE=copyUV_COMPILE_BYTECODE=1UV_PYTHON_DOWNLOADS=neverUV_PROJECT_ENVIRONMENT=/app
Set UV_PYTHON when the base image has multiple Python interpreters or when uv cannot infer the intended one cleanly.
Use BuildKit cache mounts for the uv cache, typically /root/.cache/uv or /root/.cache.
Never bake secrets into the Dockerfile via ENV.
Baseline template Use this as the default starting point for packaged applications:
# syntax=docker/dockerfile:1.9
FROM python:3.13-slim AS build
COPY --from=ghcr.io/astral-sh/uv:0.8.15 /uv /uvx /bin/
ENV UV_LINK_MODE=copy \
UV_COMPILE_BYTECODE=1 \
UV_PYTHON_DOWNLOADS=never \
UV_PROJECT_ENVIRONMENT=/app
WORKDIR /src
COPY pyproject.toml uv.lock ./
RUN --mount=type=cache,target=/root/.cache/uv \
uv sync --locked --no-dev --no-install-project
COPY . /src
RUN --mount=type=cache,target=/root/.cache/uv \
uv sync --locked --no-dev --no-editable
FROM python:3.13-slim AS final
ENV PATH="/app/bin:$PATH"
STOPSIGNAL SIGINT
RUN groupadd --system app && useradd --system --gid app --home-dir /app app
COPY --from=build --chown=app:app /app /app
USER app
WORKDIR /app
CMD ["python", "-m", "your_package"]
Keep the following adaptation rules in mind:
If the project is not packaged, skip the second uv sync step and copy the source into the runtime image after copying /app.
If the project has heavy OS-level build dependencies, use a fuller build image and only install runtime libraries in the final image.
If the project needs a shell entrypoint or signal handling wrapper, use an explicit ENTRYPOINT script and keep STOPSIGNAL SIGINT.
When using an OS image instead of python:<version>-slim, install the exact runtime Python packages explicitly and set UV_PYTHON if needed.
Entrypoint patterns Pick the startup command that matches the project type.
ASGI (FastAPI, Starlette, Quart) EXPOSE 8000
CMD ["uvicorn", "your_package.main:app", "--host", "0.0.0.0", "--port", "8000"]
Django (WSGI) EXPOSE 8000
CMD ["gunicorn", "--bind", "0.0.0.0:8000", "your_project.wsgi:application"]
Flask or generic WSGI EXPOSE 8000
CMD ["gunicorn", "--bind", "0.0.0.0:8000", "your_package.wsgi:app"]
Background worker CMD ["python", "-m", "your_package.worker"]
CLI or batch task container ENTRYPOINT ["python", "-m", "your_package.cli"]
Use JSON-array syntax for CMD and ENTRYPOINT.
Final checklist Run this checklist before finalizing output:
Multi-stage build is used.
uv is copied from the official image.Dependency installation happens before source copy.
Dependency sync and application install are separate when the app is packaged.
A BuildKit cache mount is used for uv.
UV_PROJECT_ENVIRONMENT=/app is set and /app is copied into the runtime image.The runtime image runs as a non-root user.
PATH includes /app/bin when executables live in the project environment.Startup command is explicit and matches app type.
No secrets are baked into the image.
Optional but recommended: STOPSIGNAL SIGINT.
Optional but recommended: EXPOSE for network services.
Optional but recommended: a .dockerignore that excludes VCS data, caches, build artifacts, and local virtualenvs.
Output contract When generating a Dockerfile for a user:
Return a complete Dockerfile.
State assumptions briefly (Python version, packaged vs unpackaged, startup command).
Add a short .dockerignore suggestion when missing.
agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试
147,400 周安装
