uv 0.12.0 调整项目初始化默认结构

uv 0.12.0 的主要变化

uv 0.12.0 带来了一些值得注意的破坏性变更，尤其体现在 uv init 命令生成的默认项目结构上。

uv init 是 uv 用来创建新项目的快捷命令。在 0.11.x 版本中，运行：

uv init uv-init

会生成一个较为扁平的项目结构，其中包括位于项目根目录下的 main.py。

到了 uv 0.12.0，默认生成结果发生了明显变化。

默认改用 src/ 布局

新版 uv init 不再默认把 main.py 放在项目根目录，而是生成一个符合 src/ 布局的包结构。

变化包括：

• 删除原先根目录下的 main.py
• 新增类似 src/uv_init/__init__.py 的包文件
• 在其中定义带有类型标注的 main() -> None 函数
• 默认输出类似 Hello from uv-init 的示例内容

这意味着 uv init 生成的新项目更接近 Python 包发布场景下常见的结构。

默认配置 uv_build

uv 0.12.0 还会在 pyproject.toml 中配置构建后端。

新版项目会加入 build-system 配置，使用 uv_build 作为 build backend。这样在运行：

uv build

时，可以用于构建 wheel 和 .tar.gz 分发文件。

自动设置脚本入口

新版初始化项目还会在 pyproject.toml 中配置脚本入口。

例如，项目会设置一个类似 uv-init 的脚本别名，并将其指向包中的 main() 函数：

[project.scripts]
uv-init = "uv_init:main"

之后可以通过以下命令运行：

uv run uv-init

该命令会执行 src/uv_init/__init__.py 中定义的 main() 函数。

对 Python 项目模板的影响

这次变化说明，uv init 的默认项目模板正在向更标准的 Python 包结构靠拢：

• 从扁平布局转向 src/ 布局
• 默认具备构建发布配置
• 默认提供命令行脚本入口

对于习惯旧版 uv init 输出结构的用户，这属于需要注意的破坏性变化。对于新项目而言，这也可能减少后续手动调整包结构、构建配置和脚本入口的工作量。

src/ 布局长期以来是 Python 打包社区讨论较多的实践之一。随着 uv init 默认采用这一结构，未来使用 uv 创建项目的开发者可能会更自然地进入这种项目组织方式。