2026/9/14 4:09:47
FEATURED · 精选文章 
1. 项目概述在Web开发领域富文本编辑器是内容管理系统的核心组件之一。作为一名长期使用Django框架的后端开发者我最近在个人博客项目中尝试了CKEditor5的集成发现这套方案在易用性和功能性上达到了很好的平衡。本文将详细记录从零开始搭建一个支持CKEditor5的Django博客系统的完整过程。这个方案特别适合需要快速搭建内容管理后台的开发者。相比传统的CKEditor4CKEditor5提供了更现代化的界面和更简洁的API同时保持了良好的兼容性。我们将从环境准备开始逐步完成编辑器安装、配置、前端集成、数据存储和展示的全流程。2. 环境准备与基础配置2.1 创建Django项目首先确保你的开发环境已经安装了Python 3.6和Django 2.2版本。我推荐使用虚拟环境来隔离项目依赖python -m venv myenv source myenv/bin/activate # Linux/Mac # 或 myenv\Scripts\activate # Windows pip install django新建一个Django项目和应用django-admin startproject ckeditor_demo cd ckeditor_demo python manage.py startapp blog在settings.py中添加blog应用到INSTALLED_APPSINSTALLED_APPS [ ... blog, ]2.2 安装CKEditor5相关包CKEditor5提供了多种集成方式我们选择通过npm安装前端资源再使用django-ckeditor-5作为后端桥梁npm install ckeditor/ckeditor5-build-classic pip install django-ckeditor-5注意如果你不熟悉前端构建流程也可以直接使用CDN引入CKEditor5但本地安装可以获得更好的版本控制和定制能力。3. CKEditor5配置详解3.1 Django后端配置在settings.py中添加django-ckeditor-5到INSTALLED_APPSINSTALLED_APPS [django_ckeditor_5]然后配置静态文件和媒体文件路径STATIC_URL /static/ STATIC_ROOT os.path.join(BASE_DIR, staticfiles) MEDIA_URL /media/ MEDIA_ROOT os.path.join(BASE_DIR, media)添加CKEditor5的自定义配置CKEDITOR_5_CONFIGS { default: { toolbar: [heading, |, bold, italic, link, bulletedList, numberedList, blockQuote, imageUpload, ], }, }3.2 前端资源集成在项目的base.html模板中引入CKEditor5资源!DOCTYPE html html head titleMy Blog/title script src{% static ckeditor5/build/ckeditor.js %}/script /head body {% block content %}{% endblock %} /body /html如果你使用CDN方式可以直接使用script srchttps://cdn.ckeditor.com/ckeditor5/34.0.0/classic/ckeditor.js/script4. 创建博客模型与表单4.1 文章模型设计在blog/models.py中创建文章模型from django.db import models from django_ckeditor_5.fields import CKEditor5Field class Article(models.Model): title models.CharField(max_length200) content CKEditor5Field(Content, config_namedefault) created_at models.DateTimeField(auto_now_addTrue) updated_at models.DateTimeField(auto_nowTrue) def __str__(self): return self.title注意我们使用了CKEditor5Field而不是普通的TextField这是django-ckeditor-5提供的专用字段类型。4.2 创建文章表单在blog/forms.py中创建表单from django import forms from .models import Article class ArticleForm(forms.ModelForm): class Meta: model Article fields [title, content]5. 视图与URL配置5.1 创建视图函数在blog/views.py中添加创建和显示文章的视图from django.shortcuts import render, redirect from .forms import ArticleForm from .models import Article def create_article(request): if request.method POST: form ArticleForm(request.POST) if form.is_valid(): form.save() return redirect(article_list) else: form ArticleForm() return render(request, blog/create_article.html, {form: form}) def article_list(request): articles Article.objects.all().order_by(-created_at) return render(request, blog/article_list.html, {articles: articles}) def article_detail(request, pk): article Article.objects.get(pkpk) return render(request, blog/article_detail.html, {article: article})5.2 配置URL路由在ckeditor_demo/urls.py中添加from django.contrib import admin from django.urls import path from blog import views urlpatterns [ path(admin/, admin.site.urls), path(articles/, views.article_list, namearticle_list), path(articles/create/, views.create_article, namecreate_article), path(articles/int:pk/, views.article_detail, namearticle_detail), ]6. 模板设计与实现6.1 创建文章模板在templates/blog/create_article.html中{% extends base.html %} {% block content %} h1Create New Article/h1 form methodpost {% csrf_token %} {{ form.media }} {{ form.as_p }} button typesubmitSave/button /form script ClassicEditor .create(document.querySelector(#id_content), { // 可以在这里添加更多CKEditor5配置 }) .catch(error { console.error(error); }); /script {% endblock %}6.2 文章列表模板在templates/blog/article_list.html中{% extends base.html %} {% block content %} h1Articles/h1 ul {% for article in articles %} li a href{% url article_detail article.pk %}{{ article.title }}/a small{{ article.created_at|date:Y-m-d }}/small /li {% endfor %} /ul a href{% url create_article %}Create New Article/a {% endblock %}6.3 文章详情模板在templates/blog/article_detail.html中{% extends base.html %} {% block content %} article h1{{ article.title }}/h1 time{{ article.created_at|date:Y-m-d H:i }}/time div{{ article.content|safe }}/div /article a href{% url article_list %}Back to list/a {% endblock %}重要提示注意在详情页中使用|safe过滤器来渲染HTML内容这是必要的但同时要确保你的内容来源可信以避免XSS攻击。7. 图片上传功能实现7.1 配置图片上传CKEditor5默认支持图片上传但需要额外的后端支持。首先安装必要的依赖pip install pillow然后修改settings.pyCKEDITOR_5_CONFIGS { default: { toolbar: [heading, |, bold, italic, link, bulletedList, numberedList, blockQuote, imageUpload, ], image: { toolbar: [imageTextAlternative, |, imageStyle:alignLeft, imageStyle:alignRight, imageStyle:alignCenter, imageStyle:side, |], styles: [ full, side, alignLeft, alignRight, alignCenter, ], } }, }7.2 创建图片上传视图在blog/views.py中添加from django.http import JsonResponse from django.views.decorators.csrf import csrf_exempt import os from django.core.files.storage import default_storage from django.core.files.base import ContentFile from django.conf import settings csrf_exempt def upload_image(request): if request.method POST and request.FILES.get(upload): upload request.FILES[upload] path os.path.join(uploads, upload.name) saved_path default_storage.save(path, ContentFile(upload.read())) url os.path.join(settings.MEDIA_URL, saved_path) return JsonResponse({url: url}) return JsonResponse({error: Invalid request}, status400)在urls.py中添加路由path(upload/, views.upload_image, nameckeditor_upload),7.3 前端配置修改create_article.html中的CKEditor5初始化代码ClassicEditor .create(document.querySelector(#id_content), { ckfinder: { uploadUrl: /upload/ } }) .catch(error { console.error(error); });8. 高级功能与自定义8.1 自定义工具栏你可以根据需要添加或移除工具栏按钮。例如要添加代码块支持首先安装插件npm install ckeditor/ckeditor5-code-block然后修改配置CKEDITOR_5_CONFIGS { default: { toolbar: [heading, |, bold, italic, link, bulletedList, numberedList, blockQuote, codeBlock, imageUpload, ], codeBlock: { languages: [ {language: python, label: Python}, {language: javascript, label: JavaScript}, {language: html, label: HTML}, {language: css, label: CSS}, ] } }, }8.2 使用自定义构建如果你想进一步定制编辑器可以创建自定义构建创建一个新的npm项目安装CKEditor5源码版本创建自定义配置文件构建并复制到Django的静态文件目录mkdir my-ckeditor5-build cd my-ckeditor5-build npm init -y npm install --save ckeditor/ckeditor5-dev-utils ckeditor/ckeditor5-theme-lark npm install --save ckeditor/ckeditor5-basic-styles ckeditor/ckeditor5-essentials ckeditor/ckeditor5-paragraph创建webpack.config.js和自定义构建脚本最后将构建结果复制到Django的static目录。9. 部署注意事项9.1 静态文件收集在生产环境中记得运行python manage.py collectstatic9.2 媒体文件服务在生产环境中你需要配置Web服务器如Nginx来服务媒体文件。示例Nginx配置location /media/ { alias /path/to/your/project/media/; } location /static/ { alias /path/to/your/project/staticfiles/; }9.3 安全考虑图片上传应该进行安全检查文件类型、大小等考虑使用django-cleanup自动删除未使用的媒体文件对于生产环境应该移除csrf_exempt装饰器使用更安全的方式处理图片上传10. 常见问题解决10.1 编辑器未加载检查静态文件是否正确加载查看页面源代码确保CKEditor5的JS文件路径正确检查浏览器控制台是否有错误10.2 图片上传失败确保MEDIA_ROOT和MEDIA_URL配置正确检查服务器是否有写入权限验证CSRF令牌是否正确处理10.3 内容保存后格式丢失确保在模板中使用|safe过滤器检查是否有多余的HTML转义发生验证模型字段是否正确定义为CKEditor5Field10.4 与其他Django应用冲突检查是否有其他应用也使用了CKEditor的不同版本确保静态文件命名空间不会冲突考虑使用django-ckeditor-5的命名空间功能11. 性能优化建议对于内容较多的页面考虑实现分页使用django-debug-toolbar识别性能瓶颈对文章列表页实现缓存考虑使用CDN分发静态文件和媒体资源对CKEditor5进行自定义构建只包含需要的功能模块12. 扩展思路这个基础实现可以进一步扩展添加文章分类和标签系统实现用户评论功能添加文章搜索功能支持Markdown和富文本双模式编辑实现版本控制和文章修订历史添加文章发布状态草稿、已发布、已归档我在实际项目中发现CKEditor5与Django的集成非常顺畅特别是对于需要频繁内容更新的场景。相比其他富文本编辑器解决方案CKEditor5提供了更好的现代浏览器支持和更简洁的API。
Django集成CKEditor5实现富文本编辑功能
1. 项目概述在Web开发领域富文本编辑器是内容管理系统的核心组件之一。作为一名长期使用Django框架的后端开发者我最近在个人博客项目中尝试了CKEditor5的集成发现这套方案在易用性和功能性上达到了很好的平衡。本文将详细记录从零开始搭建一个支持CKEditor5的Django博客系统的完整过程。这个方案特别适合需要快速搭建内容管理后台的开发者。相比传统的CKEditor4CKEditor5提供了更现代化的界面和更简洁的API同时保持了良好的兼容性。我们将从环境准备开始逐步完成编辑器安装、配置、前端集成、数据存储和展示的全流程。2. 环境准备与基础配置2.1 创建Django项目首先确保你的开发环境已经安装了Python 3.6和Django 2.2版本。我推荐使用虚拟环境来隔离项目依赖python -m venv myenv source myenv/bin/activate # Linux/Mac # 或 myenv\Scripts\activate # Windows pip install django新建一个Django项目和应用django-admin startproject ckeditor_demo cd ckeditor_demo python manage.py startapp blog在settings.py中添加blog应用到INSTALLED_APPSINSTALLED_APPS [ ... blog, ]2.2 安装CKEditor5相关包CKEditor5提供了多种集成方式我们选择通过npm安装前端资源再使用django-ckeditor-5作为后端桥梁npm install ckeditor/ckeditor5-build-classic pip install django-ckeditor-5注意如果你不熟悉前端构建流程也可以直接使用CDN引入CKEditor5但本地安装可以获得更好的版本控制和定制能力。3. CKEditor5配置详解3.1 Django后端配置在settings.py中添加django-ckeditor-5到INSTALLED_APPSINSTALLED_APPS [django_ckeditor_5]然后配置静态文件和媒体文件路径STATIC_URL /static/ STATIC_ROOT os.path.join(BASE_DIR, staticfiles) MEDIA_URL /media/ MEDIA_ROOT os.path.join(BASE_DIR, media)添加CKEditor5的自定义配置CKEDITOR_5_CONFIGS { default: { toolbar: [heading, |, bold, italic, link, bulletedList, numberedList, blockQuote, imageUpload, ], }, }3.2 前端资源集成在项目的base.html模板中引入CKEditor5资源!DOCTYPE html html head titleMy Blog/title script src{% static ckeditor5/build/ckeditor.js %}/script /head body {% block content %}{% endblock %} /body /html如果你使用CDN方式可以直接使用script srchttps://cdn.ckeditor.com/ckeditor5/34.0.0/classic/ckeditor.js/script4. 创建博客模型与表单4.1 文章模型设计在blog/models.py中创建文章模型from django.db import models from django_ckeditor_5.fields import CKEditor5Field class Article(models.Model): title models.CharField(max_length200) content CKEditor5Field(Content, config_namedefault) created_at models.DateTimeField(auto_now_addTrue) updated_at models.DateTimeField(auto_nowTrue) def __str__(self): return self.title注意我们使用了CKEditor5Field而不是普通的TextField这是django-ckeditor-5提供的专用字段类型。4.2 创建文章表单在blog/forms.py中创建表单from django import forms from .models import Article class ArticleForm(forms.ModelForm): class Meta: model Article fields [title, content]5. 视图与URL配置5.1 创建视图函数在blog/views.py中添加创建和显示文章的视图from django.shortcuts import render, redirect from .forms import ArticleForm from .models import Article def create_article(request): if request.method POST: form ArticleForm(request.POST) if form.is_valid(): form.save() return redirect(article_list) else: form ArticleForm() return render(request, blog/create_article.html, {form: form}) def article_list(request): articles Article.objects.all().order_by(-created_at) return render(request, blog/article_list.html, {articles: articles}) def article_detail(request, pk): article Article.objects.get(pkpk) return render(request, blog/article_detail.html, {article: article})5.2 配置URL路由在ckeditor_demo/urls.py中添加from django.contrib import admin from django.urls import path from blog import views urlpatterns [ path(admin/, admin.site.urls), path(articles/, views.article_list, namearticle_list), path(articles/create/, views.create_article, namecreate_article), path(articles/int:pk/, views.article_detail, namearticle_detail), ]6. 模板设计与实现6.1 创建文章模板在templates/blog/create_article.html中{% extends base.html %} {% block content %} h1Create New Article/h1 form methodpost {% csrf_token %} {{ form.media }} {{ form.as_p }} button typesubmitSave/button /form script ClassicEditor .create(document.querySelector(#id_content), { // 可以在这里添加更多CKEditor5配置 }) .catch(error { console.error(error); }); /script {% endblock %}6.2 文章列表模板在templates/blog/article_list.html中{% extends base.html %} {% block content %} h1Articles/h1 ul {% for article in articles %} li a href{% url article_detail article.pk %}{{ article.title }}/a small{{ article.created_at|date:Y-m-d }}/small /li {% endfor %} /ul a href{% url create_article %}Create New Article/a {% endblock %}6.3 文章详情模板在templates/blog/article_detail.html中{% extends base.html %} {% block content %} article h1{{ article.title }}/h1 time{{ article.created_at|date:Y-m-d H:i }}/time div{{ article.content|safe }}/div /article a href{% url article_list %}Back to list/a {% endblock %}重要提示注意在详情页中使用|safe过滤器来渲染HTML内容这是必要的但同时要确保你的内容来源可信以避免XSS攻击。7. 图片上传功能实现7.1 配置图片上传CKEditor5默认支持图片上传但需要额外的后端支持。首先安装必要的依赖pip install pillow然后修改settings.pyCKEDITOR_5_CONFIGS { default: { toolbar: [heading, |, bold, italic, link, bulletedList, numberedList, blockQuote, imageUpload, ], image: { toolbar: [imageTextAlternative, |, imageStyle:alignLeft, imageStyle:alignRight, imageStyle:alignCenter, imageStyle:side, |], styles: [ full, side, alignLeft, alignRight, alignCenter, ], } }, }7.2 创建图片上传视图在blog/views.py中添加from django.http import JsonResponse from django.views.decorators.csrf import csrf_exempt import os from django.core.files.storage import default_storage from django.core.files.base import ContentFile from django.conf import settings csrf_exempt def upload_image(request): if request.method POST and request.FILES.get(upload): upload request.FILES[upload] path os.path.join(uploads, upload.name) saved_path default_storage.save(path, ContentFile(upload.read())) url os.path.join(settings.MEDIA_URL, saved_path) return JsonResponse({url: url}) return JsonResponse({error: Invalid request}, status400)在urls.py中添加路由path(upload/, views.upload_image, nameckeditor_upload),7.3 前端配置修改create_article.html中的CKEditor5初始化代码ClassicEditor .create(document.querySelector(#id_content), { ckfinder: { uploadUrl: /upload/ } }) .catch(error { console.error(error); });8. 高级功能与自定义8.1 自定义工具栏你可以根据需要添加或移除工具栏按钮。例如要添加代码块支持首先安装插件npm install ckeditor/ckeditor5-code-block然后修改配置CKEDITOR_5_CONFIGS { default: { toolbar: [heading, |, bold, italic, link, bulletedList, numberedList, blockQuote, codeBlock, imageUpload, ], codeBlock: { languages: [ {language: python, label: Python}, {language: javascript, label: JavaScript}, {language: html, label: HTML}, {language: css, label: CSS}, ] } }, }8.2 使用自定义构建如果你想进一步定制编辑器可以创建自定义构建创建一个新的npm项目安装CKEditor5源码版本创建自定义配置文件构建并复制到Django的静态文件目录mkdir my-ckeditor5-build cd my-ckeditor5-build npm init -y npm install --save ckeditor/ckeditor5-dev-utils ckeditor/ckeditor5-theme-lark npm install --save ckeditor/ckeditor5-basic-styles ckeditor/ckeditor5-essentials ckeditor/ckeditor5-paragraph创建webpack.config.js和自定义构建脚本最后将构建结果复制到Django的static目录。9. 部署注意事项9.1 静态文件收集在生产环境中记得运行python manage.py collectstatic9.2 媒体文件服务在生产环境中你需要配置Web服务器如Nginx来服务媒体文件。示例Nginx配置location /media/ { alias /path/to/your/project/media/; } location /static/ { alias /path/to/your/project/staticfiles/; }9.3 安全考虑图片上传应该进行安全检查文件类型、大小等考虑使用django-cleanup自动删除未使用的媒体文件对于生产环境应该移除csrf_exempt装饰器使用更安全的方式处理图片上传10. 常见问题解决10.1 编辑器未加载检查静态文件是否正确加载查看页面源代码确保CKEditor5的JS文件路径正确检查浏览器控制台是否有错误10.2 图片上传失败确保MEDIA_ROOT和MEDIA_URL配置正确检查服务器是否有写入权限验证CSRF令牌是否正确处理10.3 内容保存后格式丢失确保在模板中使用|safe过滤器检查是否有多余的HTML转义发生验证模型字段是否正确定义为CKEditor5Field10.4 与其他Django应用冲突检查是否有其他应用也使用了CKEditor的不同版本确保静态文件命名空间不会冲突考虑使用django-ckeditor-5的命名空间功能11. 性能优化建议对于内容较多的页面考虑实现分页使用django-debug-toolbar识别性能瓶颈对文章列表页实现缓存考虑使用CDN分发静态文件和媒体资源对CKEditor5进行自定义构建只包含需要的功能模块12. 扩展思路这个基础实现可以进一步扩展添加文章分类和标签系统实现用户评论功能添加文章搜索功能支持Markdown和富文本双模式编辑实现版本控制和文章修订历史添加文章发布状态草稿、已发布、已归档我在实际项目中发现CKEditor5与Django的集成非常顺畅特别是对于需要频繁内容更新的场景。相比其他富文本编辑器解决方案CKEditor5提供了更好的现代浏览器支持和更简洁的API。 
