Cookiecutter Django 本地开发环境搭建完全指南从裸机同步开发到异步任务与前端流水线【免费下载链接】cookiecutter-djangoCookiecutter Django is a framework for jumpstarting production-ready Django projects quickly.项目地址: https://gitcode.com/GitHub_Trending/co/cookiecutter-django本篇指南以 Cookiecutter Django 项目的 docs/2-local-development/developing-locally.rst 文档为核心系统讲解在不使用 Docker的前提下如何在本地裸机bare-metal环境搭建并运行一个由 Cookiecutter Django 模板生成的 Django 项目。内容包括开发环境前置依赖、项目初始化与uv依赖管理、PostgreSQL 数据库创建与迁移、同步/异步两种开发服务器启动方式、双层项目结构下创建 Django App 的规范流程、本地邮件捕获方案Mailpit / Mailtrap Local / Console、Celery 异步任务调试以及 Webpack/Gulp 前端流水线的使用。读完本文你将掌握一套完整、可复现的本地开发工作流并能理解每个步骤背后对应的源码实现。前置依赖裸机本地开发需要准备什么与 Docker 方案不同裸机bare-metal本地开发要求所有服务直接运行在你的宿主机上。根据原文档在开始之前需要在宿主机上安装以下工具依赖用途获取方式uvPython 包管理与虚拟环境工具本项目依赖管理与运行命令的统一入口官方安装文档见原文档链接PostgreSQL项目默认数据库官方下载页Redis仅当使用 Celery 异步任务时需要作为任务队列 Broker官方下载页Cookiecutter用于从模板生成新项目官方仓库从模板生成项目是这一切的前提。生成命令定义在 docs/2-local-development/generate-project-block.rst 中cookiecutter gh:cookiecutter/cookiecutter-django生成过程中会交互式询问一系列配置选项如project_slug、use_docker、use_celery、frontend_pipeline、mail_catcher等完整选项说明可参考 docs/1-getting-started/project-generation-options.rst。在 setup 阶段输入的project_slug会作为后续所有命令中项目目录、数据库名、容器名等标识的基础。注意本指南对应的文档面向不使用 Docker的裸机场景。若你选择在初始化时设置use_docker y请参阅 docs/2-local-development/developing-locally-docker.rst两者的环境变量与启动方式完全不同。第一步同步依赖并安装 pre-commit 钩子项目生成完成后进入项目目录并执行依赖安装cd what you have entered as the project_slug at setup stage uv sync git init # A git repo is required for pre-commit to install uv run pre-commit install三个命令各有明确的职责uv sync基于项目根目录的 pyproject.toml 和uv.lock锁文件创建虚拟环境并安装全部开发依赖。由于模板默认生成uv.lock锁文件uv sync会保证依赖版本的可复现性。git init正如原文档注释强调的pre-commit的安装必须在一个 Git 仓库中进行。pre-commit 钩子依赖 Git 来检测暂存文件并执行 lint / 格式化检查。uv run pre-commit install在.git/hooks/中注册 pre-commit 钩子。原文档特别指出pre-commit钩子在生成的项目中是默认存在的pyproject.toml中会声明 pre-commit 相关配置每次git commit时它会自动运行项目配置的 linter如 ruff、black 风格检查等。若跳过这一步后续提交时会出现大量 CI 和 Linter 错误。第二步创建 PostgreSQL 数据库并配置环境变量创建数据库使用 PostgreSQL 自带的createdb工具创建数据库数据库名与 setup 阶段输入的project_slug保持一致createdb --usernamepostgres project_slug原文档特别提醒如果这是你机器上第一次创建数据库可能需要进行PostgreSQL 初始配置——即修改pg_hba.conf等配置文件允许本地连接并为postgres用户设置密码。这是常见的初装坑createdb连接失败时优先检查本机 PostgreSQL 的认证方式trust/md5/scram-sha-256与postgres用户的密码是否已设置。导出环境变量export POSTGRES_USERpostgres export POSTGRES_PASSWORD export POSTGRES_DBDB name given to createdb这些环境变量会被 config/settings/base.py 中的数据库配置读取。从源码可以看到if os.getenv(DATABASE_URL, defaultNone): DATABASES {default: env.db(DATABASE_URL)} # ... HOST: env.str(POSTGRES_HOST, defaultpostgres),也就是说裸机模式下如果不显式设置DATABASE_URL则默认通过POSTGRES_HOST非 Docker 场景默认值实际为localhost、POSTGRES_PORT、POSTGRES_DB、POSTGRES_USER、POSTGRES_PASSWORD等变量拼装连接信息。裸机开发时必须把POSTGRES_HOST指向localhost这与 Docker 场景下指向postgres服务名截然不同。完整的可用环境变量清单DJANGO_DEBUG、DJANGO_SECRET_KEY、DJANGO_ALLOWED_HOSTS等可查阅 docs/1-getting-started/settings.rst其中整理了各变量在开发环境与生产环境的默认值对照表。环境变量的两种管理方式原文档提供了两种推荐实践避免每次打开终端都手动export.env文件 DJANGO_READ_DOT_ENV_FILETrue在项目根目录创建.env文件定义全部所需变量然后在宿主机设置DJANGO_READ_DOT_ENV_FILETrue。base.py中对应READ_DOT_ENV_FILE设置开启后项目会读取根目录.env文件并自动加载其中的变量。本地环境管理器如direnv进入项目目录时自动加载环境变量。第三步迁移数据库并启动开发服务器应用迁移uv run python manage.py migratemanage.py位于项目根目录{{cookiecutter.project_slug}}/manage.py模板默认将DJANGO_SETTINGS_MODULE指向config.settings.local。迁移会创建 Django 内置表以及users应用、contrib/sites应用的初始表结构。启动服务器同步 vs 异步根据你的项目是否启用了异步支持选择对应的启动方式。同步默认——使用 Django 自带开发服务器uv run python manage.py runserver 0.0.0.0:8000异步——使用 Uvicorn 运行 ASGI 应用模板默认提供config.asgi:application见 config/asgi.pyuv run uvicorn config.asgi:application --host 0.0.0.0 --reload --reload-include *.html--reload-include *.html保证了修改模板文件时也能触发热重载。如果项目选择了 Webpack 或 Gulp 作为前端流水线则不要用上述命令直接访问 8000 端口应改走 Webpack/Gulp 小节 的流程。创建你的第一个 Django App双层项目结构规范原文档明确指出该项目采用Two Scoops of Django一书推荐的双层布局two-tier layout顶层仓库根Top Level Repository Root存放配置文件、文档、manage.py、requirements/、README.md等第二层 Django 项目根Second Level Django Project Root所有 Django App 的存放位置第二层配置根Second Level Configuration Root即config/存放 settings 与 URL 配置。对应仓库中{{cookiecutter.project_slug}}/目录下的实际结构其布局如下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 └── ...说明模板当前实际使用pyproject.tomluv.lock作为依赖管理方案requirements/*.txt是模板为兼容传统工作流保留的生成物两者以pyproject.toml为主。按此结构新增一个 App 的完整步骤# 1. 生成 App uv run python manage.py startapp name-of-the-app # 2. 移动到 Django 项目根保持双层结构 mv name-of-the-app django_project_root/# 3. 编辑 App 的 apps.py修改 name 为带项目根的完整路径 name django_project_root.name-of-the-app# 4. 在 config/settings/base.py 的 LOCAL_APPS 列表中添加该 App LOCAL_APPS [ # 你的新 App 名称含项目根前缀 django_project_root.name-of-the-app, ]LOCAL_APPS定义在 config/settings/base.py 中与DJANGO_APPS、THIRD_PARTY_APPS共同构成INSTALLED_APPS。注册后App 便成为项目正式组成部分可被迁移、Admin 和测试框架识别。配置邮件后端本地邮件捕获与测试本地开发时我们通常不想真正发送邮件而是希望捕获并查看项目发送的邮件内容。典型场景是django-allauth在用户注册或重新验证时会发送验证邮件。原文档提供了三种方案其中前两种依赖于项目初始化时的mail_catcher选项。MailpitGo 编写的零依赖邮件捕获工具前提项目初始化时mail_catcher必须设置为Mailpit。Mailpit 由 Go 编写无外部依赖。安装步骤# 1. 下载对应系统的最新 release 二进制 # 2. 复制到项目根目录 # 3. 赋予可执行权限 chmod x mailpit # 4. 另开一个终端窗口启动 ./mailpit # 5. 浏览器访问 Web 界面 http://127.0.0.1:8025/在裸机模式下local.py会为 Mailpit 配置如下见 config/settings/local.pyEMAIL_HOST localhost EMAIL_PORT 1025即 Django 会把邮件发往本机 1025 端口的 Mailpit SMTP 服务Mailpit 在 8025 端口提供 Web 界面查看邮件。Mailtrap LocalMIT 许可的单文件 Go 二进制前提项目初始化时mail_catcher必须设置为Mailtrap Local。# 1. 下载对应系统的最新 release 二进制 # 2. 复制到项目根目录 # 3. 赋予可执行权限 chmod x mailtrap-local # 4. 另开一个终端窗口启动 ./mailtrap-local # 5. 浏览器访问 Web 界面 http://127.0.0.1:3550/对应local.py的配置见 config/settings/local.pyEMAIL_HOST localhost EMAIL_PORT 3535注意 Mailtrap Local 的 SMTP 端口3535与 Web 界面端口3550不同而 Mailpit 两者都是 1025/8025。Console 后端默认兜底方案前提项目初始化时mail_catcher设置为None默认。此时local.py使用 Django 内置的 console 邮件后端见 config/settings/local.pyEMAIL_BACKEND env( DJANGO_EMAIL_BACKEND, defaultdjango.core.mail.backends.console.EmailBackend, )邮件不会真正发送而是直接打印到运行开发服务器的终端标准输出中。生产环境的邮件则由 Mailgun 等服务接管相关配置见 docs/includes/mailgun.rst。Celery本地异步任务的两种运行模式如果项目初始化时启用了use_celery默认情况下非 Docker 裸机开发local.py中会有如下设置见 config/settings/local.pyCELERY_TASK_ALWAYS_EAGER True CELERY_TASK_EAGER_PROPAGATES TrueCELERY_TASK_ALWAYS_EAGER True意味着任务不会进入 Broker 队列而是在主线程同步执行这样本地开发无需启动 Redis 与 worker 即可运行整个应用。这是裸机模式省心的默认行为。切换为真实异步模式如果你在本机安装了 Redis希望在本地体验真实的异步任务队列在config/settings/local.py中修改CELERY_TASK_ALWAYS_EAGER False然后分两个终端分别启动 Redis 与 Celery worker# 终端 1启动 Redis redis-server # 终端 2启动 Celery worker uv run celery -A config.celery_app worker --loglevelinfo这里的-A config.celery_app指向 config/celery_app.py。从源码可以看到Celery 实例通过app.config_from_object(django.conf:settings, namespaceCELERY)从 Django settings 中读取所有CELERY_前缀配置Broker 与结果后端在 config/settings/base.py 中定义REDIS_URL env(REDIS_URL, defaultredis://localhost:6379/0) CELERY_BROKER_URL REDIS_URL CELERY_RESULT_BACKEND REDIS_URL裸机场景REDIS_URL默认指向localhost:6379。Celery worker 应在应用运行期间保持后台运行以便及时消费队列中的任务。用自带任务做冒烟测试模板自带一个用于测试的简单任务位于project_slug/users/tasks.py对应仓库 users/tasks.pyfrom celery import shared_task from .models import User shared_task() def get_users_count(): A pointless Celery task to demonstrate usage. return User.objects.count()在 Django shell 中调用它来验证异步链路uv run python manage.py shell from project_slug.users.tasks import get_users_count get_users_count.delay()任务会返回当前用户总数。此外得益于django-celerybeat包你还可以通过Django Admin 后台可视化地创建、调度周期任务无需手写 cron 表达式。使用 Webpack 或 Gulp 前端流水线如果项目初始化时frontend_pipeline选择了 Webpack 或 Gulp模板已预置Sass 编译与live reloading浏览器即时热刷新能力当你修改 Sass/JS 源文件时任务运行器会自动重新构建对应的 CSS/JS 资源并在浏览器中无刷新地热加载。启动步骤# 1. 确保本机安装 Node.js模板 package.json 声明 engines.node 为 26.5请以生成项目为准 # 2. 安装 JS 依赖 npm install # 3. 激活虚拟环境后启动开发模式 npm run devnpm run dev会并行启动两个进程一边是静态资源构建循环另一边是 Django 开发服务器。dev脚本由项目根目录的 package.json 定义其scripts.dev在模板渲染时会被填充为具体的并行命令通常基于concurrently组合 webpack-dev-server / gulp 与 Django 服务器。访问地址必须走 Node 端口⚠️关键警告访问应用时请使用node 服务地址 http://localhost:3000默认绝对不要直接访问 Django 的 8000 端口否则会出现样式错乱以及静态资源 404。原因在于3000 端口由 node 服务代理到 Django 应用并在响应中注入 live reload 脚本同时正确地为 Sass 编译产物提供服务而 Django 自身端口8000并不了解这些前端资源的存在。默认端口映射可在 docker-compose.local.yml 中看到node服务暴露3000:3000端口裸机模式下npm run dev同样以 3000 作为入口。排错要点与日常开发提示数据库连接失败优先检查POSTGRES_HOST是否为localhost裸机而非postgresDocker并确认本机 PostgreSQL 已完成初始配置密码、pg_hba.conf认证方式。pre-commit 报错确认已在项目目录执行过git init与uv run pre-commit install否则提交会触发大量 Linter 失败。邮件看不到确认你选择的mail_catcher与初始化选项一致Mailpit / Mailtrap Local / None并核对EMAIL_HOST与EMAIL_PORTConsole 模式下邮件直接打印在运行 Django 的终端。异步任务不进入队列检查local.py中CELERY_TASK_ALWAYS_EAGER是否为False以及 Redis 是否运行在localhost:6379REDIS_URL默认值。前端资源 404 / 样式丢失确认通过http://localhost:3000访问而非 8000 端口。完整环境变量表涉及DJANGO_*系列变量的开发/生产默认值差异始终以 docs/1-getting-started/settings.rst 为准。总结至此你已经完成了从零开始搭建 Cookiecutter Django 裸机本地开发环境的全部关键步骤安装依赖、创建数据库、配置环境变量、执行迁移、启动同步/异步服务器、按双层结构创建 App、搭建本地邮件捕获环境、切换 Celery 任务模式并验证异步链路以及启用 Webpack/Gulp 前端流水线。这套工作流与 Docker 方案 互为补充——裸机模式胜在轻量与直接Docker 模式胜在环境一致性可根据团队与机器情况灵活选择。继续阅读 docs/2-local-development/developing-locally-docker.rst 或 docs/3-deployment/ 系列可进一步了解容器化开发与生产部署实践充分释放 Cookiecutter Django 的完整潜力。【免费下载链接】cookiecutter-djangoCookiecutter Django is a framework for jumpstarting production-ready Django projects quickly.项目地址: https://gitcode.com/GitHub_Trending/co/cookiecutter-django创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考