使用 uv 编译特定源码的核心做法是调用 uv build 命令，该工具会自动解析项目配置并生成符合 pep 517/660 标准的构建后端产物。执行后会在当前目录生成 dist 文件夹，其中包含可直接安装的 .whl 或 .tar.gz 文件。若需指定特定的构建环境或清理旧产物，可配合 --clean 参数使用。
如何验证构建产物的具体类型与结构
构建完成后，可以通过检查 dist 目录下的文件后缀来确认生成的包类型。通常 uv build 默认会同时生成 wheel 和 sdist，但某些配置下可能只生成其一。通过查看生成的文件名可以直观判断。
import os
import glob
def check_build_output():
dist_path = "dist"
if not os.path.exists(dist_path):
print("No dist folder found. Run 'uv build' first.")
return
files = os.listdir(dist_path)
for f in files:
if f.endswith('.whl'):
print(f"Wheel generated: {f}")
elif f.endswith('.tar.gz'):
print(f"Sdist generated: {f}")
else:
print(f"Other file: {f}")
if __name__ == "__main__":
check_build_output()
运行上述脚本将列出 dist 目录中的实际内容。如果 pyproject.toml 中未指定后端，uv 会根据依赖自动推断。若项目中存在 setup.py 且未迁移至 pyproject.toml，uv 可能会报错或提示需要显式指定后端。
立即学习“Python免费学习笔记（深入）”；
如何在构建时排除特定文件或目录
在构建过程中，若希望排除某些测试文件或文档，可以在 pyproject.toml 中配置 tool.uv.build-backend 相关的打包规则，或者使用 MANIFEST.in（如果兼容）。更直接的方式是利用 uv 的源树模式，通过 source 字段控制包含关系。
[project]
name = "my-project"
version = "0.1.0"
[tool.uv]
# 配置 uv 特有的行为
build-backend = "hatchling.build"
[tool.hatch.build.targets.wheel]
include = [
"src/my_project",
"README.md"
]
exclude = [
"tests/**",
"docs/**"
]
上述配置展示了如何在 hatchling 后端中排除 tests 和 docs 目录。当执行 uv build 时，这些被排除的文件不会进入最终的 wheel 包中。这种细粒度的控制对于减少包体积和避免泄露内部测试代码非常有用。
基于 pyproject.toml 中 backend 配置的具体问题
当 pyproject.toml 中明确指定了 build-backend 为 hatchling.build 时，uv 会严格遵循该后端的规则进行构建。如果此时手动修改了 src 目录下的文件但未更新版本号，uv 不会自动重新计算哈希，而是直接使用缓存或重新构建。关键在于，uv 的构建过程是幂等的，除非输入文件发生变动或强制刷新。
