Wagtail 提供 wagtail start 命令和项目模板，让您尽快开始新的 Wagtail 项目，但也可以轻松将 Wagtail 集成到现有 Django 项目中。

Wagtail 目前兼容 Django 3.2、4.1 和 4.2。首先，从 PyPI 安装 wagtail 包：

pip install wagtail

或将包添加到现有的需求文件中。这还将安装 Pillow library 作为依赖项，它需要 libjpeg 和 zlib - 请参阅 Pillow 的 platform-specific installation instructions 。

Settings

在您的 settings.py 文件中，将以下应用程序添加到 INSTALLED_APPS ：

'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',

将以下条目添加到 MIDDLEWARE ：

'wagtail.contrib.redirects.middleware.RedirectMiddleware',

添加 STATIC_ROOT 设置，如果您的项目还没有：

STATIC_ROOT = os.path.join(BASE_DIR, 'static')

添加 MEDIA_ROOT 和 MEDIA_URL 设置，如果您的项目还没有这些设置：

MEDIA_ROOT = os.path.join(BASE_DIR, 'media')
MEDIA_URL = '/media/'

添加 WAGTAIL_SITE_NAME - 这将显示在 Wagtail 管理后端的主仪表板上：

WAGTAIL_SITE_NAME = 'My Example Site'

添加 WAGTAILADMIN_BASE_URL - 这是 Wagtail 管理站点使用的基础 URL。它通常用于生成通知电子邮件中的 url:

WAGTAILADMIN_BASE_URL = 'http://example.com'

如果此设置不存在，Wagtail 将回调 request.site。root_url 或请求的主机名。虽然此设置不是严格要求的，但强烈建议这样做，因为不设置可能会在通知电子邮件中产生不可用的 url。

各种其他设置可用于配置 Wagtail 的行为 - 请参阅 Settings 。

URL 配置

现在将以下内容添加到您的 urls.py 文件中：

from django.urls import path, include

from wagtail.admin import urls as wagtailadmin_urls
from wagtail import urls as wagtail_urls
from wagtail.documents import urls as wagtaildocs_urls

urlpatterns = [
    ...
    path('cms/', include(wagtailadmin_urls)),
    path('documents/', include(wagtaildocs_urls)),
    path('pages/', include(wagtail_urls)),
    ...
]

此处的 URL 路径可以根据需要进行更改，以适合您项目的 URL 方案。

wagtailadmin_urls 提供 Wagtail 的管理界面。它独立于 Django 的管理界面 django .contrib.admin。只有 Wagtail 的项目托管 Wagtail 管理在 /admin/ ，但如果这与你的项目现有的管理后端冲突，那么你可以使用替代路径，如 /cms/。

Wagtail 从位置 wagtaildocs_urls 提供文档文件。如果不打算使用 Wagtail 的文档管理特性，可以省略这一点。

Wagtail 从 wagtail_urls 位置提供您的页面。在上面的例子中，Wagtail 处理 /pages/ 目录下的 URL，让 Django 项目像往常一样处理根 URL 和其他路径。如果您希望 Wagtail 处理包括根 URL 在内的整个 URL 空间，那么在 urlpatterns 列表的末尾放置 path('', include(wagtail_urls))。在 URL 模式的末尾放置 path('', include(wagtail_urls)) 可以确保它不会覆盖更具体的 URL 模式。

最后，您需要设置项目以服务来自 MEDIA_ROOT 的用户上传文件。你的 Django 项目可能已经准备好了，但如果没有，在 urls.py 中添加下面的代码片段：

from django.conf import settings
from django.conf.urls.static import static

urlpatterns = [
    # ... the rest of your URLconf goes here ...
] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

请注意，这仅适用于开发模式（ DEBUG = True ）；在生产中，您需要配置 Web 服务器以服务来自 MEDIA_ROOT 的文件。有关更多详细信息，请参阅 Django 文档： Serving files uploaded by a user during development 和 Deploying static files 。

完成此配置后，您就可以运行 python manage.py migrate 来创建 Wagtail 使用的数据库表。

用户帐号

Wagtail 默认使用 Django 的默认用户模型。超级用户帐户可以自动访问 Wagtail 管理界面；如果您还没有 python manage.py createsuperuser ，请使用 python manage.py createsuperuser 。Wagtail 支持自定义用户模型，但有一些限制； Wagtail 使用 Django 权限框架的扩展，因此您的用户模型必须至少继承自 AbstractBaseUser 和 PermissionsMixin 。

开始开发

现在，您已准备好将新应用程序添加到 Django 项目，通过 python manage.py startapp - 请记住将新颖用添加到 settings.py 文件中的 INSTALLED_APPS ，并设置页面模型，如你的第一个 Wagtail 站点中所述。

请注意，不使用 Wagtail 项目模板时存在一个小差异： Wagtail 创建基本类型 Page 的初始主页，其中不包含标题之外的任何内容字段。您可能希望将其替换为您自己的 HomePage 类 - 当您这样做时，请确保设置站点记录（在 Wagtail 管理中的“设置/站点”下）以指向新主页。