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 一节只使用持续维护的第三方库避免项目从第一天就背上失维护依赖的负担数据库一律使用 PostgreSQL14–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 或 nginxDocker 支持开发与生产两套 docker-compose生产侧使用 Traefik 并内置 LetsEncrypt 证书支持提供Procfile可直接部署到 Heroku提供PythonAnywhere部署指引测试可用unittest 或 pytestPostgreSQL 版本可选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 安装要求cookiecutter1.7.0uv tool install cookiecutter1.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-greenfeldexample.com]: pydannygmail.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 gitgithub.com:pydanny/redditclone.git git push -u origin main提交前请务必仔细阅读生成项目根目录的 README——它针对你的具体选项生成了对应的本地开发指引。生成选项全解析模板的全部选项定义在仓库根目录 cookiecutter.json 中其权威说明见 docs/1-getting-started/project-generation-options.rst。下表按提问顺序逐项说明选项含义与取值关键说明project_name项目人类可读名称允许大写与空格会出现在 README、页面标题等处project_slug不含横线和空格的 slug默认由project_name自动转换小写、空格/横线/点替换为下划线用于仓库名及所有需要 Python 可导入标识符的场景必须是合法 Python 标识符description项目描述会被写进生成的README.rst等位置author_name作者名写入LICENSE等文件email作者邮箱默认由author_name与domain_name拼装username_typeusername或email选username时登录字段为用户名仍含邮箱字段选email时登录字段为邮箱且不生成 username 字段domain_name上线域名之后可随时安全修改version项目初始版本号默认0.1.0open_source_licenseMIT / BSD / GPLv3 / Apache 2.0 / Not open source决定生成的 LICENSE、COPYING 等文件timezone时区写入TIME_ZONE设置windowsy/n是否按 Windows 本地开发环境配置editorNone / PyCharm / VS Code决定是否生成.idea/及 IDE 运行配置use_dockery/n是否生成 Docker、Docker Compose 与 devcontainer 相关文件postgresql_version18 / 17 / 16 / 15 / 14决定数据库镜像版本cloud_providerAWS / GCP / Azure / None决定静态与媒体文件存储后端mail_serviceMailgun / Amazon SES / Mailjet / Mandrill / Postmark / Sendgrid / Brevo / SparkPost / Other SMTP通过 django-anymail 配置邮件发送rest_apiNone / DRF / Django Ninja决定 API 框架及其配套文件use_asyncy/n是否启用 WebsocketUvicorn Gunicornfrontend_pipelineNone / Django Compressor / Gulp / WebpackGulp 与 Webpack 都支持 Bootstrap 实时变量重编译use_celeryy/n是否配置 Celerymail_catcherNone / Mailpit / Mailtrap Local本地开发邮件接收工具use_sentryy/n是否接入 Sentry 错误日志use_whitenoisey/n是否用 WhiteNoise 托管静态文件use_herokuy/n是否生成 Heroku 部署配置ci_toolNone / Travis / Gitlab / Github / Drone生成对应 CI 流水线文件keep_local_envs_in_vcsy/n是否将.envs/.local/纳入版本控制利于团队本地环境复现debugy/n仅对模板开发者有意义一般不选 y选项之间的联动与约束几个选项存在交叉影响需要特别留意静态文件与媒体文件的托管组合若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.rstrepository_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 设置开发默认值生产默认值DJANGO_READ_DOT_ENV_FILEREAD_DOT_ENV_FILEFalseFalseDATABASE_URLDATABASES有 Docker 时自动无 Docker 时postgres://project_slug缺省报错DJANGO_ADMIN_URL—admin/缺省报错DJANGO_DEBUGDEBUGTrueFalseDJANGO_SECRET_KEYSECRET_KEY自动生成缺省报错DJANGO_SECURE_SSL_REDIRECTSECURE_SSL_REDIRECT—TrueDJANGO_ALLOWED_HOSTSALLOWED_HOSTS[*][your_domain_name]DJANGO_DEFAULT_FROM_EMAILDEFAULT_FROM_EMAIL—项目名 noreply域名SENTRY_DSNSENTRY_DSN—缺省报错MAILGUN_API_KEYMAILGUN_API_KEY—缺省报错此外还有两个其他环境设置DJANGO_ACCOUNT_ALLOW_REGISTRATION默认 True在不关闭认证与账户管理的前提下单独开关 django-allauth 的用户注册DJANGO_ADMIN_FORCE_ALLAUTH默认 False强制 admin 登录走 django-allauth 流程。配置文件的分层实现生成项目使用三层 settings 继承结构模板中的原型实现见 config/settings/base.pybase.py公共基线。通过environ.Env()读取环境变量DJANGO_READ_DOT_ENV_FILETrue时会读取项目根目录.env文件OS 环境变量优先数据库支持DATABASE_URL或POSTGRES_DB/USER/PASSWORD/HOST/PORT两种方式且强制ATOMIC_REQUESTS True密码哈希首选Argon2Cookie 均 HttpOnly、X_FRAME_OPTIONS DENY内置 Celerybroker/result 指向 Redis、任务 5 分钟硬超时/60 秒软超时、django_celery_beat数据库调度、django-allauth强制邮箱验证ACCOUNT_EMAIL_VERIFICATION mandatory、DRFSession 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在项目根目录创建.env文件并定义所需变量然后在机器上设置DJANGO_READ_DOT_ENV_FILETrue所有变量会被自动读取使用direnv等本地环境管理工具按目录自动加载。若同时启用了 Docker/Herokupost 钩子会把.env与.envs/*追加进.gitignore当keep_local_envs_in_vcsy时会额外保留!.envs/.local/便于团队成员共享一致的本地环境。本地开发工作流前置依赖宿主机需要安装docs/2-local-development/developing-locally.rstuvPython 依赖管理已替代 pip/venv 组合PostgreSQL必须Redis仅在使用 Celery 时需要Cookiecutter生成项目时。初始化与启动cd 你在生成时填写的 project_slug uv sync git init # pre-commit 安装需要 git 仓库 uv run pre-commit install说明生成的项目中默认带有 pre-commit 钩子安装后才能享受提交前自动检查。创建数据库并注入环境变量createdb --usernamepostgres project_slug export POSTGRES_USERpostgres export POSTGRES_PASSWORD export POSTGRES_DBcreatedb 时给的数据库名首次建库若失败通常需要先完成 PostgreSQL 的初始配置允许本地连接并为 postgres 用户设置密码。执行迁移并启动服务uv run python manage.py migrate同步模式Django 开发服务器uv run python manage.py runserver 0.0.0.0:8000异步模式Uvicorn ASGIuv 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 与 workerredis-server uv run celery -A config.celery_app worker --loglevelinfo模板自带一个演示任务生成项目中的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_catcherMailpit纯 Go 单二进制、无外部依赖。下载后放入项目根目录chmod x mailpit ./mailpit然后访问http://127.0.0.1:8025/查看收到的邮件。Mailtrap Local需生成时mail_catcherMailtrap Local同样是 MIT 许可的单二进制 Go 程序chmod x mailtrap-local ./mailtrap-local访问http://127.0.0.1:3550/查看。Console 后端生成时mail_catcherNone的默认方案通过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:3000node 服务端口切勿用 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.rstHeroku启用use_heroku后生成 Procfile 及配套配置部署步骤见 docs/3-deployment/deployment-on-heroku.rstPythonAnywhere见 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考