Cookiecutter Django 仓库开发与维护指南面向 AI 编码代理的完整工作手册【免费下载链接】cookiecutter-djangoCookiecutter Django is a framework for jumpstarting production-ready Django projects quickly.项目地址: https://gitcode.com/GitHub_Trending/co/cookiecutter-django本文基于仓库根目录的 AGENTS.md 编写。该文档是仓库维护者为 AI 编码代理AI coding agent提供的开发指引覆盖依赖安装、测试、lint、架构解析与新增模板选项的完整流程。读完本文你将理解 cookiecutter-django 作为 Cookiecutter 模板的独特工程结构掌握其三层测试体系与前后置钩子hooks的工作原理并能够安全地为模板新增一个可选项。项目本质一个模板而非一个 Django 应用cookiecutter-django 是一个Cookiecutter 模板template用于快速生成生产就绪production-ready的 Django 项目。它本身不是一个 Django 应用而是一套基于 Jinja2 语法的项目脚手架scaffold。这一本质区别决定了仓库的全部组织方式真正的模板内容位于{{cookiecutter.project_slug}}/目录下该目录名是字面的 Jinja2 变量占位符并非真实项目名用户运行 Cookiecutter 生成项目时该目录下的所有文件会被 Jinja2 渲染占位符被替换为用户的选择渲染、校验、清理等工作由 hooks/pre_gen_project.py 与 hooks/post_gen_project.py 两个钩子完成模板文件内的条件渲染语法如{% if cookiecutter.use_celery y %}决定了不同选项组合下生成项目的文件差异。理解这一点是阅读后续所有内容的前提任何对生成后项目的修改本质上都是对模板文件的修改必须以 Jinja2 条件逻辑 钩子清理的方式实现。开发环境与常用命令仓库依赖管理统一使用uvPython 版本要求为3.14见 pyproject.toml 中的requires-python 3.14.*。以下命令均在仓库根目录执行。安装依赖uv sync --locked--locked确保严格按照uv.lock锁定文件安装保证依赖可复现。运行测试仓库提供多层次的测试命令从单个用例到全量并行覆盖不同场景# 完整测试套件经 tox 并行执行 uv run tox run -e py # 直接使用 pytest 并行运行 uv run pytest -n auto tests # 运行单个测试 uv run pytest tests/test_cookiecutter_generation.py -k test_name # 启用可自动修复风格检查后运行AUTOFIXABLE_STYLES1 AUTOFIXABLE_STYLES1 uv run pytest -n auto tests其中AUTOFIXABLE_STYLES1环境变量会额外启用那些虽然能自动修复、但在模板源码中修复成本较高的风格类检查见 tests/test_cookiecutter_generation.pyCI 默认跳过它们本地调试时可显式开启。tox 侧的配置见 tox.inienvlist py314实际命令为pytest --instafail -n auto {posargs:./tests}即基于 pytest-xdist 的并行 失败即显instafail输出。Lint 与格式化# 运行所有 pre-commit 钩子 uv run pre-commit run --all-files # 仅运行 Ruff 检查与格式化 uv run ruff check --fix uv run ruff formatlint 与格式化相关配置集中在 pyproject.toml 的[tool.ruff]与[tool.djlint]段落详见下文编码约定。集成测试需要 Docker 或 PostgreSQL Redis集成测试会实际生成一个项目并运行其完整测试套件验证模板产物在真实环境中的可用性分为 Docker 与裸机bare metal两条路径# Docker 路径 sh tests/test_docker.sh # 使用 cookiecutter.json 默认选项 sh tests/test_docker.sh use_celeryy use_drfy # 传参覆盖选项 # 裸机路径需要本机运行 PostgreSQL 和 Redis sh tests/test_bare.sh sh tests/test_bare.sh use_celeryy frontend_pipelineGulp以 tests/test_docker.sh 为例脚本的执行链条很能说明问题在.cache/docker下用uv run cookiecutter ../../ --no-input --overwrite-if-exists use_dockery $生成项目 →docker compose build构建镜像 → 在容器内依次执行uv lock、mypy 类型检查、pytest、makemigrations --check确保没有遗漏迁移、makemessages --all翻译支持以及配置校验check --deploy级别需要注入一组环境变量。这意味着模板生成的每个项目在合并进主干前都要通过近乎生产标准的检查。本地调试生成一个项目uv run cookiecutter . --no-input --output-dir/tmp/debug该命令用仓库自身的默认配置cookiecutter.json在当前目录生成项目到/tmp/debug是排查模板问题时的首选调试手段可以快速得到一个完整渲染后的项目用于检查文件是否缺失、Jinja2 语法是否泄漏、配置是否正确。架构模板生成全流程AGENTS.md 用四个步骤概括了从用户运行 cookiecutter到项目落地的完整生命周期结合源码可以还原更精细的细节用户运行cookiecutterCookiecutter 依据 cookiecutter.json 中的变量定义逐个向用户提问项目名、slug、Docker、Celery、云厂商、前端管线等hooks/pre_gen_project.py校验输入在渲染前拦截非法或冲突的组合Jinja2 渲染{{cookiecutter.project_slug}}/下所有文件用用户选择替换模板变量条件块按选项展开hooks/post_gen_project.py约 550 行执行收尾删除所选选项不需要的文件、生成随机密钥、调整配置文件。前置校验pre_gen_project.pyhooks/pre_gen_project.py 的写法很特殊文件顶部嵌入了一段会被 Jinja2 求值的字符串字面量用于在钩子运行前更新上下文 {{ cookiecutter.update({ domain_name: cookiecutter.domain_name | trim }) }} {{ cookiecutter.update({ email: cookiecutter.email | trim }) }} 这段假字符串会被 Jinja 执行从而对domain_name和email做首尾空白裁剪。对应的测试 tests/test_cookiecutter_generation.py 验证当输入 example.com 时生成项目.envs/.production/.django中会出现DJANGO_ALLOWED_HOSTS.example.com证明裁剪确实生效。随后的断言覆盖了四类规则project_slug必须是合法 Python 标识符isidentifier且全小写——不满足直接assert失败author_name不允许包含反斜杠静态文件服务约束若use_whitenoise n且cloud_provider None则必须退出并提示用户否则生产环境静态文件无人服务邮件服务约束mail_service Amazon SES时cloud_provider必须是 AWS。这些约束与测试中的UNSUPPORTED_COMBINATIONS一一对应tests/test_cookiecutter_generation.py并由test_error_if_incompatible断言这些组合会抛出FailedHookException。后置清理post_gen_project.pyhooks/post_gen_project.py 是模板个性化的核心引擎main()函数按选项逐项执行删除/修改。从源码中可以归纳出几个关键机制随机密钥生成generate_random_string优先使用random.SystemRandom()加密安全随机源参考 Django 的django/utils/crypto.py并刻意从标点集合中剔除、、\、$等在环境变量里会出问题的字符hooks/post_gen_project.py。在此基础上set_django_secret_key生成 64 位字母数字密钥替换!!!SET DJANGO_SECRET_KEY!!!占位符set_django_admin_url生成 32 位随机串并补上/替换!!!SET DJANGO_ADMIN_URL!!!用于隐藏生产环境后台地址set_postgres_password、set_celery_flower_password同样生成 64 位强随机密码。占位符替换set_flag以读-替换-截断的方式原地改写文件hooks/post_gen_project.py。若系统缺少安全随机数生成器会打印警告并临时用占位符文本替代提示用户稍后手动补齐。按选项删除文件main()中通过一系列remove_*函数实现例如许可证open_source_license为 Not open source 时删除CONTRIBUTORS.txt与LICENSE非 GPLv3 时删除COPYING编辑器非 PyCharm 时递归删除.idea与docs/pycharmDockeruse_docker n时删除compose/、docker-compose.*.yml、.dockerignore、justfileuse_docker y时反而删除utility/本地脚本在容器化场景下无用前端管线无 Webpack/Gulp 时删除package.json、webpack/、sass 目录并移除 pre-commit 中的 prettier 配置选择 Gulp 或 Webpack 时则通过handle_js_runner改写package.json的scripts与devDependenciesCeleryuse_celery n时删除config/celery_app.py、用户tasks.py及测试CIci_tool非 Travis/Gitlab/Github/Drone 时分别删除对应的.travis.yml、.gitlab-ci.yml、.github/、.drone.ymlREST APIDRF 与 Django Ninja 互斥删除对方的 starter 文件两者都未选时整体删除users/api/目录异步use_async n时删除config/asgi.py与config/websocket.py。环境变量文件处理当既不使用 Docker 也不使用 Heroku 且keep_local_envs_in_vcs n时删除.envs目录及配套的merge_production_dotenvs_in_dotenv.py、tests否则向.gitignore追加.env、.envs/*并在keep_local_envs_in_vcs y时保留!.envs/.local/例外。该行为有单测覆盖tests/test_hooks.py 中的test_append_to_gitignore_file验证追加逻辑会正确换行写入。依赖落地setup_dependencies()用 uv 安装依赖——use_docker y时先构建精简的compose/local/uv/Dockerfile镜像tag 为cookiecutter-django-uv-runner:latest再通过docker run挂载当前目录执行 uv否则直接调用本机uv。随后分别以uv add --no-sync -r requirements/production.txt与uv add --no-sync --dev -r requirements/local.txt把依赖并入pyproject.toml最后删除requirements/目录与 uv 构建镜像目录。关键文件地图文件职责cookiecutter.json全部模板变量及可选值项目名、slug、Docker、Celery、云厂商、前端管线、邮件服务、CI 工具等是生成交互的数据源hooks/pre_gen_project.py生成前校验slug 合法性、选项冲突检测顶部用 Jinja2 语法更新上下文裁剪 domain/email 空白hooks/post_gen_project.py生成后清理按选项删文件、生成 Django secret key、设置数据库凭据、改写package.json与.pre-commit-config.yaml{{cookiecutter.project_slug}}/模板目录内部使用{% if cookiecutter.option y %}条件渲染控制内容取舍以cookiecutter.json为例当前模板的全部变量包括project_name、project_slug由project_name经 Jinja2 过滤器推导小写并替换空格/连字符/点为下划线、description、author_name、domain_name、email、version、open_source_licenseMIT/BSD/GPLv3/Apache 2.0/闭源、username_typeusername/email、timezone、windows、editorNone/PyCharm/VS Code、use_docker、postgresql_version18/17/16/15/14、cloud_providerAWS/GCP/Azure/None、mail_serviceMailgun/Amazon SES/Mailjet/Mandrill/Postmark/Sendgrid/Brevo/SparkPost/Other SMTP、rest_apiNone/DRF/Django Ninja、use_async、frontend_pipelineNone/Django Compressor/Gulp/Webpack、use_celery、mail_catcherNone/Mailpit/Mailtrap Local、use_sentry、use_whitenoise、use_heroku、ci_toolNone/Travis/Gitlab/Github/Drone、keep_local_envs_in_vcs、debug。注意{{cookiecutter.project_slug}}/目录下的文件不是可解析的 Python 源码包含未替换的 Jinja2 语法因此 ruff 通过extend-exclude将其排除在检查范围之外见 pyproject.toml。测试结构三层防护网仓库的测试体系可划分为三层共同保证模板在 50 种选项组合下仍能产出合格项目第一层模板渲染测试tests/test_cookiecutter_generation.py这是主测试文件基于pytest-cookies的cookies.bake()把模板烤制bake成真实项目。核心设施是SUPPORTED_COMBINATIONS——一个包含 50 个选项覆盖的列表tests/test_cookiecutter_generation.py覆盖每个许可证、编辑器、云厂商×邮件服务、PostgreSQL 版本、REST API、前端管线、CI 工具等并显式标注了不支持组合如cloud_providerNoneuse_whitenoisen。每个组合都会执行以下断言渲染完整性test_project_generation生成项目后用build_files_list遍历所有文件以正则{{(\s?cookiecutter)[.](https://link.gitcode.com/i/a0e554d62966db3f1174fbf1875f40d5)}}检查是否残留未替换的 Jinja2 变量check_paths并跳过二进制文件代码质量test_ruff_check_passes对生成项目运行ruff check .test_ruff_format_passes运行ruff format .后者标记为 auto-fixable默认跳过test_django_upgrade_passes以--target-version 5.0对全部.py运行 django-upgrade模板格式test_djlint_lint_passes与test_djlint_check_passes以 Jinja profile 校验生成的 HTML 模板CI 配置正确性test_travis_invokes_pytest、test_gitlab_invokes_precommit_and_pytest、test_github_invokes_linter_and_pytest分别解析生成的 CI 文件断言其中包含预期的 lint 与测试命令裸机为uv run pytestDocker 为docker compose -f docker-compose.local.yml run django pytest负面用例test_invalid_slug断言project slug、Project_Slug等非法 slug 触发FailedHookExceptiontest_error_if_incompatible断言UNSUPPORTED_COMBINATIONS中的组合全部失败行为细节test_pycharm_docs_removed验证编辑器选项决定docs/index.rst是否保留 PyCharm 配置文档test_trim_domain_email验证空白裁剪test_pyproject_toml验证作者信息写入生成项目的pyproject.tomltest_pre_commit_without_heroku验证未选 Heroku 时 pre-commit 配置中不会出现uv-pre-commit。该文件在 Windowssh模块不支持与 macOS CI过慢上会被跳过tests/test_cookiecutter_generation.py。第二层钩子单元测试tests/test_hooks.pytests/test_hooks.py 针对钩子中的辅助函数做轻量单测通过tmp_pathfixture 切换工作目录验证纯函数行为。目前覆盖的是append_to_gitignore_file向已有.gitignore追加.envs/*时能正确保留原有内容并补上换行。这是钩子逻辑可单测的示范——新增remove_*或set_*纯函数时应在此处补充对应测试。第三层集成测试tests/test_docker.sh / tests/test_bare.sh如前述这两条脚本把模板生成的完整项目拉起来跑真实测试套件含迁移检查、翻译生成、类型检查与部署配置校验是需要 Docker 或 PostgreSQLRedis 的端到端防线。它们通常不在日常pytest中执行而是作为发布前的重型验证。生成项目的内部布局模板生成的项目{{cookiecutter.project_slug}}/渲染后具备如下工程结构对应模板目录 {{cookiecutter.project_slug}}/config/settings/{base,local,test,production}.py—— 拆分式设置基于 django-environ 从环境变量读取配置config/urls.py—— URL 路由入口project_slug/users/—— 自定义用户模型基于 django-allauth支持用户名或邮箱登录由username_type决定compose/—— 本地与生产的 Docker 配置requirements/——已弃用依赖统一由pyproject.tomluv.lock管理生成时由setup_dependencies移除。编码约定仓库对贡献代码有一组明确的规范约束均可在 pyproject.toml 与 tox.ini 中验证Python 版本3.14requires-python 3.14.*行长度119 字符ruff 与 djLint 统一执行line-length 119/max_line_length 119Ruff负责 lint 与格式化配置在[tool.ruff]启用了覆盖 Abuiltins、Bbugbear、C4/C90复杂度、S安全、PERF性能、PLpylint等数十类规则集djLint负责 HTML 模板 lintprofile jinja适配 Jinja2 语法并设置custom_blocks element,slot、ignore_blocks raw模板文件豁免{{cookiecutter.project_slug}}/目录被排除在 ruff 检查之外其中不是可解析的 Python版本策略日历版本号Calendar versioning格式YYYY.MM.DD当前仓库版本为2026.9.4见 pyproject.toml。实战如何新增一个模板选项AGENTS.md 给出了新增选项的标准五步流程这是模板开发者最常遇到的需求结合前文源码可展开如下在 cookiecutter.json 中添加变量与可选值决定默认值字符串或列表列表会成为交互菜单例如新增use_something: n在 hooks/pre_gen_project.py 中添加必要校验如果新选项与其他选项存在冲突约束如 SES 依赖 AWS在此处assert或sys.exit在 hooks/post_gen_project.py 中添加文件删除/修改逻辑在main()中按条件调用新的remove_*函数或在set_flag系函数中生成新的随机凭据在模板文件{{cookiecutter.project_slug}}/下使用 Jinja2 条件如{% if cookiecutter.option y %}控制块级内容取舍在 tests/test_cookiecutter_generation.py 的SUPPORTED_COMBINATIONS中添加组合让新选项进入全量矩阵测试确保所有交叉组合下项目仍能通过渲染完整性、ruff、djLint 等全部断言。完成上述五步后还应检查是否需要同步更新 README.md 的功能清单Optional Integrations 部分与 docs/ 下的项目生成选项文档如果新选项涉及前端或 CI 行为还需通过 tests/test_docker.sh 等集成脚本做端到端验证。总结cookiecutter-django 的工程化精髓在于用 cookiecutter.json 声明选项、用前置钩子拦截非法输入、用后置钩子裁剪冗余文件并注入密钥、用 50 组合的矩阵测试保证每一种选择都能生成健康项目。AGENTS.md 正是这套机制的高度浓缩——对 AI 编码代理而言它是理解仓库边界、执行正确命令、遵循贡献流程的路线图对模板开发者而言它是从改一个文件到加一个完整选项的操作手册。本文所引用的源码、测试与配置均可直接在仓库对应路径中查看验证。【免费下载链接】cookiecutter-djangoCookiecutter Django is a framework for jumpstarting production-ready Django projects quickly.项目地址: https://gitcode.com/GitHub_Trending/co/cookiecutter-django创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考