企业官网建设流程全解析

Cookiecutter Django 实战指南：用脚手架快速生成生产级 Django 项目

【免费下载链接】cookiecutter-djangoCookiecutter Django is a framework for jumpstarting production-ready Django projects quickly.项目地址: https://gitcode.com/GitHub_Trending/co/cookiecutter-django

本文是一份面向 Django 开发者的 Cookiecutter Django 实战指南。Cookiecutter Django 是构建在 Cookiecutter 之上的 Django 项目脚手架框架，它把 Django 项目从零到生产所需的配置、目录结构、安全基线、CI/CD、容器化与部署方案全部模板化，让你在回答完一轮交互式提问后就能获得一个具备 100% 初始测试覆盖率、开箱即用且符合 12-Factor 规范的 Django 工程。读完本文，你将掌握 Cookiecutter Django 的安装方式、全部生成选项的含义与取舍、项目生成的内部机制（pre/post 钩子），以及生成后本地开发与部署的完整工作流。

项目定位：为什么要用 Cookiecutter Django

与其反复执行django-admin startproject再手工补齐各种"总是忘记配置到最后一刻"的细节（作者邮箱、密钥、域名、静态资源、安全头……），不如把这一整套决策交给 Cookiecutter Django。它基于 Cookiecutter 模板引擎工作：模板仓库中大量使用 Jinja2 语法（如{{ cookiecutter.project_slug }}），你的每一次回答都会注入到生成文件的每一个角落，最终渲染出一个完整、独立、可直接运行的项目。

在开始之前，请先理解本模板的三个硬性约束（详见仓库根目录 README.md 的 "Constraints" 一节）：

• 只使用持续维护的第三方库，避免项目从第一天就背上失维护依赖的负担；
• 数据库一律使用 PostgreSQL（14–18），如确需 MySQL，官方维护了一个 MySQL 分支（外部链接，仅作提示，不在本文展开）；
• 一切配置通过环境变量注入，这意味着 Apache/mod_wsgi 这类无法提供环境变量的部署方式不被支持，项目主要面向 Gunicorn/Nginx、uWSGI/Nginx、Docker 等部署形态。

核心特性一览

以下特性均来自模板默认输出，除非在生成时显式关闭（README.md "Features" 一节）：

• 面向Django 6.0，兼容Python 3.14；
• 生成的 Django 项目初始测试覆盖率为 100%，模板自带用户模块的模型、表单、视图、任务、URL、API 全套测试；
• 前端采用Twitter Bootstrap v5样式体系；
• 基于 django-environ 的12-Factor 风格配置，环境变量与 Django settings 一一映射；
• 安全默认值：SSL 优先、HttpOnly Cookie、X_FRAME_OPTIONS = "DENY"等安全设置开箱即用；
• 区分开发/生产两套优化过的 settings；
• 用户注册认证基于 django-allauth，支持邮箱/用户名登录、邮箱验证、MFA、社交账号；
• 内置自定义 User 模型（AUTH_USER_MODEL = "users.User"），从第一天就避免"后期替换 User 模型"这个 Django 最痛苦的迁移难题；
• 可选的ASGI 基础配置（Websocket + Uvicorn/Gunicorn）；
• 可选的Gulp 或 Webpack 前端构建管线；
• 邮件发送基于 Anymail：默认 Mailgun，若云厂商选 AWS 则默认 Amazon SES，且可随时切换；
• 媒体存储支持Amazon S3、Google Cloud Storage、Azure Storage 或 nginx；
• Docker 支持：开发与生产两套 docker-compose，生产侧使用 Traefik 并内置 LetsEncrypt 证书支持；
• 提供Procfile，可直接部署到 Heroku；
• 提供PythonAnywhere部署指引；
• 测试可用unittest 或 pytest；
• PostgreSQL 版本可选（14–18）；
• 默认集成pre-commit，在提交代码审查前先自动发现简单问题。

可选集成（生成时按需启用）

以下功能在项目初始生成阶段决定是否启用（README.md "Optional Integrations" 一节）：

• 静态文件由Amazon S3、Google Cloud Storage、Azure Storage 或 WhiteNoise之一托管；
• Celery + Flower异步任务配置（Flower 仅在 Docker 方案中提供）；
• 本地邮件测试接入Mailpit或Mailtrap Local；
• 错误日志接入Sentry。

快速上手：安装与生成项目

第一步：安装 Cookiecutter

使用 uv 安装（要求cookiecutter>=1.7.0）：

uv tool install "cookiecutter>=1.7.0"

第二步：运行模板生成项目

以创建一个名为 "redditclone" 的项目为例。与其startproject之后再手工修补，不如让 Cookiecutter 一次搞定：

uvx cookiecutter https://gitcode.com/GitHub_Trending/co/cookiecutter-django

（等价地，你也可以先git clone该仓库到本地，再对本地路径运行uvx cookiecutter <本地路径>。）

命令执行后，你会被逐一提问。以下是 README.md 中完整的交互实录，展示了所有提问与典型回答：

Cloning into 'cookiecutter-django'... remote: Counting objects: 550, done. remote: Compressing objects: 100% (310/310), done. remote: Total 550 (delta 283), reused 479 (delta 222) Receiving objects: 100% (550/550), 127.66 KiB | 58 KiB/s, done. Resolving deltas: 100% (283/283), done. project_name [My Awesome Project]: Reddit Clone project_slug [reddit_clone]: reddit description [Behold My Awesome Project!]: A reddit clone. author_name [Daniel Roy Greenfeld]: Daniel Greenfeld domain_name [example.com]: myreddit.com email [daniel-greenfeld@example.com]: pydanny@gmail.com version [0.1.0]: 0.0.1 Select open_source_license: 1 - MIT 2 - BSD 3 - GPLv3 4 - Apache Software License 2.0 5 - Not open source Choose from 1, 2, 3, 4, 5 [1]: 1 Select username_type: 1 - username 2 - email Choose from 1, 2 [1]: 1 timezone [UTC]: America/Los_Angeles windows [n]: n Select an editor to use. The choices are: 1 - None 2 - PyCharm 3 - VS Code Choose from 1, 2, 3 [1]: 1 use_docker [n]: n Select postgresql_version: 1 - 18 2 - 17 3 - 16 4 - 15 5 - 14 Choose from 1, 2, 3, 4 [1]: 1 Select cloud_provider: 1 - AWS 2 - GCP 3 - None Choose from 1, 2, 3 [1]: 1 Select mail_service: 1 - Mailgun 2 - Amazon SES 3 - Mailjet 4 - Mandrill 5 - Postmark 6 - Sendgrid 7 - Brevo (formerly SendinBlue) 8 - SparkPost 9 - Other SMTP Choose from 1, 2, 3, 4, 5, 6, 7, 8, 9 [1]: 1 Select rest_api [None]: 1 - None 2 - DRF 3 - Django Ninja Choose from 1, 2, 3 [1]: 1 use_async [n]: n Select frontend_pipeline: 1 - None 2 - Django Compressor 3 - Gulp 4 - Webpack Choose from 1, 2, 3, 4 [1]: 1 use_celery [n]: y Select mail_catcher: 1 - None 2 - Mailpit 3 - Mailtrap Local Choose from 1, 2, 3 [1]: 1 use_sentry [n]: y use_whitenoise [n]: n use_heroku [n]: y Select ci_tool: 1 - None 2 - Travis 3 - Gitlab 4 - Github Choose from 1, 2, 3, 4 [1]: 4 keep_local_envs_in_vcs [y]: y debug [n]: n

回答完毕后，一个 Django 项目便已生成。

注意：生成之后，务必把Daniel Greenfeld、pydanny等模板占位信息替换为你自己的信息（README.md 中的明确警告）。

第三步：进入项目并提交版本库

cd reddit/ ls git init git add . git commit -m "first awesome commit" git remote add origin git@github.com:pydanny/redditclone.git git push -u origin main

提交前请务必仔细阅读生成项目根目录的 README——它针对你的具体选项生成了对应的本地开发指引。

生成选项全解析

模板的全部选项定义在仓库根目录 cookiecutter.json 中，其权威说明见 docs/1-getting-started/project-generation-options.rst。下表按提问顺序逐项说明：

选项之间的联动与约束

几个选项存在交叉影响，需要特别留意：

• 静态文件与媒体文件的托管组合：若cloud_provider选 None 且use_docker为 n，模板会在生成时打印警告：生产环境媒体文件将无法被提供；若选 None 但启用了 Docker，则生产栈会通过一个nginx Docker 服务来提供媒体文件。
• 安全兜底校验：生成前钩子 hooks/pre_gen_project.py 会强制校验两条组合规则：
  • 若use_whitenoise为 n 且cloud_provider为 None，则静态文件将无处托管，直接sys.exit(1)终止生成；
  • 若mail_service为 Amazon SES 但cloud_provider不是 AWS，同样会终止生成并提示你改用 AWS 或更换邮件服务。
• slug 合法性校验：同一个 pre 钩子还会断言project_slug是合法 Python 标识符（isidentifier()）、必须全小写，且author_name不能包含反斜杠；它还会通过 Jinja 上下文更新逻辑对domain_name和email做首尾空白修剪。

生成机制探秘：pre/post 钩子如何工作

Cookiecutter 在执行渲染前后会分别调用模板中的hooks/目录脚本，本仓库的实现正是"回答完提问就能得到完整项目"的关键。

pre 钩子（hooks/pre_gen_project.py）在渲染之前运行，职责是"拦截非法组合"，除上述校验外，其顶部的 Jinja 代码还会更新 cookiecutter 上下文，对域名和邮箱做trim处理。

post 钩子（hooks/post_gen_project.py）在渲染之后运行，职责是"按你的选项裁剪项目"，主要工作包括：

• 注入随机密钥：调用generate_random_string()（基于random.SystemRandom，失败时回退普通随机并给出警告），为生产环境生成 64 位DJANGO_SECRET_KEY、32 位DJANGO_ADMIN_URL（格式为{随机串}/）、随机的 PostgreSQL 用户/密码、Celery Flower 用户/密码，并替换.envs/.local/与.envs/.production/以及config/settings/local.py、test.py中的占位符；
• 按许可证裁剪文件：选择 "Not open source" 时删除CONTRIBUTORS.txt与LICENSE；非 GPLv3 时删除COPYING；
• 按编辑器裁剪：非 PyCharm 时删除.idea/与docs/pycharm/；
• 按 Docker/云厂商/Heroku 裁剪：不用 Docker 时删除compose/、docker-compose.*.yml、justfile、.devcontainer等；选 Docker 且非 AWS 时删除 AWS 专用 Dockerfile；不用 Heroku 时删除Procfile与bin/；
• 按前端管线裁剪：None / Django Compressor 时删除 Gulp、Webpack、Sass、package.json及对应 pre-commit 配置；Gulp 或 Webpack 时则通过update_package_json()精确改写package.json的依赖与脚本（如 Webpack 无 Docker 时用concurrently同时启动 webpack dev server 与 Django 开发服务器）；
• 按 Celery/CI/API/异步裁剪：分别删除未选组件的celery_app.py、CI 配置文件（.travis.yml、.gitlab-ci.yml、.github/、.drone.yml）、DRF/Ninja 的 starter 文件与asgi.py/websocket.py；
• 依赖装填：setup_dependencies()用uv把requirements/production.txt（作为正式依赖）与requirements/local.txt（作为--dev依赖）写入pyproject.toml/uv.lock，随后删除requirements/目录——若启用 Docker，则会先构建一个精简的compose/local/uv/Dockerfile镜像再在容器内执行 uv，避免污染宿主机环境。

模板自带的钩子测试见 tests/test_hooks.py，完整的端到端生成测试见 tests/test_cookiecutter_generation.py，它们分别验证了钩子行为与生成结果的可运行性。

生成的目录结构：Two Scoops 双层布局

生成项目的布局遵循 "Two Scoops of Django" 一书的双层结构（docs/2-local-development/developing-locally.rst）：

<repository_root>/ ├── config/ │ ├── settings/ │ │ ├── __init__.py │ │ ├── base.py │ │ ├── local.py │ │ └── production.py │ ├── urls.py │ └── wsgi.py ├── <django_project_root>/ │ ├── <name_of_the_app>/ │ │ ├── migrations/ │ │ ├── admin.py │ │ ├── apps.py │ │ ├── models.py │ │ ├── tests.py │ │ └── views.py │ ├── __init__.py │ └── ... ├── requirements/ │ ├── base.txt │ ├── local.txt │ └── production.txt ├── manage.py ├── README.md └── ...

三层职责划分：

• 仓库根（第一层）：存放配置、文档、manage.py等顶层文件；
• Django 项目根（第二层，即<django_project_root>/）：所有业务 app 的宿主目录；
• 配置根（第二层config/）：settings 与 URL 配置。

向项目添加第一个 app

在双层布局下，新建 app 需要多一步"归位"操作：

uv run python manage.py startapp <name-of-the-app> mv <name-of-the-app> <django_project_root>/

然后把apps.py中的name = '<name-of-the-app>'改为name = '<django_project_root>.<name-of-the-app>'，最后把新 app 追加到 config/settings/base.py 的LOCAL_APPS列表中（该列表已预留# Your stuff: custom apps go here注释位）。

环境变量与配置体系

模板的配置哲学是"环境变量驱动"。settings 的权威映射表见 docs/1-getting-started/settings.rst，此处摘录核心映射：

此外还有两个"其他环境设置"：

• DJANGO_ACCOUNT_ALLOW_REGISTRATION（默认 True）：在不关闭认证与账户管理的前提下，单独开关 django-allauth 的用户注册；
• DJANGO_ADMIN_FORCE_ALLAUTH（默认 False）：强制 admin 登录走 django-allauth 流程。

配置文件的分层实现

生成项目使用三层 settings 继承结构，模板中的原型实现见 config/settings/base.py：

• base.py：公共基线。通过environ.Env()读取环境变量；DJANGO_READ_DOT_ENV_FILE=True时会读取项目根目录.env文件（OS 环境变量优先）；数据库支持DATABASE_URL或POSTGRES_DB/USER/PASSWORD/HOST/PORT两种方式，且强制ATOMIC_REQUESTS = True；密码哈希首选Argon2；Cookie 均 HttpOnly、X_FRAME_OPTIONS = "DENY"；内置 Celery（broker/result 指向 Redis、任务 5 分钟硬超时/60 秒软超时、django_celery_beat数据库调度）、django-allauth（强制邮箱验证ACCOUNT_EMAIL_VERIFICATION = "mandatory"）、DRF（Session + Token 认证、drf-spectacular Swagger 仅对 admin 开放）与 Webpack loader 的条件配置段；文件末尾预留# Your stuff...扩展位。
• local.py：开发环境。DEBUG = True、ALLOWED_HOSTS = ["localhost", "0.0.0.0", "127.0.0.1"]、LocMemCache 缓存、console 邮件后端（除非选了 Mailpit/Mailtrap Local，此时切换为 SMTP 到本地端口 1025/3535）、django-debug-toolbar（含INTERNAL_IPS自动探测 Docker 内网 IP）、django-extensions；非 Docker 时CELERY_TASK_ALWAYS_EAGER = True，让任务在本地同步执行而非进入 broker。
• production.py / test.py：生产环境开启 SSL 跳转、HSTS、SECURE cookies 等，测试环境提供独立配置。

环境变量的设置方式

本地开发时可用两种方式（docs/2-local-development/developing-locally.rst）：

1. 在项目根目录创建.env文件并定义所需变量，然后在机器上设置DJANGO_READ_DOT_ENV_FILE=True，所有变量会被自动读取；
2. 使用direnv等本地环境管理工具按目录自动加载。

若同时启用了 Docker/Heroku，post 钩子会把.env与.envs/*追加进.gitignore；当keep_local_envs_in_vcs=y时会额外保留!.envs/.local/，便于团队成员共享一致的本地环境。

本地开发工作流

前置依赖

宿主机需要安装（docs/2-local-development/developing-locally.rst）：

• uv（Python 依赖管理，已替代 pip/venv 组合）；
• PostgreSQL（必须）；
• Redis（仅在使用 Celery 时需要）；
• Cookiecutter（生成项目时）。

初始化与启动

cd <你在生成时填写的 project_slug> uv sync git init # pre-commit 安装需要 git 仓库 uv run pre-commit install

说明：生成的项目中默认带有 pre-commit 钩子，安装后才能享受提交前自动检查。

创建数据库并注入环境变量：

createdb --username=postgres <project_slug> export POSTGRES_USER=postgres export POSTGRES_PASSWORD= export POSTGRES_DB=<createdb 时给的数据库名>

首次建库若失败，通常需要先完成 PostgreSQL 的初始配置（允许本地连接并为 postgres 用户设置密码）。

执行迁移并启动服务：

uv run python manage.py migrate

同步模式（Django 开发服务器）：

uv run python manage.py runserver 0.0.0.0:8000

异步模式（Uvicorn + ASGI）：

uv run uvicorn config.asgi:application --host 0.0.0.0 --reload --reload-include '*.html'

配置 Celery 本地任务队列

默认情况下（非 Docker 本地开发），CELERY_TASK_ALWAYS_EAGER = True，任务直接在主线程同步执行。若本机装有 Redis，可在config/settings/local.py中改为：

CELERY_TASK_ALWAYS_EAGER = False

然后分别开两个终端运行 Redis 与 worker：

redis-server uv run celery -A config.celery_app worker --loglevel=info

模板自带一个演示任务（生成项目中的<project_slug>/users/tasks.py，模板原型见 {{cookiecutter.project_slug}}/{{cookiecutter.project_slug}}/users/tasks.py），可用 Django shell 手动入队验证：

uv run python manage.py shell >> from <project_slug>.users.tasks import get_users_count >> get_users_count.delay()

此外，得益于django-celery-beat，你也可以直接在 Django admin 后台创建定时任务。

本地邮件测试

开发阶段通常不希望真实投递邮件，而是本地接收并可视化查看。模板提供三种方案：

Mailpit（需生成时mail_catcher=Mailpit）：纯 Go 单二进制、无外部依赖。下载后放入项目根目录：

chmod +x mailpit ./mailpit

然后访问http://127.0.0.1:8025/查看收到的邮件。

Mailtrap Local（需生成时mail_catcher=Mailtrap Local）：同样是 MIT 许可的单二进制 Go 程序：

chmod +x mailtrap-local ./mailtrap-local

访问http://127.0.0.1:3550/查看。

Console 后端（生成时mail_catcher=None的默认方案）：通过EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'把邮件直接打印到终端。生产环境则由 Anymail 接管的邮件服务（如 Mailgun）负责真实投递。

为什么本地需要邮件捕捉器？因为项目依赖的 django-allauth 会向新注册用户以及未完成验证的老用户发送验证邮件，本地调试注册流程时没有邮件捕捉器将寸步难行。

使用 Gulp / Webpack 前端管线

若生成时选择 Gulp 或 Webpack，模板预置了 Sass 编译与浏览器实时重载（BrowserSync）：修改 Sass/JS 源码后，任务会自动重建 CSS/JS 资源并在浏览器中热更新，无需手动刷新页面。

• 需要宿主机安装 Node.js v18；
• 项目根目录执行npm install；
• 激活虚拟环境后执行npm run dev，该命令会并行启动两个进程：静态资源构建循环 + Django 服务器；
• 访问地址应为http://localhost:3000（node 服务端口），切勿用 Django 的 8000 端口访问——否则会出现样式错乱与静态资源 404。

部署选项

模板按你的选项生成多种部署路径：

• Docker 生产栈：启用use_docker后，生产侧 docker-compose.production.yml 编排 Django（含 Celery beat/flower/worker）、PostgreSQL、nginx（媒体文件代理）、Traefik（自动 HTTPS，配合 LetsEncrypt）等容器，配置原型见 compose/production/；Docker 方式下的本地开发、数据库备份/恢复等操作详见 docs/2-local-development/developing-locally-docker.rst 与 docs/4-guides/docker-postgres-backups.rst；
• Heroku：启用use_heroku后生成 Procfile 及配套配置，部署步骤见 docs/3-deployment/deployment-on-heroku.rst；
• PythonAnywhere：见 docs/3-deployment/deployment-on-pythonanywhere.rst；
• 云存储：AWS S3 / GCP / Azure 的存储配置细节见 docs/3-deployment/cloud-storage.rst。

社区与进一步定制

• 提问请优先使用 Stack Overflow 的cookiecutter-django标签，维护者会定期巡查；
• 发现 bug 或想提新功能，请在仓库 Issues 中提交，不要给维护者发私人邮件；
• 日常交流可在项目 Discord 频道进行；
• 模板在 Python/HTML 中预留了大量标注 "your stuff" 的位置，这是第三方库与你的项目集成的约定入口（README.md "Your Stuff" 一节）；
• 需要稳定版本时，可选用仓库 Releases 中发布的 tag；
• 如果默认方案不合口味，官方鼓励 fork 出属于你自己的模板，并在跑通后提交 PR 收录到 "Similar Cookiecutter Templates" 列表中；也欢迎提交小而原子化的 PR 回馈上游（README.md "Not Exactly What You Want?" 一节）。

小结

从安装 Cookiecutter、交互式回答 20 余个选项，到pre/post钩子自动注入密钥、裁剪无关文件、装填依赖，再到本地开发、Celery 队列、邮件测试、前端管线与多平台部署，Cookiecutter Django 把"从空目录到可上线的 Django 项目"压缩到了几分钟内，同时保证了安全基线、测试覆盖与 12-Factor 配置规范不缩水。阅读 docs/ 目录下的全套文档（生成选项、settings 映射、本地开发、Docker、部署、故障排查等），可以进一步释放这个模板的全部能力。

【免费下载链接】cookiecutter-djangoCookiecutter Django is a framework for jumpstarting production-ready Django projects quickly.项目地址: https://gitcode.com/GitHub_Trending/co/cookiecutter-django