Copier：3.3k Star 的项目模板引擎，生成之后还能持续更新

Copier：3.3k Star 的项目模板引擎，生成之后还能持续更新

Copier 是一个用 Python 写的项目模板工具，提供了命令行和 Python API 两种交互方式，目前在 GitHub 上有 3,362 个 Star。

Copier 的工作方式：先创建一个模板仓库，在里面定义好目录结构、文件骨架和变量占位符。使用者运行生成命令后，Copier 按模板配置逐步提问，收集答案，再将答案填入模板，在目标路径下生成新的项目。

模板的存放位置可以是本地目录，也可以是远程 Git 仓库。文件名、文件夹名以及文件里的文本内容，都可以用 Jinja 模板语法嵌入变量占位符，Copier 在渲染阶段统一替换。

Copier 围绕三个核心概念来组织功能：

• 模板（Template）：一个包含 copier.yml 配置文件的 Git 仓库，仓库里有设好占位符的目录结构和文本文件。模板是整套生成逻辑的载体。
• 问卷（Questionnaire）：在 copier.yml 中声明的一组问题，每个问题支持设置类型（字符串、布尔、整数、列表等）、默认值和帮助文字。使用者的回答在渲染阶段传给 Jinja 引擎，替换模板中的变量。
• 项目（Project）：从模板渲染生成的代码库。项目创建时，根目录下会自动生成一个 answers 文件，里面记录了本次生成所使用的全部回答，这份记录是后续执行项目更新操作的关键依据。

很多脚手架工具只做一次性生成，生成完就跟模板断开关系了。Copier 的设计目标里包含"代码生命周期管理"，生成出来的项目跟模板之间保持着持续关联。模板创建者改进模板后，项目使用者只需要在项目目录下执行更新命令，Copier 就会拉取最新模板，结合之前保存的 answers 文件重新渲染，把差异合并到项目中。如果合并碰到手动修改过的区域，Copier 会提示冲突，交由使用者处理。

创建模板

一个 Copier 模板的目录结构大致如下：

my_copier_template/
├── copier.yml
├── {{project_name}}/
│   └── {{module_name}}.py.jinja
└── {{_copier_conf.answers_file}}.jinja

核心文件是 copier.yml，里面声明向使用者提出的问题：

project_name:
    type: str
    help: What is your project name?

module_name:
    type: str
    help: What is your Python module name?

模板化的源文件放在 {{project_name}}/ 这样的 Jinja 文件夹下，内容同样嵌入 Jinja 语法。比如 {{module_name}}.py.jinja：

print("Hello from {{module_name}}!")

还有一个特殊的 {{_copier_conf.answers_file}}.jinja，它在生成后的项目中变成 .copier-answers.yml，保存了全部回答记录。

安装与环境

运行 Copier 需要 Python 3.10 以上和 Git 2.27 以上。

作为命令行工具安装：

pipx install copier

在 macOS 或 Linux 上也可以通过 Homebrew 安装：

brew install copier

在 Python 项目中作为库引入：

pip install copier

日常使用

从模板生成新项目，命令行方式：

copier copy path/to/template path/to/destination

也可以从 Git 仓库生成模板：

copier copy https://github.com/username/template.git path/to/destination

更新已有项目：

copier update path/to/destination

Copier 会自动检测当前项目关联的模板仓库，拉取最新版本，对比 answers 文件重新渲染后合并差异。

Python API 的调用方式：

from copier import run_copy, run_update

# 从本地路径生成
run_copy("path/to/template", "path/to/destination")

# 从 Git URL 生成，支持 gh: 和 gl: 简写
run_copy("gh:copier-org/copier.git", "path/to/destination")

# 更新已有项目
run_update("path/to/destination")

Copier 面向的角色分两类。第一类是模板创建者，主要是需要频繁生成同类型项目结构的开发者，比如管理多个微服务或 Python 包的团队，用模板统一风格，减少手动拷贝。第二类是模板消费者，关注点在快速启动项目，以及后续能方便地跟进模板的改进。

GitHub 上以 copier-template 为标签可以浏览社区公开的模板，涵盖 Python 包、Web 应用、CI 配置等多种场景，可以直接参考或改造成自己的版本。