在Django项目中集成现代CKEditor 5富文本编辑器的完整指南

时间：2026-07-03 06:50

Django 官方建议开发者停止使用存在安全风险的 CKEditor 4，转而迁移至符合现代标准的 CKEditor 5。本文详细讲解如何借助 django-ckeditor-5 在 Django 项目中安全、高效地集成 CKEditor 5，并提供清晰的配置步骤与关键注意事项。首先交代一个重要背

Django 官方建议开发者停止使用存在安全风险的 CKEditor 4，转而迁移至符合现代标准的 CKEditor 5。本文详细讲解如何借助 django-ckeditor-5 在 Django 项目中安全、高效地集成 CKEditor 5，并提供清晰的配置步骤与关键注意事项。

首先交代一个重要背景：CKEditor 4 自 2023 年底起官方已终止维护，4.22.1 版本中遗留了一个至今未修复的安全漏洞。Django 生态中的传统插件 django-ckeditor（即原 v6.x）启动时会弹出 W001 警告，强烈催促开发者迁移。官方力推的 CKEditor 5 才是下一代富文本编辑器：模块化架构、良好的可访问性、兼容 Webpack 与 ESM，并且会持续获得安全更新——这才是真正值得使用的方案。

目前 Django 领域最成熟、专门适配 CKEditor 5 的解决方案，是 django-ckeditor-5（由 hvlads 维护，可在 GitHub 找到）。它并非简单的封装，而是深度集成了 Django 的表单、模型字段和 Admin 界面，默认采用 CKEditor 5 的开源社区版（MIT 协议），无论是开源项目还是大多数商业项目都无需付费购买授权。

下面直接给出集成步骤，按顺序执行即可。

第一步：安装依赖

一条命令完成：

pip install django-ckeditor-5

第二步：注册应用

在 settings.py 的 INSTALLED_APPS 中添加：

INSTALLED_APPS = [
    # ... 其他应用
    'django_ckeditor_5',
]

第三步：配置工具栏与功能

此步骤可选但强烈建议执行——你可以决定编辑器中显示哪些按钮，以及图片上传、表格等高级功能是否启用。以下提供一套默认配置和一套扩展配置，复制到 settings.py 后按需调整：

# settings.py
CKEDITOR_5_CONFIGS = {
    'default': {
        'toolbar': ['heading', '|', 'bold', 'italic', 'link', 'bulletedList', 'numberedList', 'blockQuote', 'undo', 'redo'],
        'height': 300,
    },
    'extends': {
        'blockToolbar': [
            'paragraph', 'heading1', 'heading2', 'heading3',
            '|',
            'bulletedList', 'numberedList',
            '|',
            'imageUpload', 'table', 'mediaEmbed'
        ],
        'toolbar': ['heading', '|', 'outdent', 'indent', '|', 'bold', 'italic', 'link', 'underline', 'strikethrough', 'codeBlock', 'subscript', 'superscript', 'highlight', '|', 'bulletedList', 'numberedList', 'todoList', '|', 'blockQuote', 'insertImage', 'insertTable', 'mediaEmbed', 'undo', 'redo'],
        'image': {
            'toolbar': ['imageTextAlternative', '|', 'imageStyle:alignLeft', 'imageStyle:alignCenter', 'imageStyle:alignRight'],
            'styles': ['full', 'alignLeft', 'alignCenter', 'alignRight']
        }
    }
}

第四步：在模型中使用富文本字段

先导入字段类：

# models.py
from django.db import models
from django_ckeditor_5.fields import CKEditor5Field

然后在模型中使用 CKEditor5Field 替换传统的 TextField，并指定之前配置的 config_name：

class Article(models.Model):
    title = models.CharField(max_length=200)
    content = CKEditor5Field(config_name='default')  # 或 'extends'

第五步：Admin 后台自动适配

这一点极为省心——只要字段类型是 CKEditor5Field，Django Admin 就会自动渲染出对应的编辑器，完全无需重写 ModelAdmin.formfield_overrides。换句话说，模型配置好之后，后台直接就能使用漂亮的富文本编辑框。

几个常见的踩坑点

CDN 加载问题：库默认从 CDN 拉取 CKEditor 5 的构建文件（@ckeditor/ckeditor5-build-classic）。如果你的项目需要离线部署或自定义编辑器构建，必须参考官方文档配置本地 build 路径。
图片上传配置：库内置了 upload 视图，可自动注册 URL。记得在项目主 urls.py 中添加以下代码：
```
from django_ckeditor_5 import urls as ckeditor5_urls
urlpatterns += [path("ckeditor5/", include(ckeditor5_urls)),]
```
REST Framework 场景：该库目前没有直接提供序列化器支持。如果你使用 DRF，手动处理 HTML 字段的清洗与验证是必需的——推荐搭配 bleach 库来过滤 XSS 攻击。
不要购买 CKEditor 4 LTS 商业版：那个版本按域名或用户数收费，限制严格，长期来看技术债难以消化。直接拥抱 CKEditor 5 才是正确的方向。