Cookiecutter：用模板一键生成项目的命令行工具

Cookiecutter：用模板一键生成项目的命令行工具

Cookiecutter 是一个命令行工具，用于从项目模板快速创建新项目。目前在 GitHub 上已获得约 2.5 万 Star，是项目脚手架领域使用广泛的工具之一。

它的核心思路是事先定义好一套项目结构和变量占位符。使用时只需回答几个提示问题，工具就能在短时间内生成完整的项目目录。这对需要频繁创建同类项目的开发者来说，能节省大量重复劳动。

安装与基本用法

Cookiecutter 支持通过 uv 直接安装为 CLI 工具：

uv tool install cookiecutter

安装完成后，最常见的用法是指定一个远程或本地模板来生成项目。例如使用 GitHub 上的 Python 包模板：

uvx cookiecutter gh:audreyfeldroy/cookiecutter-pypackage

执行后会弹出若干提示，要求填写项目名称、作者、版本号等信息。回答完毕后，工具会在当前目录下生成完整的项目结构，包括配置文件、源代码目录、测试目录等。

如果需要在 Python 代码中调用，也可以直接导入模块：

from cookiecutter.main import cookiecutter

cookiecutter('cookiecutter-pypackage/')

这种方式适合在自动化脚本或更大型的工具链中集成。

跨平台与多语言支持

Cookiecutter 兼容 Windows、Mac 和 Linux，支持 Python 3.10 至 3.14。虽然它本身是一个 Python 工具，但模板内容不限于 Python 项目。无论是 Rust、Terraform 还是文档站点，只要是需要重复生成的项目结构，都可以做成 Cookiecutter 模板。模板文件可以是任意语言或标记格式。

这意味着不同技术栈的团队都能用同一套工具来管理项目模板，无需为每种语言单独寻找脚手架方案。

模板机制

一个 Cookiecutter 模板本质上是一个包含变量声明的目录。模板根目录下的 cookiecutter.json 文件定义了所有变量及其默认值。用户回答提示后，工具会将这些变量替换到模板中的文件名和内容里。

模板还可以包含生成前后的钩子脚本。pre generate hook 在文件生成前执行，可用于验证用户输入或前置条件检查。post generate hook 在文件生成后执行，常用于初始化 git 仓库、安装依赖、运行代码格式化工具等后续操作。这些钩子脚本可以用 shell 或 Python 编写。

这种设计让模板不仅负责文件结构的复制，还能承担一部分项目初始化后的自动化配置工作。

实际场景

Cookiecutter 特别适合以下场景：

团队内部需要统一新项目结构。无论是 Python 包、Web 服务还是 CLI 工具，都可以维护一套官方模板，确保每个新项目的目录结构、配置文件和基础代码都符合规范。

开源社区维护项目模板，降低新用户的上手成本。很多框架都提供了 Cookiecutter 模板，新用户一条命令就能生成可运行的基础项目。

个人有大量重复性的项目初始化工作。如果你经常需要从零搭建相同类型的项目，把常用结构做成模板后，每次只需回答问题就能拿到现成代码。

社区已经积累了大量现成模板，涵盖 Django、Pytest 插件、Plone 等多种框架，可以直接使用或在此基础上定制。

总结

Cookiecutter 解决的是一个具体且常见的问题：减少项目初始化的重复工作。它不涉及复杂的配置，上手门槛低，输出稳定。模板机制简单直接，钩子脚本又提供了足够的扩展空间。如果你或你的团队经常需要从零创建同类项目，这个工具值得一试。