企业官网建设流程全解析

• 开发工具
• CLI
• 代码生成

导读

本指南围绕 Cookiecutter 的高级特性_jinja2_env_vars，讲解如何在模板的cookiecutter.json中直接定制项目生成时使用的 Jinja2 渲染环境——从最常用的空白控制（lstrip_blocks、trim_blocks）到定界符替换（variable_start_string/variable_end_string）。读完本文，你将掌握该配置项的完整语法、底层实现原理、可配置参数及其适用边界，并能在自己的模板中安全地启用这些能力。

一、什么是_jinja2_env_vars

Cookiecutter 生成项目时，所有模板文件（以及目录名、文件名）都会经过一个 Jinja2Environment对象进行渲染。默认情况下，这个环境使用 Cookiecutter 内置的严格模式配置，但开发者可能需要对渲染行为做细粒度调整，例如：

• 控制模板中{% ... %}块周围的空白处理；
• 修改变量定界符（{{ }}）以适应特殊场景；
• 传递其他 Jinja2Environment构造函数支持的参数。

为此，Cookiecutter 提供了一条特殊的（下划线前缀的）私有配置项_jinja2_env_vars。它定义在模板根目录的cookiecutter.json中，以普通 JSON 对象的形式声明，键名与 Jinja2Environment构造函数的参数名一一对应。

二、官方示例：控制模板空白

官方文档给出的经典示例是在cookiecutter.json中启用lstrip_blocks与trim_blocks：

{ "project_slug": "sample", "_jinja2_env_vars": {"lstrip_blocks": true, "trim_blocks": true} }

这两个参数的作用

• trim_blocks：开启后，{% ... %}语句块（如{% if %}、{% for %}）之后的第一个换行符会被自动移除，避免渲染结果中残留多余空行；
• lstrip_blocks：开启后，{% ... %}语句块之前的空白字符会被剥离，使模板源码可以缩进排版，而渲染结果不会带上前导空格。

仓库中的测试 tests/test_generate_files.py（test_generate_files_with_jinja2_environment）正是用{'lstrip_blocks': True, 'trim_blocks': True}渲染了tests/test-generate-files/input{{cookiecutter.food}}/simple-with-conditions.txt这一嵌套条件模板：

{% if cookiecutter %} {% if cookiecutter.food %} I eat {{ cookiecutter.food }} {% endif %} {% endif %}

模板中{% ... %}前的缩进和块后的换行，在开启两个参数后不会污染输出。测试断言渲染结果为单行I eat pizzä\n，直接验证了空白控制效果——这正是该配置项最典型、最实用的场景。

三、底层实现原理

3.1 配置读取与传递

_jinja2_env_vars的读取发生在 cookiecutter/utils.py 的create_env_with_context函数中：

def create_env_with_context(context: dict[str, Any]) -> StrictEnvironment: """Create a jinja environment using the provided context.""" envvars = context.get('cookiecutter', {}).get('_jinja2_env_vars', {}) return StrictEnvironment(context=context, keep_trailing_newline=True, **envvars)

关键点有二：

1. 取值路径固定：配置必须位于上下文根的cookiecutter键之下，即cookiecutter.json中的_jinja2_env_vars；
2. 展开传递：字典通过**envvars展开为关键字参数，原样传给 Jinja2Environment的构造函数。也就是说，凡是 Jinja2Environment.__init__支持的参数，都可以在这里声明。

3.2 与默认环境的叠加规则

StrictEnvironment的定义在 cookiecutter/environment.py：

class StrictEnvironment(ExtensionLoaderMixin, Environment): def __init__(self, **kwargs: Any) -> None: super().__init__(undefined=StrictUndefined, **kwargs)

从中可以提炼出三条叠加规则：

• undefined=StrictUndefined由 Cookiecutter 硬编码传入，保证模板中引用未定义变量时立即抛出错误（而非静默输出空字符串）。该行为不受_jinja2_env_vars影响，你无法通过该配置项关闭严格模式——这是刻意的安全设计；
• keep_trailing_newline=True同样由create_env_with_context固定注入，确保文件末尾换行不被模板引擎吞掉，从而避免生成文件意外丢失结尾换行；
• 其余参数则完全由你的_jinja2_env_vars决定，未声明的项一律采用 Jinja2 默认值。

3.3 扩展加载不受影响

StrictEnvironment通过ExtensionLoaderMixin（cookiecutter/environment.py）加载扩展：先注册内置扩展（JsonifyExtension、RandomStringExtension、SlugifyExtension、TimeExtension、UUIDExtension），再合并cookiecutter.json中_extensions指定的自定义扩展。这一过程与_jinja2_env_vars完全正交——定制环境参数不会影响扩展的注册与加载。

四、进阶用法：自定义定界符

_jinja2_env_vars并不局限于空白控制。仓库测试 tests/test_find.py 展示了另一个典型场景：自定义变量定界符。

fake-repo-pre2模板的目录名写作{%{cookiecutter.repo_name}%}，对应的上下文配置为：

{ 'cookiecutter': { '_jinja2_env_vars': { 'variable_start_string': '{%{', 'variable_end_string': '}%}', } } }

这里通过variable_start_string和variable_end_string将默认的{{ ... }}改为{%{ ... }%}。值得注意的是，定界符定制会同步影响模板目录的查找逻辑：find_template（见 cookiecutter/find.py）正是用env.variable_start_string和env.variable_end_string来识别哪个子目录是项目模板：

if ( 'cookiecutter' in str_path and env.variable_start_string in str_path and env.variable_end_string in str_path ): project_template = Path(repo_dir, str_path) break

因此，当模板目录名使用了非默认定界符时，必须在_jinja2_env_vars中同步声明对应的定界符，否则find_template将抛出不带模板目录的NonTemplatedInputDirException——测试中的第三个用例正是用fake-repo-pre（默认{{ }}目录名）搭配自定义定界符来验证这一失败场景。

五、可配置参数与使用注意事项

5.1 常用可配置参数一览

需要说明的是，lstrip_blocks、trim_blocks、variable_start_string等参数的语义与默认值均继承自 Jinja2Environment本身，_jinja2_env_vars只是把这些参数的设置入口暴露到了模板配置层；上文表格中标注"由 Jinja2 环境透传支持"的行，表示仓库通过**envvars无条件透传，实际效果以 Jinja2 版本行为为准。

5.2 注意事项

1. 以_开头是私有约定：_jinja2_env_vars与其他下划线前缀配置（如_extensions、_copy_without_render、_new_lines）一样，属于模板元配置而非用户提示变量，不会出现在交互式提问中，也不会被渲染进生成文件；
2. JSON 类型限制：由于配置写在cookiecutter.json中，参数值只能是 JSON 支持的布尔、字符串、数字等类型。函数、回调等复杂对象无法通过此途径配置，这类需求应改在hooks/中通过 从 Python 调用 Cookiecutter 的方式自行构造环境；
3. 全局生效：_jinja2_env_vars作用于整个模板生成过程——目录名渲染、文件名渲染、文件内容渲染以及模板目录查找全部使用同一个环境对象，不存在"只对某类文件生效"的细粒度控制；
4. 严格模式不可关闭：StrictUndefined是 Cookiecutter 的安全底线，未定义变量会直接中断生成并给出明确报错。若模板中确有"可能未定义"的变量，应使用 Jinja2 的default过滤器显式兜底，而非尝试覆盖undefined参数；
5. 与_new_lines的区别：_jinja2_env_vars控制 Jinja2 模板引擎的解析与渲染行为，而换行符输出由独立的_new_lines配置（见 docs/advanced/new_line_characters.rst）决定，两者职责不同，不要混淆。

六、快速验证

你可以用仓库自带的测试数据快速验证这一机制。在仓库根目录执行：

python -m pytest tests/test_generate_files.py::test_generate_files_with_jinja2_environment -v python -m pytest tests/test_find.py -v

前者验证空白控制（lstrip_blocks/trim_blocks），后者验证自定义定界符及其对模板目录识别的影响。此外，也可参考 tests/test-generate-files/input{{cookiecutter.food}}/simple-with-conditions.txt 中的嵌套条件模板，对比开启与不开启该配置时的输出差异，直观感受渲染结果的变化。

总结

_jinja2_env_vars是 Cookiecutter 将底层 Jinja2Environment配置能力暴露给模板作者的关键通道。通过一条简单的 JSON 配置，即可控制空白处理、自定义定界符等渲染行为，而无需修改 Cookiecutter 自身代码。理解其读取链路（create_env_with_context→StrictEnvironment→ Jinja2Environment）、叠加规则（StrictUndefined与keep_trailing_newline固定、其余透传）以及"环境定制同时作用于模板查找"这一联动效应，是安全、高效使用该特性的前提。

• 开发工具
• CLI
• 代码生成