Wagtail 是一个开源的内容管理系统（CMS），基于 Python 的 Django 框架构建。它专为开发者、设计师和内容编辑者设计，提供了一个灵活、高效的平台，用于创建和管理网站内容。Wagtail 以其直观的编辑界面和强劲的扩展性而闻名，被广泛用于企业级内容管理，而无需锁定在特定模板或结构中。 它支持从简单博客到复杂的企业网站的一切需求，已被 NASA、Google、NHS（英国国家医疗服务体系）、Oxfam、Mozilla 和 MIT 等知名组织采用。

历史背景

Wagtail 于 2011 年由英国数字机构 Torchbox 开发，作为 Django 的 CMS 扩展。它最初是为了解决 Torchbox 内部的内容管理需求而创建的，随着开源社区的贡献，迅速成长为一个成熟的 CMS 项目。截至 2025 年，Wagtail 已发展到 7.x 版本，拥有活跃的社区支持，包括每月新闻通讯和专业服务。它的设计哲学强调“编辑者友善”和“开发者自由”，避免了传统 CMS 的复杂性和锁定问题。

关键特性

Wagtail 的核心优势在于平衡了编辑者的创意控制与开发者的灵活性。以下是其主要特性：

特性	描述
StreamField	一个创新的编辑界面，允许编辑者自由组合文本、图像、视频等内容块，而无需开发者干预。适合博客或新闻页面。
开发者灵活性	基于 Django，支持 Python 的一切功能。只需几行代码即可添加新内容类型。
前端自由	提供简单的模板系统，设计师可以准确控制样式，支持 headless（无头）模式。
无锁定费用	开源免费，无许可费；全球专业机构（如 Torchbox）提供支持。
编辑器控制	直观的 admin 界面，支持富文本编辑、图像管理、表单和搜索，提升生产力。
多站点支持	轻松管理多个网站，如 Cambridge University Hospitals 的多站点设置。

架构概述

Wagtail 的架构建立在 Django 之上，使用 MVT（Model-View-Template）模式。核心是页面模型（Page），它继承 Django 的模型系统，支持树状结构（页面层级）。它集成 Wagtail 的扩展，如 Wagtail API（用于 headless CMS）和搜索模块（基于 Elasticsearch 或 PostgreSQL）。与其他 CMS 不同，Wagtail 强调“内容即代码”，允许开发者通过 Python 类定义内容结构，而非固定表单。

用例

• 文化与教育：M+ 博物馆使用 Wagtail 构建数字基础，支持多语言和 headless 集成。
• 医疗与政府：NHS 和 Cambridge University Hospitals 用于多站点内容管理，确保可访问性和响应式设计。
• 企业与非营利：UC Berkeley 和 Syracuse University 赞扬其在内容创建和维护上的效率。 适合博客、新闻门户、企业网站或 API 驱动的应用。

核心概念

Wagtail 的设计围绕几个关键概念，确保内容管理和扩展的简易性：

• Pages（页面）：Wagtail 的核心实体。每个页面是一个 Django 模型的子类，支持树状层次（首页 > 子页面）。页面可以有自定义字段，如标题、内容，并通过模板渲染。
• StreamField：用于非结构化内容的字段。编辑者可以拖拽添加块（如段落、图像、嵌入视频），开发者定义块类型。例如，在博客中混合文本和媒体。
• Snippets（片段）：非页面内容，如作者简介、广告或页脚元素。它们是可重用的模型，不需要 URL，直接在页面中引用。
• Images/Videos（图像/视频）：内置媒体库，支持上传、裁剪和优化。使用 ImageChooserPanel 在 admin 中选择。
• Search（搜索）：内置全文搜索，支持 Elasticsearch 集成。使用 {% search %} 模板标签实现站点搜索。 这些概念通过 content_panels 和 promote_panels 在 admin 界面中配置，确保编辑体验流畅。

安装 Wagtail

Wagtail 的安装简单，只需 Python 环境。以下是步步指南（假设使用 Python 3.9+）。

先决条件

• Python 3.9 或更高（检查：python --version）。
• pip 和虚拟环境工具（venv）。
• 推荐在虚拟环境中安装，避免全局污染。

步骤

1. 创建并激活虚拟环境：

Windows (cmd)：

py -m venv mysiteenv mysiteenvScriptsactivate

macOS/Linux (bash)：

python -m venv mysite/env source mysite/env/bin/activate 

（激活后，命令行显示 (env)）。

安装 Wagtail：

pip install wagtail

生成新项目：

wagtail start mysite

这会创建一个 mysite 文件夹，包含基本结构（如 home/、search/、manage.py 和 requirements.txt）。

安装项目依赖：

cd mysite pip install -r requirements.txt

创建数据库（默认 SQLite）：

python manage.py migrate

创建超级用户（admin 账户）：

python manage.py createsuperuser

跟随提示输入用户名、邮箱和密码。

启动服务器：

python manage.py runserver

常见问题：如果 python 未识别，使用 python3 或添加 Python 到 PATH。 可选：安装 Elasticsearch 以增强搜索。

入门上手：构建你的第一个 Wagtail 站点

以下基于官方教程的初学者指南，逐步构建一个简单站点，包括首页扩展和基本博客。假设已完成安装。

步骤 1: 运行初始站点

• 启动服务器后，你会看到 Wagtail 欢迎页。登录 admin，探索“Pages”部分（显示首页树）。

步骤 2: 扩展 HomePage 模型（添加内容字段）

编辑 home/models.py：

from django.db import models
from wagtail.models import Page
from wagtail.fields import RichTextField
from wagtail.admin.panels import FieldPanel

class HomePage(Page):
    body = RichTextField(blank=True)  # 可选的富文本字段

    content_panels = Page.content_panels + [
        FieldPanel('body'),  # 在 admin 中添加 body 面板
    ]

• 更新数据库：

python manage.py makemigrations 
python manage.py migrate

• 在 admin 中编辑“Home”页面，添加 body 内容（如“欢迎来到我们的站点！”），然后“Publish”。
• 更新模板 home/templates/home/home_page.html：

{% extends "base.html" %}
{% load wagtailcore_tags %}

{% block content %}
    <h1>{{ page.title }}</h1>
    {{ page.body|richtext }}  <!-- 渲染富文本 -->
{% endblock %}

重启服务器，刷新首页查看变化。

步骤 3: 创建基本博客

• 生成博客 app：

python manage.py startapp blog

• 添加到 settings（mysite/settings/base.py 的 INSTALLED_APPS）：

INSTALLED_APPS = [
    'blog',  # 新添加
    'home',
    'search',
    # ... 其他
]

• 定义博客模型（blog/models.py）：

from django.db import models
from wagtail.models import Page
from wagtail.fields import RichTextField
from wagtail.admin.panels import FieldPanel

class BlogPage(Page):
    intro = RichTextField()
    body = StreamField([  # 使用 StreamField 添加混合内容
        ('paragraph', RichTextField()),
        ('image', models.ForeignKey('wagtailimages.Image', on_delete=models.CASCADE)),
    ])

    content_panels = Page.content_panels + [
        FieldPanel('intro'),
        FieldPanel('body'),
    ]

• StreamField 允许编辑者添加段落或图像块。

• 更新数据库：

python manage.py makemigrations blog 
python manage.py migrate

• 添加博客页面： 在 admin “Pages” > 选择首页 > “Add child page” > 选择“Blog Page”。 编辑 intro 和 body（使用 StreamField 添加块），发布。

• 创建博客索引页面（可选，blog/models.py 添加）：

class BlogIndexPage(Page):
    intro = RichTextField(blank=True)

    content_panels = Page.content_panels + [
        FieldPanel('intro'),
    ]

    def get_context(self, request):
        context = super().get_context(request)
        context['posts'] = BlogPage.objects.child_of(self).live()
        return context

模板
blog/templates/blog/blog_index_page.html：

{% extends "base.html" %}
{% load wagtailcore_tags %}

{% for post in posts %}
    <h2><a href="{% pageurl post %}">{{ post.title }}</a></h2>
    {{ post.intro|richtext }}
{% endfor %}

步骤 4: 添加媒体和搜索

• 图像：在 admin “Images” 上传，StreamField 中选择。
• 搜索：添加 search/templates/search/search.html，使用 {% search "query" %} 标签。

步骤 5: 部署基础

• 使用 Heroku 或 Docker（项目有 Dockerfile）。
• 运行 python manage.py collectstatic 收集静态文件。
• 设置生产数据库（如 PostgreSQL）：修改 settings/base.py 中的 DATABASES。

提示

• 探索 admin：使用“Workflows” 审批内容，“Snippets” 添加重用元素。
• 调试：检查控制台日志，常见错误如迁移未运行。

通过这些步骤，你可以快速上手 Wagtail。提议从简单页面开始，逐步添加 StreamField 和 API。