5.6.2 可复现示例

原文链接: https://docs.astral.sh/uv/reference/troubleshooting/reproducible-examples/

5.6.2 可复现示例

为什么可复现示例很重要

最小可复现示例（MRE）对修复缺陷至关重要。没有能用来复现问题的示例，维护者就无法调试它，也无法测试它是否被修复。如果示例不是最小的，也就是说它包含大量与问题无关的内容，维护者识别问题根因所需的时间会大大增加。

如何编写可复现示例

编写可复现示例时，目标是提供让他人复现你的示例所需的全部上下文，包括：

• 你使用的平台（例如操作系统和架构）

• 任何相关的系统状态（例如显式设置的环境变量）

• uv 的版本

• 其他相关工具的版本

• 相关文件（uv.lock、pyproject.toml 等）

• 要运行的命令

为确保复现示例最小化，请尽可能移除依赖、设置和文件。分享之前请务必测试你的复现示例。我们建议附上复现过程中的详细日志；它们在你的机器上可能有关键差异。对于很长的日志，使用 Gist 会很有帮助。

下面我们会介绍几种创建和分享可复现示例的具体策略。

提示

Stack Overflow 上有一篇关于创建 MRE 基础知识的优秀指南。

可复现示例的策略

Docker 镜像

编写 Docker 镜像往往是分享可复现示例的最佳方式，因为它完全自包含。这意味着复现者系统的状态不会影响问题。

注意

只有在问题能在 Linux 上复现时，使用 Docker 镜像才可行。使用 macOS 时，谨慎的做法是确认你的镜像在 Linux 上不能复现 —— 但有些缺陷是特定于操作系统的。虽然用 Docker 运行 Windows 容器是可行的，但并不常见。这类缺陷预期以脚本形式报告。

编写 uv 的 Docker MRE 时，最好从 uv 的 Docker 镜像之一开始。这样做时，务必把版本固定到特定的 uv 版本。

1

FROM ghcr.io/astral-sh/uv:0.12.0-debian-slim

虽然 Docker 镜像与系统隔离，但构建默认会使用你系统的架构。分享复现示例时，可以显式设置平台以确保复现者得到预期的行为。uv 为 linux/amd64（例如 Intel 或 AMD）和 linux/arm64（例如 Apple M 系列或 ARM）发布镜像。

1

FROM --platform=linux/amd64 ghcr.io/astral-sh/uv:0.12.0-debian-slim

Docker 镜像最适合复现可以用命令构造的问题，例如：

1
2
3
4
5
6
7

FROM --platform=linux/amd64 ghcr.io/astral-sh/uv:0.12.0-debian-slim

RUN uv init /mre
WORKDIR /mre
RUN uv add pydantic
RUN uv sync
RUN uv run -v python -c "import pydantic"

不过你也可以把文件内联写入镜像：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

FROM --platform=linux/amd64 ghcr.io/astral-sh/uv:0.12.0-debian-slim

COPY <<EOF /mre/pyproject.toml
[project]
name = "example"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = ["pydantic"]
EOF

WORKDIR /mre
RUN uv lock

如果你需要写入很多文件，更好的做法是创建并发布一个 Git 仓库。也可以结合这些方式，在仓库中包含一个 Dockerfile。

分享 Docker 复现示例时，附上构建日志会很有帮助。可以通过禁用缓存和花哨输出看到构建步骤的更多输出：

1

docker build . --progress plain --no-cache

脚本

报告无法在容器中复现的平台相关缺陷时，最佳实践是附上一个脚本，展示可用于复现该缺陷的命令，例如：

1
2
3
4

uv init
uv add pydantic
uv sync
uv run -v python -c "import pydantic"

如果你的复现示例需要很多文件，请使用 Git 仓库来分享它们。

除脚本之外，请附上失败的详细日志（即带 -v 标志）以及完整的错误信息。

只要脚本依赖外部状态，请务必分享该信息。例如，如果你是在 Windows 上编写该脚本，并且它使用的是用 choco 安装的 Python 版本、运行在 PowerShell 6.2 上，请在报告中说明。

Git 仓库

分享 Git 仓库形式的复现示例时，请附上一个能复现问题的脚本，或者更好的做法是附上 Dockerfile。脚本的第一步应当是克隆仓库并检出特定提交：

1
2
3
4

$ git clone https://github.com/<user>/<project>.git
$ cd <project>
$ git checkout <commit>
$ <产生错误的命令>

你可以在 GitHub UI 中或用 gh CLI 快速创建新仓库：

1

$ gh repo create uv-mre-1234 --clone

使用 Git 仓库做复现示例时，请记得通过排除复现问题不需要的文件或设置来最小化其内容。