Django 中集成现代 CKEditor 5 的完整指南-Python教程-PHP中文网

Django 中集成现代 CKEditor 5 的完整指南

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（即原 django-ckeditor v6.x）已明确发出警告（W001），强烈建议迁移至更安全、更活跃的替代方案。CKEditor 5 是官方主推的下一代编辑器，具备模块化架构、更好的可访问性、现代前端生态兼容性（如 Webpack、ESM 支持）以及持续的安全更新。

目前最成熟、专为 Django 设计的 CKEditor 5 集成方案是 django-ckeditor-5（由 hvlads 维护，GitHub 地址：https://www.php.cn/link/792efc1687658bdf2e49af5ab8c6d38f）。它并非简单封装，而是深度适配 Django 表单、模型字段与 Admin 界面，同时默认使用 CKEditor 5 的开源社区版（MIT 许可），无需商业授权即可用于开源及多数商业项目。

✅ 快速集成步骤如下：

安装依赖

Django
避免常见的 Django 错误——QuerySet 评估、N+1 查询、迁移冲突和 ORM 陷阱。

下载
```
pip install django-ckeditor-5
```

注册应用
在 settings.py 中添加：

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

配置 CKEditor 5 工具栏与功能（可选但推荐）

# 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

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

5. **Admin 后台自动适配**（无需额外代码）  
只要字段类型为 `CKEditor5Field`，Django Admin 将自动渲染对应编辑器——无需重写 `ModelAdmin.formfield_overrides`。

⚠️ 注意事项：  
- `django-ckeditor-5` 默认使用 CDN 加载 CKEditor 5 构建（`@ckeditor/ckeditor5-build-classic`），若需离线部署或定制构建，请参考文档配置本地 `build` 路径；  
- 图片上传需配合 `django-ckeditor-5` 内置的 `upload` 视图（已自动注册 URL），确保 `urls.py` 包含：  
  ```python
  from django_ckeditor_5 import urls as ckeditor5_urls
  urlpatterns += [path("ckeditor5/", include(ckeditor5_urls)),]