Wagtail 2.0中Draftail编辑器下RichTextField无法编辑求助

我之前帮朋友处理过几乎一模一样的Wagtail 2.0升级故障，Draftail编辑器失效的情况大多和旧内容格式不兼容、编辑器配置缺失或者静态资源加载失败有关，咱们一步步来排查解决：

第一步：先抓核心报错（最关键！） #

Draftail是纯JS驱动的编辑器，只要浏览器控制台有报错，基本直接导致编辑器罢工。打开编辑页面后按F12切换到Console标签，看看有没有红色的错误提示（比如404找不到JS/CSS文件、JS语法错误）；同时检查Network标签，确认Wagtail的Draftail相关静态资源（比如draftail.js、draftail.css）都能正常加载。

第二步：检查RichTextField的编辑器配置 #

Wagtail 2.0把Draftail设为默认编辑器，但它的默认功能集合（features）和旧版Hallo.js不一样，而且对HTML格式的要求更严格。

1. 全局编辑器配置（settings.py） #

如果你移除了Hallo的配置，确保Draftail的默认配置是完整的，在settings.py里补充：

WAGTAILADMIN_RICH_TEXT_EDITORS = {
    'default': {
        'WIDGET': 'wagtail.admin.rich_text.DraftailRichTextArea',
        'OPTIONS': {
            # 按需添加你需要的编辑功能，覆盖默认值
            'features': ['h1', 'h2', 'h3', 'bold', 'italic', 'link', 'ol', 'ul', 'image', 'embed', 'code']
        }
    },
}

如果你的旧内容里有Hallo生成的行内样式（比如文字颜色、对齐），还需要额外添加'style'和'text-align'这两个features。

2. 模型字段的单独配置 #

如果某个页面的RichTextField需要特殊配置，可以直接在字段定义里指定features：

# models.py
from wagtail.core.fields import RichTextField

class MyPage(Page):
    # 明确指定支持的功能，确保和旧内容的格式匹配
    body = RichTextField(features=['h1', 'h2', 'bold', 'italic', 'link', 'ol', 'ul', 'style'])

第三步：处理旧内容的格式兼容性问题 #

Hallo.js生成的HTML结构比较松散，比如会自动添加多余的<div>标签、用<span>包裹样式，这些都是Draftail不识别的，会导致内容无法显示和编辑。

Wagtail自带了专门的清理工具，处理这类升级后的内容兼容问题：

1. 先试运行（只预览修改内容，不实际变更）：

python manage.py richtext_cleanup --dry-run

2. 确认没问题后，正式执行清理：

python manage.py richtext_cleanup

这个命令会把旧的Hallo格式HTML转换为Draftail兼容的结构。

第四步：检查静态资源和依赖版本 #

1. 升级后一定要重新收集静态资源，避免旧的静态文件干扰：

python manage.py collectstatic

2. 确认你的Django版本符合Wagtail 2.0的要求（必须是Django 1.11+，不支持1.10及以下），可以运行pip freeze查看依赖版本，有冲突的话及时调整。

最后验证 #

完成上面的步骤后，先创建一个全新的测试页面，在Draftail里编辑内容并保存：

• 如果新页面能正常显示和编辑，说明配置没问题，问题出在旧内容的格式上，继续用richtext_cleanup处理即可；
• 如果新页面也失效，那大概率是静态资源加载或者依赖版本的问题，再回头检查控制台报错。

内容的提问来源于stack exchange，提问作者redmood