深入理解 Wagtail 项目模板wagtail start生成的默认项目骨架、配置拆分、测试与 Docker 部署【免费下载链接】wagtailA Django content management system focused on flexibility and user experience项目地址: https://gitcode.com/GitHub_Trending/wa/wagtailwagtail start是 Wagtail 的官方项目脚手架命令执行一次即可得到一个结构完整、可直接运行的 Django Wagtail 站点。本文以 Wagtail 官方文档对“项目模板”的说明为主线逐层拆解默认模板中home/search两个应用、settings四文件拆分、基础模板与测试、Dockerfile的真实内容并结合仓库内模板源码位于 wagtail/project_template说明每个文件的实际行为最后介绍如何用--template参数替换为自定义模板以及如何规避模板文件中的模板语法解析问题。默认项目的目录结构默认情况下运行wagtail start mysite或任何项目名会创建一个包含以下结构的 Django 项目mysite/ home/ migrations/ __init__.py 0001_initial.py 0002_create_homepage.py templates/ home/ home_page.html __init__.py models.py tests.py search/ templates/ search/ search.html __init__.py views.py mysite/ settings/ __init__.py base.py dev.py production.py static/ css/ mysite.css js/ mysite.js templates/ 404.html 500.html base.html __init__.py urls.py wsgi.py Dockerfile manage.py requirements.txt这一结构的模板源头就是仓库中的 wagtail/project_template/ 目录其中project_name/子目录在生成时会被重命名为你的项目名如mysite/模板文件中的{{ project_name }}、{{ secret_key }}等占位符会被替换为真实值例如 wagtail/project_template/manage.py-tpl 中的os.environ.setdefault(DJANGO_SETTINGS_MODULE, {{ project_name }}.settings.dev)生成的manage.py会默认使用dev设置模块。“home”应用HomePage 模型与首页数据迁移模板中home应用的作用是帮助你更快启动项目它提供一个HomePage模型并通过迁移在首次迁移数据库时自动创建一个首页。HomePage 模型定义home/models.py 极其精简——HomePage直接继承 Wagtail 的Page抽象基类不添加任何字段from django.db import models from wagtail.models import Page class HomePage(Page): pass这体现了 Wagtail 页面建模的基本方式先有一个可用的页面类型之后按需为其添加字段、面板和迁移。迁移如何自动创建首页home/migrations/下有两个迁移文件0001_initial.py标准的CreateModel操作为HomePage建表其主键page_ptr是以OneToOneField指向wagtailcore.Page的父链multi-table inheritance0002_create_homepage.py一个数据迁移RunPython负责把“能跑起来的最小站点”直接写进数据库。从 0002_create_homepage.py 的实现可以看到具体步骤删除 Wagtail 核心迁移wagtailcore.0002_initial_data预先创建的那个默认Page类型的home页面按content_typeslughomedepth2定位为HomePage创建ContentType创建HomePage实例显式写入path00010001、depth2、url_path/home/创建Site对象hostnamelocalhost并把新首页设为该站点的根节点is_default_siteTrue。此外该迁移通过run_before [(wagtailcore, 0053_locale_model)]声明执行顺序确保它在核心后续迁移之前完成数据替换。因此你执行python manage.py migrate之后数据库中就已经有一个指向/的默认站点和一条HomePage记录无需再手工建页。首页模板与欢迎页home/templates/home/home_page.html 继承base.html并设置了body_class区块为template-homepage。从当前仓库的模板内容看它还通过{% include home/welcome_page.html %}引入了一个“欢迎页”配套样式为 home/static/css/welcome_page.css并在注释中提示如果你已经熟悉 Wagtail、想移除欢迎屏幕删除对应的 include 与样式引入行即可。search 应用内置的站点搜索目录树中的search应用提供了一个开箱即用的页面搜索视图。search/views.py 的核心逻辑从request.GET中取query与page参数当存在查询词时调用Page.objects.live().search(search_query)搜索所有已发布页面——这就是 Wagtail 数据库搜索后端的直接用法WAGTAILSEARCH_BACKENDS在默认配置中使用wagtail.search.backends.database用 Django 的Paginator按每页 10 条分页并对PageNotAnInteger/EmptyPage做了兜底处理用TemplateResponse渲染search/search.html。源码注释中还给出了接入“推广搜索结果”Promoted search results模块的方式将wagtail.contrib.search_promotions加入INSTALLED_APPS并在视图内调用Query.get(search_query)/query.add_hit()记录查询命中。项目模板中的 Django 设置四文件拆分项目设置文件被拆分为base.py、dev.py、production.py与local.py四个文件这一拆分是模板最重要的工程约定之一。文件用途典型内容base.py开发与生产共用的全局设置绝大多数配置应集中在这里INSTALLED_APPS、中间件、数据库、静态/媒体文件、Wagtail 相关设置dev.py仅供开发者使用的设置DEBUG True、控制台邮件后端production.py仅供生产服务器运行的设置DEBUG False、ManifestStaticFilesStoragelocal.py针对特定机器的本地设置绝不应被版本控制系统跟踪密钥、数据库口令等机密官方文档在此还给出两条生产环境建议其一生产服务器上建议只把机密API 密钥、口令等存放在local.py中——将来排查服务器异常行为时能省去大量“密钥从哪里来”的困惑其二如果多台生产服务器需要不同配置建议为每台服务器各维护一份不同的production.py。base.py 中的关键配置从 project_name/settings/base.py 源码看默认设置包含了以下内容应用注册INSTALLED_APPS除项目自身的home、search外默认启用了wagtail.contrib.forms、wagtail.contrib.redirects、wagtail.embeds、wagtail.sites、wagtail.users、wagtail.snippets、wagtail.documents、wagtail.images、wagtail.search、wagtail.admin、wagtail以及依赖库modelcluster、taggit、django_filters中间件在 Django 默认中间件链末尾追加了wagtail.contrib.redirects.middleware.RedirectMiddleware用于在页面 404 时按重定向表进行跳转数据库默认为项目根目录下的 SQLiteBASE_DIR / db.sqlite3静态文件STATICFILES_DIRS指向项目static/目录STATIC_ROOT指向根目录static/表单字段上限DATA_UPLOAD_MAX_NUMBER_FIELDS 10_000源码注释解释了原因——Wagtail 页面编辑器中特别复杂的页面模型字段数可能超过 Django 默认的 1000 上限Wagtail 核心设置base.pyWAGTAIL_SITE_NAME站点显示名默认取项目名WAGTAILSEARCH_BACKENDS默认使用wagtail.search.backends.database数据库搜索后端WAGTAILADMIN_BASE_URL后台生成完整 URL如通知邮件使用的基础地址注释特别提醒不要包含/admin或结尾斜杠模板中默认值为http://example.com实际部署时应修改WAGTAILDOCS_EXTENSIONS文档库允许上传的文件扩展名白名单csv、docx、pdf、xlsx等注释指出省略该设置虽可允许所有文件但在允许不受信任用户上传时存在安全风险WAGTAILDOCS_MAX_UPLOAD_SIZE文档上传大小上限默认 10MB。dev.py 与 production.pydev.py 在from .base import *之后设置DEBUG True、生成的SECRET_KEY、ALLOWED_HOSTS [*]以及控制台邮件后端EmailBackend指向 console邮件直接打印到终端并在文件末尾尝试from .local import *——导入失败则静默跳过这正是local.py可选存在的实现方式。production.py 则设置DEBUG False并把静态文件后端切换为ManifestStaticFilesStorage——源码注释解释了原因防止 Wagtail 升级等场景下浏览器缓存到过期的 JavaScript/CSS 资源。它同样以try: from .local import *结尾。settings/init.py 是空文件仅用于把settings/标记为 Python 包项目实际用哪个设置模块由manage.py/wsgi.py中的DJANGO_SETTINGS_MODULE决定模板默认指向{{ project_name }}.settings.dev见 wsgi.py。默认模板与静态文件模板目录mysite/templates/包含base.html、404.html和500.html。这些文件在 Wagtail 站点中几乎必然需要因此被直接放进了项目模板。静态目录则包含空的mysite.css与mysite.js。project_name/templates/base.html 是典型的 Wagtail 站点基模板值得注意的几个细节加载wagtailcore_tags与wagtailuserbar模板标签库并在body中输出{% wagtailuserbar %}——它负责在有权限的用户访问前台页面时显示 Wagtail 用户栏编辑入口title优先使用page.seo_title否则回退到page.title并通过wagtail_site标签追加站点名后缀当page.search_description存在时输出meta namedescription当request.in_preview_panel为真即从后台实时预览面板打开时输出base target_blank强制预览页内的链接在新标签页打开预留extra_css、content、extra_js、body_class等区块供子模板覆盖并引用全局样式表css/{{ project_name }}.css与脚本js/{{ project_name }}.js。编写与运行测试使用wagtail start创建项目时home/tests.py中会包含一组基础测试。按照官方文档这些测试验证以下四点根PageID1被自动创建可以作为根页面的子节点创建HomePage创建出的HomePage可以被渲染renderable该HomePage使用home/home_page.html模板。对照仓库中的 home/tests.py 可以看到具体实现两个测试类都继承wagtail.test.utils.WagtailPageTestCase。HomeSetUpTests.test_root_create断言Page.objects.get(pk1)非空HomeSetUpTests.test_homepage_create用root_page.add_child(instancehomepage)创建首页并断言其存在。HomeTests.setUp则创建了一个hostnametestsite的默认站点和首页实例随后test_homepage_is_renderable调用assertPageIsRenderabletest_homepage_template_used通过self.client.get(self.homepage.url)请求页面并用assertTemplateUsed断言使用了home/home_page.html模板。运行测试的方式是进入项目目录执行python manage.py test关于 Django 测试的更多细节可参考 Django 官方文档的测试章节Wagtail 特有的测试工具如WagtailPageTestCase、WagtailTestUtils则在 Wagtail 文档的“Testing your Wagtail site”docs/advanced_topics/testing.md中有专门介绍。Dockerfile容器化构建与运行模板根目录包含一个Dockerfile用于把站点构建并部署为 Docker 容器。按官方文档构建与运行命令为docker build -t mysite . docker run -p 8000:8000 mysite从仓库中的 Dockerfile 源码看它采用了多阶段构建builder 阶段基于python:3.14-slim-bookworm安装编译 Python 包所需的系统依赖build-essential、libpq-dev、libmariadb-dev、libjpeg62-turbo-dev、zlib1g-dev、libwebp-dev创建/opt/venv虚拟环境pip install -r requirements.txt并额外安装gunicorn25.1.0Dockerfileruntime 阶段同样基于python:3.14-slim-bookworm只安装运行期库libpq5、libmariadb3、libjpeg62-turbo、libwebp7创建非 root 用户wagtailEXPOSE 8000设置PYTHONUNBUFFERED1与PORT8000从 builder 阶段拷贝虚拟环境构建期操作把工作目录设为/app把源码拷入执行python manage.py collectstatic --noinput --clear收集静态文件Dockerfile启动命令CMD set -xe; python manage.py migrate --noinput; gunicorn {{ project_name }}.wsgi:applicationDockerfile——先迁移数据库再用 Gunicorn 启动应用。源码中附带 WARNING 注释启动时同时迁移数据库并非最佳实践生产上应手动迁移或利用托管平台的 release 阶段机制这里这么做只是为了能用一条docker run把 Wagtail 实例跑起来。配套的 requirements.txt 非常简短锁定Django6.1,6.2与当前开发版 Wagtailwagtail8.1a0。注意这份文件反映的是当前仓库开发主干的状态实际使用wagtail start时生成的版本约束取决于你所安装的 Wagtail 版本。使用自定义模板--template若要使用自定义项目模板在运行wagtail start时通过--template选项指定即可。该选项接受一个目录、文件路径或 URL行为与django-admin startproject --template类似。例如一个以 GitHub 仓库形式维护的自定义模板可以用如下 URL 使用wagtail start myproject --templatehttps://github.com/githubuser/wagtail-awesome-template/archive/main.zip社区维护的自定义模板合集如 awesome-wagtail 中的“Templates (start command)”清单收录了多个可直接用于项目的模板仓库可以作为选型参考。编写自定义模板时的注意事项社区中存在一些现成的自定义模板仓库例如 thibaudcolas/wagtail-tutorial-template、torchbox/wagtail-news-template 等可作为参考。编写自定义模板时最常见的坑是--template选项会像 Django 项目模板一样解析模板文件中的模板语法。如果你的模板文件本身包含 Django 模板标签{% extends %}、{% for %}等生成项目时会抛出解析错误。解决办法是在自定义模板的每个模板文件外层包裹{% verbatim %} ... {% endverbatim %}标签例如{% verbatim %} {% extends base.html %} {% load wagtailcore_tags %} {% block body_class %}template-blogindexpage{% endblock %} {% block content %} h1{{ page.title }}/h1 div classintro{{ page.intro|richtext }}/div {% for post in page.get_children %} h2a href{% pageurl post %}{{ post.title }}/a/h2 {{ post.specific.intro }} {{ post.specific.body }} {% endfor %} {% endblock %} {% endverbatim %}这样{% verbatim %}内的所有标签在模板渲染即项目生成阶段会原样保留到生成的项目中从而避免被当作模板指令执行或引发语法错误。仓库自带的默认模板正是采用类似机制的模板文件通过{% templatetag openblock %}等写法转义标签字符并在其中保留{{ project_name }}这类需要真正被替换的变量可参见 base.html 源码。小结适用前提与版本说明本文所有目录结构、设置拆分与测试内容对应仓库中的 wagtail/project_template/是wagtail start的默认模板来源生成的项目默认使用 SQLite、数据库搜索后端与控制台邮件后端面向快速开发上生产前至少需要修改WAGTAILADMIN_BASE_URL、数据库配置并按 production.py 的思路使用production设置模块当前仓库主干的模板使用 Python 3.14 基础镜像、Django 6.1 约束属于开发版本快照在已发布的稳定版 Wagtail 上执行wagtail start时生成的requirements.txt与 Dockerfile 中的基础镜像版本以你所用版本为准。【免费下载链接】wagtailA Django content management system focused on flexibility and user experience项目地址: https://gitcode.com/GitHub_Trending/wa/wagtail创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 深入理解 Wagtail 项目模板：`wagtail start` 生成的默认项目骨架、配置拆分、测试与 Docker 部署
深入理解 Wagtail 项目模板wagtail start生成的默认项目骨架、配置拆分、测试与 Docker 部署【免费下载链接】wagtailA Django content management system focused on flexibility and user experience项目地址: https://gitcode.com/GitHub_Trending/wa/wagtailwagtail start是 Wagtail 的官方项目脚手架命令执行一次即可得到一个结构完整、可直接运行的 Django Wagtail 站点。本文以 Wagtail 官方文档对“项目模板”的说明为主线逐层拆解默认模板中home/search两个应用、settings四文件拆分、基础模板与测试、Dockerfile的真实内容并结合仓库内模板源码位于 wagtail/project_template说明每个文件的实际行为最后介绍如何用--template参数替换为自定义模板以及如何规避模板文件中的模板语法解析问题。默认项目的目录结构默认情况下运行wagtail start mysite或任何项目名会创建一个包含以下结构的 Django 项目mysite/ home/ migrations/ __init__.py 0001_initial.py 0002_create_homepage.py templates/ home/ home_page.html __init__.py models.py tests.py search/ templates/ search/ search.html __init__.py views.py mysite/ settings/ __init__.py base.py dev.py production.py static/ css/ mysite.css js/ mysite.js templates/ 404.html 500.html base.html __init__.py urls.py wsgi.py Dockerfile manage.py requirements.txt这一结构的模板源头就是仓库中的 wagtail/project_template/ 目录其中project_name/子目录在生成时会被重命名为你的项目名如mysite/模板文件中的{{ project_name }}、{{ secret_key }}等占位符会被替换为真实值例如 wagtail/project_template/manage.py-tpl 中的os.environ.setdefault(DJANGO_SETTINGS_MODULE, {{ project_name }}.settings.dev)生成的manage.py会默认使用dev设置模块。“home”应用HomePage 模型与首页数据迁移模板中home应用的作用是帮助你更快启动项目它提供一个HomePage模型并通过迁移在首次迁移数据库时自动创建一个首页。HomePage 模型定义home/models.py 极其精简——HomePage直接继承 Wagtail 的Page抽象基类不添加任何字段from django.db import models from wagtail.models import Page class HomePage(Page): pass这体现了 Wagtail 页面建模的基本方式先有一个可用的页面类型之后按需为其添加字段、面板和迁移。迁移如何自动创建首页home/migrations/下有两个迁移文件0001_initial.py标准的CreateModel操作为HomePage建表其主键page_ptr是以OneToOneField指向wagtailcore.Page的父链multi-table inheritance0002_create_homepage.py一个数据迁移RunPython负责把“能跑起来的最小站点”直接写进数据库。从 0002_create_homepage.py 的实现可以看到具体步骤删除 Wagtail 核心迁移wagtailcore.0002_initial_data预先创建的那个默认Page类型的home页面按content_typeslughomedepth2定位为HomePage创建ContentType创建HomePage实例显式写入path00010001、depth2、url_path/home/创建Site对象hostnamelocalhost并把新首页设为该站点的根节点is_default_siteTrue。此外该迁移通过run_before [(wagtailcore, 0053_locale_model)]声明执行顺序确保它在核心后续迁移之前完成数据替换。因此你执行python manage.py migrate之后数据库中就已经有一个指向/的默认站点和一条HomePage记录无需再手工建页。首页模板与欢迎页home/templates/home/home_page.html 继承base.html并设置了body_class区块为template-homepage。从当前仓库的模板内容看它还通过{% include home/welcome_page.html %}引入了一个“欢迎页”配套样式为 home/static/css/welcome_page.css并在注释中提示如果你已经熟悉 Wagtail、想移除欢迎屏幕删除对应的 include 与样式引入行即可。search 应用内置的站点搜索目录树中的search应用提供了一个开箱即用的页面搜索视图。search/views.py 的核心逻辑从request.GET中取query与page参数当存在查询词时调用Page.objects.live().search(search_query)搜索所有已发布页面——这就是 Wagtail 数据库搜索后端的直接用法WAGTAILSEARCH_BACKENDS在默认配置中使用wagtail.search.backends.database用 Django 的Paginator按每页 10 条分页并对PageNotAnInteger/EmptyPage做了兜底处理用TemplateResponse渲染search/search.html。源码注释中还给出了接入“推广搜索结果”Promoted search results模块的方式将wagtail.contrib.search_promotions加入INSTALLED_APPS并在视图内调用Query.get(search_query)/query.add_hit()记录查询命中。项目模板中的 Django 设置四文件拆分项目设置文件被拆分为base.py、dev.py、production.py与local.py四个文件这一拆分是模板最重要的工程约定之一。文件用途典型内容base.py开发与生产共用的全局设置绝大多数配置应集中在这里INSTALLED_APPS、中间件、数据库、静态/媒体文件、Wagtail 相关设置dev.py仅供开发者使用的设置DEBUG True、控制台邮件后端production.py仅供生产服务器运行的设置DEBUG False、ManifestStaticFilesStoragelocal.py针对特定机器的本地设置绝不应被版本控制系统跟踪密钥、数据库口令等机密官方文档在此还给出两条生产环境建议其一生产服务器上建议只把机密API 密钥、口令等存放在local.py中——将来排查服务器异常行为时能省去大量“密钥从哪里来”的困惑其二如果多台生产服务器需要不同配置建议为每台服务器各维护一份不同的production.py。base.py 中的关键配置从 project_name/settings/base.py 源码看默认设置包含了以下内容应用注册INSTALLED_APPS除项目自身的home、search外默认启用了wagtail.contrib.forms、wagtail.contrib.redirects、wagtail.embeds、wagtail.sites、wagtail.users、wagtail.snippets、wagtail.documents、wagtail.images、wagtail.search、wagtail.admin、wagtail以及依赖库modelcluster、taggit、django_filters中间件在 Django 默认中间件链末尾追加了wagtail.contrib.redirects.middleware.RedirectMiddleware用于在页面 404 时按重定向表进行跳转数据库默认为项目根目录下的 SQLiteBASE_DIR / db.sqlite3静态文件STATICFILES_DIRS指向项目static/目录STATIC_ROOT指向根目录static/表单字段上限DATA_UPLOAD_MAX_NUMBER_FIELDS 10_000源码注释解释了原因——Wagtail 页面编辑器中特别复杂的页面模型字段数可能超过 Django 默认的 1000 上限Wagtail 核心设置base.pyWAGTAIL_SITE_NAME站点显示名默认取项目名WAGTAILSEARCH_BACKENDS默认使用wagtail.search.backends.database数据库搜索后端WAGTAILADMIN_BASE_URL后台生成完整 URL如通知邮件使用的基础地址注释特别提醒不要包含/admin或结尾斜杠模板中默认值为http://example.com实际部署时应修改WAGTAILDOCS_EXTENSIONS文档库允许上传的文件扩展名白名单csv、docx、pdf、xlsx等注释指出省略该设置虽可允许所有文件但在允许不受信任用户上传时存在安全风险WAGTAILDOCS_MAX_UPLOAD_SIZE文档上传大小上限默认 10MB。dev.py 与 production.pydev.py 在from .base import *之后设置DEBUG True、生成的SECRET_KEY、ALLOWED_HOSTS [*]以及控制台邮件后端EmailBackend指向 console邮件直接打印到终端并在文件末尾尝试from .local import *——导入失败则静默跳过这正是local.py可选存在的实现方式。production.py 则设置DEBUG False并把静态文件后端切换为ManifestStaticFilesStorage——源码注释解释了原因防止 Wagtail 升级等场景下浏览器缓存到过期的 JavaScript/CSS 资源。它同样以try: from .local import *结尾。settings/init.py 是空文件仅用于把settings/标记为 Python 包项目实际用哪个设置模块由manage.py/wsgi.py中的DJANGO_SETTINGS_MODULE决定模板默认指向{{ project_name }}.settings.dev见 wsgi.py。默认模板与静态文件模板目录mysite/templates/包含base.html、404.html和500.html。这些文件在 Wagtail 站点中几乎必然需要因此被直接放进了项目模板。静态目录则包含空的mysite.css与mysite.js。project_name/templates/base.html 是典型的 Wagtail 站点基模板值得注意的几个细节加载wagtailcore_tags与wagtailuserbar模板标签库并在body中输出{% wagtailuserbar %}——它负责在有权限的用户访问前台页面时显示 Wagtail 用户栏编辑入口title优先使用page.seo_title否则回退到page.title并通过wagtail_site标签追加站点名后缀当page.search_description存在时输出meta namedescription当request.in_preview_panel为真即从后台实时预览面板打开时输出base target_blank强制预览页内的链接在新标签页打开预留extra_css、content、extra_js、body_class等区块供子模板覆盖并引用全局样式表css/{{ project_name }}.css与脚本js/{{ project_name }}.js。编写与运行测试使用wagtail start创建项目时home/tests.py中会包含一组基础测试。按照官方文档这些测试验证以下四点根PageID1被自动创建可以作为根页面的子节点创建HomePage创建出的HomePage可以被渲染renderable该HomePage使用home/home_page.html模板。对照仓库中的 home/tests.py 可以看到具体实现两个测试类都继承wagtail.test.utils.WagtailPageTestCase。HomeSetUpTests.test_root_create断言Page.objects.get(pk1)非空HomeSetUpTests.test_homepage_create用root_page.add_child(instancehomepage)创建首页并断言其存在。HomeTests.setUp则创建了一个hostnametestsite的默认站点和首页实例随后test_homepage_is_renderable调用assertPageIsRenderabletest_homepage_template_used通过self.client.get(self.homepage.url)请求页面并用assertTemplateUsed断言使用了home/home_page.html模板。运行测试的方式是进入项目目录执行python manage.py test关于 Django 测试的更多细节可参考 Django 官方文档的测试章节Wagtail 特有的测试工具如WagtailPageTestCase、WagtailTestUtils则在 Wagtail 文档的“Testing your Wagtail site”docs/advanced_topics/testing.md中有专门介绍。Dockerfile容器化构建与运行模板根目录包含一个Dockerfile用于把站点构建并部署为 Docker 容器。按官方文档构建与运行命令为docker build -t mysite . docker run -p 8000:8000 mysite从仓库中的 Dockerfile 源码看它采用了多阶段构建builder 阶段基于python:3.14-slim-bookworm安装编译 Python 包所需的系统依赖build-essential、libpq-dev、libmariadb-dev、libjpeg62-turbo-dev、zlib1g-dev、libwebp-dev创建/opt/venv虚拟环境pip install -r requirements.txt并额外安装gunicorn25.1.0Dockerfileruntime 阶段同样基于python:3.14-slim-bookworm只安装运行期库libpq5、libmariadb3、libjpeg62-turbo、libwebp7创建非 root 用户wagtailEXPOSE 8000设置PYTHONUNBUFFERED1与PORT8000从 builder 阶段拷贝虚拟环境构建期操作把工作目录设为/app把源码拷入执行python manage.py collectstatic --noinput --clear收集静态文件Dockerfile启动命令CMD set -xe; python manage.py migrate --noinput; gunicorn {{ project_name }}.wsgi:applicationDockerfile——先迁移数据库再用 Gunicorn 启动应用。源码中附带 WARNING 注释启动时同时迁移数据库并非最佳实践生产上应手动迁移或利用托管平台的 release 阶段机制这里这么做只是为了能用一条docker run把 Wagtail 实例跑起来。配套的 requirements.txt 非常简短锁定Django6.1,6.2与当前开发版 Wagtailwagtail8.1a0。注意这份文件反映的是当前仓库开发主干的状态实际使用wagtail start时生成的版本约束取决于你所安装的 Wagtail 版本。使用自定义模板--template若要使用自定义项目模板在运行wagtail start时通过--template选项指定即可。该选项接受一个目录、文件路径或 URL行为与django-admin startproject --template类似。例如一个以 GitHub 仓库形式维护的自定义模板可以用如下 URL 使用wagtail start myproject --templatehttps://github.com/githubuser/wagtail-awesome-template/archive/main.zip社区维护的自定义模板合集如 awesome-wagtail 中的“Templates (start command)”清单收录了多个可直接用于项目的模板仓库可以作为选型参考。编写自定义模板时的注意事项社区中存在一些现成的自定义模板仓库例如 thibaudcolas/wagtail-tutorial-template、torchbox/wagtail-news-template 等可作为参考。编写自定义模板时最常见的坑是--template选项会像 Django 项目模板一样解析模板文件中的模板语法。如果你的模板文件本身包含 Django 模板标签{% extends %}、{% for %}等生成项目时会抛出解析错误。解决办法是在自定义模板的每个模板文件外层包裹{% verbatim %} ... {% endverbatim %}标签例如{% verbatim %} {% extends base.html %} {% load wagtailcore_tags %} {% block body_class %}template-blogindexpage{% endblock %} {% block content %} h1{{ page.title }}/h1 div classintro{{ page.intro|richtext }}/div {% for post in page.get_children %} h2a href{% pageurl post %}{{ post.title }}/a/h2 {{ post.specific.intro }} {{ post.specific.body }} {% endfor %} {% endblock %} {% endverbatim %}这样{% verbatim %}内的所有标签在模板渲染即项目生成阶段会原样保留到生成的项目中从而避免被当作模板指令执行或引发语法错误。仓库自带的默认模板正是采用类似机制的模板文件通过{% templatetag openblock %}等写法转义标签字符并在其中保留{{ project_name }}这类需要真正被替换的变量可参见 base.html 源码。小结适用前提与版本说明本文所有目录结构、设置拆分与测试内容对应仓库中的 wagtail/project_template/是wagtail start的默认模板来源生成的项目默认使用 SQLite、数据库搜索后端与控制台邮件后端面向快速开发上生产前至少需要修改WAGTAILADMIN_BASE_URL、数据库配置并按 production.py 的思路使用production设置模块当前仓库主干的模板使用 Python 3.14 基础镜像、Django 6.1 约束属于开发版本快照在已发布的稳定版 Wagtail 上执行wagtail start时生成的requirements.txt与 Dockerfile 中的基础镜像版本以你所用版本为准。【免费下载链接】wagtailA Django content management system focused on flexibility and user experience项目地址: https://gitcode.com/GitHub_Trending/wa/wagtail创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考