Django集成TinyMCE富文本编辑器：安装、配置、图片上传与安全回显

第一次在Django后台里给运营团队配正文编辑时我差点被富文本编辑器的接入给劝退静态资源、工具栏配置、图片上传、CSRF校验、内容转义每一项单独看都不难串在一起就到处都是坑。后来换成TinyMCE并配合django-tinymce折腾了一轮终于稳定下来后台文章的编辑体验总算对得起“后台”两个字。这篇就把TinyMCE在Django里的完整接入过程、配置拆解、图片上传实现、前端回显安全这些内容一次性讲透最后附一份我反复踩坑后整理的问题排查表。适合正在做内容后台、CMS项目或者还在表单编辑区用textarea硬扛的人。1. 为什么是TinyMCE富文本选型前的三个判断1.1 谁在用先分清使用人群再谈技术选型后台里需要“大段正文编辑”的地方基本只有两条路接入富文本编辑器或者用Markdown编辑器。我见过不少项目在这上面选错了方向后果往往是运营同事每天都在问“为什么预览要单独点开”“这个语法符号是干嘛的”最后干脆把HTML源码复制进来粘贴然后排版就乱了。我的习惯是先看使用者。如果后台是给内容编辑、运营、客服这类非技术角色用的几乎无脑选富文本编辑器。他们习惯Word那套交互选中文字加粗、插图片、调对齐、做表格所见即所得不需要理解任何语法。而如果后台是给开发者写技术文档、接口说明用的Markdown反而效率更高毕竟是程序员自己维护的内容。1.2 为什么TinyMCE更省心富文本编辑器本身选择也不算多主流就那几个。对比下来TinyMCE对我最大的吸引力是它在Django生态里有一个相对完整、维护节奏稳定的桥接包django-tinymce。装上之后模型字段可以直接用HTMLFieldDjango管理后台和ModelForm不需要额外写前端代码就能自动渲染出编辑器这对做后台管理系统来说太省事了。另一个理由是TinyMCE足够老牌。从TinyMCE 4到6同一套核心API的变化相对可控网上资料多、插件全。遇到问题搜索时几乎都能找到对应的案例这个优势在开发调试时你才能体会到。相比之下如果自己基于contenteditable写一个编辑器光是光标定位、撤销重做、复制粘贴的样式清理这三件事就够折腾几个星期生产环境真不建议自研。2. 十分钟跑通安装配置与模型接入2.1 安装并注册依赖先说明一下版本基线下面内容以django-tinymce 4.x配合TinyMCE 6为参考。如果你项目里还在用老版本核心概念相通只是部分widget写法有差异。安装很简单pip install django-tinymce然后打开settings.py把应用注册进去INSTALLED_APPS [ # ... tinymce, ]这一步不做的话后续编辑器静态资源和HTMLField都找不到对应的模型映射会直接给你报错。同时检查一下MEDIA相关配置。Django项目里上传前通常都需要这个否则后面图片上传功能没法正常落盘MEDIA_URL /media/ MEDIA_ROOT BASE_DIR / media如果是开发环境调试还需要在urls.py里把media路由暴露出来from django.conf import settings from django.conf.urls.static import static urlpatterns [ # ... ] if settings.DEBUG: urlpatterns static(settings.MEDIA_URL, document_rootsettings.MEDIA_ROOT)2.2 一份可以直接抄的基础配置编辑器的界面、插件、菜单栏行为都通过TINYMCE_DEFAULT_CONFIG配置。下面这份是我项目里常用的基础配置先贴出来TINYMCE_DEFAULT_CONFIG { height: 500px, width: 100%, menubar: file edit view insert format tools table help, plugins: advlist autolink lists link image charmap preview anchor searchreplace visualblocks code codesample fullscreen insertdatetime media table paste code help wordcount, toolbar: undo redo | blocks | bold italic forecolor | alignleft aligncenter alignright alignjustify | bullist numlist outdent indent | removeformat | help, custom_undo_redo_levels: 10, }先说几个关键项的理解方式。height和width控制编辑区尺寸width设成100%在多屏下体验更友好。menubar是顶部菜单栏plugins声明需要启用的插件toolbar则决定工具栏上具体显示哪些按钮。注意一个容易踩的坑插件的名称必须和toolbar里出现的按钮名称一一对应比如toolbar里写了codesampleplugins里就必须有codesample否则那个按钮会神秘消失。这份配置不是一次到位的建议先跑通再按业务裁剪。2.3 用HTMLField替换普通字段模型字段的写法是接入的关键。把正文从普通的TextField或CharField换成HTMLFieldfrom django.db import models from tinymce.models import HTMLField class Article(models.Model): title models.CharField(标题, max_length200) content HTMLField(正文, nullTrue, blankTrue) created_at models.DateTimeField(auto_now_addTrue) def __str__(self): return self.titleHTMLField本身继承了TextField数据库层面和普通TextField没有本质区别差别在表单渲染这一层Django创建表单字段时如果识别到这个字段来自HTMLField会自动返回一个TinyMCE编辑器widget。所以你不用在forms.py里做任何额外处理注册到admin后打开文章编辑页正文区域就直接是富文本编辑器from django.contrib import admin from .models import Article admin.register(Article) class ArticleAdmin(admin.ModelAdmin): list_display (title, created_at)这一点对做后台CMS尤其友好运营人员看到的就是一个类似Word的编辑区域而不是一个textarea。2.4 编辑器替换textarea的底层逻辑理解TinyMCE的替换机制能帮你排查掉一半的接入问题。整个流程是这样的Django表单渲染时widget最终输出的是一个普通textarea标签这个textarea保留了自己的name属性和id比如id_content。页面加载时TinyMCE的JavaScript会扫描页面找到匹配selector的textarea把它隐藏掉然后在这个位置创建一个可编辑的iframe区域。用户在编辑区里的每一次输入都会被JavaScript同步写回背后的textarea值。也就是说表单提交时后端拿到的仍然是textarea的value只是这个value变成了包含HTML标签的字符串。这个机制解释了两个常见现象一编辑器没显示时往往不是Django的问题而是TinyMCE的JavaScript没有成功找到textarea二内容能正常保存就说明textarea的表单数据链路没被破坏问题大概率出在回显或过滤环节。3. 核心配置逐项拆解3.1 工具栏按钮顺序就是界面顺序工具栏配置看起来像一串字符串实际上就是你在界面上看到的按钮排列顺序。用竖线分隔的就是分组间隔。比如下面这段配置toolbar: ( undo redo | blocks | bold italic underline | forecolor backcolor | alignleft aligncenter alignright alignjustify | removeformat bullist numlist | link image media table | codesample | fullscreen preview code )每一项的含义要心里有数undo redo撤销和重做编辑刚需。blocks段落和标题样式的下拉框维护文章语义层级就靠它。bold italic underline加粗、斜体、下划线。forecolor backcolor文字颜色、背景色。设置后可让编辑自由调文字高亮。alignleft等四个左对齐、居中、右对齐、两端对齐。bullist numlist无序列表、有序列表。link image media table插入链接、图片、媒体文件和表格。codesample插入代码示例适合做技术文章。removeformat一键清除格式强烈建议保留。复制过来的内容经常带着一堆无效样式编辑点一下这个按钮就清爽了。preview code预览和源码模式。源码模式面向技术型编辑普通人可以不用。配置的核心原则是“按使用人群裁剪”。如果是给运营后台用保留排版、列表、图片这几个核心就够了technical向的按钮一律隐藏减少误触概率。如果是给技术文档后台用blocks和codesample就必须保留。3.2 插件清单哪些建议保留插件这里有个经验初期配置不需要太克制先把常用的都声明上确认功能跑通后再根据实际使用情况裁剪。base配置里的插件我逐个说明一下定位advlist可以给列表选择更多符号样式autolink负责把粘贴的URL自动转成可点击链接lists是列表功能的底层支持。link、image、media这三个是主流内容类型的插入入口图、文、视频都靠它们。charmap提供特殊字符面板做专业排版时会用到。anchor用来插入锚点preview支持整篇预览searchreplace是查找替换。visualblocks在编辑时显示块级标签轮廓对调试排版很有用但普通人看着反而乱。code是HTML源码编辑入口codesample允许插入代码片段。fullscreen一键全屏insertdatetime插入当前时间table做表格paste负责粘贴时清理Word等外部格式wordcount在状态栏显示字数统计。我特别想多说一句paste。编辑从Word或网页里复制一段文字进来结果带上一大串inline样式这是富文本编辑器里最高频的投诉点。TinyMCE的paste插件专门处理这种情况可以过滤掉大部分无意义样式。如果发现粘贴后样式依然乱可以再叠加配置paste_remove_styles_if_webkit: True, paste_remove_spans: True,这两项能砍掉大部分从浏览器复制进来的残留span和style。3.3 界面语言切换默认情况下编辑器界面是英文的对大多数后台使用者不友好。配置语言很简单language: zh_CN有两点要注意。第一语言代码不一定总是zh_CN有些版本使用zh-CN要看语言包文件名对应关系。第二django-tinymce自带TinyMCE的完整静态文件通常已经包含多语言包直接配置就能生效但如果你是从官网下载的精简版可能没有中文包需要在静态目录下放一个语言文件并指定language_url指向它否则配置了language也不生效。3.4 图片上传从零实现图片上传是富文本编辑器里避开不开的一道坎。不接上传功能的话用户插图片只有两种结果填外链地址或者直接把base64编码塞进正文里。base64方案会让整篇文章体积膨胀好几倍数据库里存的内容又长又没法复用属于必须拒绝的方案。正确做法是后端提供一个接收图片的接口编辑器通过接口把文件存到存储目录然后返回一个可访问的URL。先写接收上传的视图# views.py import os from uuid import uuid4 from django.core.files.storage import default_storage from django.http import HttpResponseNotAllowed, JsonResponse ALLOWED_EXT {.jpg, .jpeg, .png, .gif, .webp} def editor_upload(request): if request.method ! POST: return HttpResponseNotAllowed([POST]) image request.FILES.get(file) if image is None: return JsonResponse({error: 没有收到文件}, status400) ext os.path.splitext(image.name)[1].lower() if ext not in ALLOWED_EXT: return JsonResponse({error: 不支持的文件格式}, status400) if image.size 2 * 1024 * 1024: return JsonResponse({error: 图片大小不能超过2MB}, status400) saved_path default_storage.save(feditor/{uuid4().hex}{ext}, image) return JsonResponse({location: default_storage.url(saved_path)})路由注册# urls.py from django.urls import path from . import views urlpatterns [ path(editor/upload/, views.editor_upload, nameeditor_upload), ]然后把这个接口地址配置到编辑器TINYMCE_DEFAULT_CONFIG.update({ images_upload_url: /editor/upload/, automatic_uploads: True, })这里有个DERDami核心要注意TinyMCE期望上传接口返回的JSON里有一个location字段内容就是图片的访问URL。如果接口返回的是url字段或者别的命名编辑器会直接报“无法处理图片上传请求”。还有Django的CSRF问题。默认情况下Django对POST请求做CSRF校验TinyMCE自动发起的图片上传请求默认不会携带csrftoken请求头所以在内网后台或者只给登录用户使用的情况下可以给这个视图加csrf_exempt省得绕前端。如果你面向的是正式对外系统且安全要求较高就得用自定义images_upload_handler在前端手动带上X-CSRFToken请求头类似于function getCookie(name) { let cookieValue null; if (document.cookie document.cookie ! ) { const cookies document.cookie.split(;); for (let i 0; i cookies.length; i) { const cookie cookies[i].trim(); if (cookie.substring(0, name.length 1) name ) { cookieValue decodeURIComponent(cookie.substring(name.length 1)); break; } } } return cookieValue; } function uploadHandler(blobInfo) { return new Promise((resolve, reject) { const fd new FormData(); fd.append(file, blobInfo.blob(), blobInfo.filename()); fetch(/editor/upload/, { method: POST, body: fd, headers: { X-CSRFToken: getCookie(csrftoken) }, }) .then((res) res.json()) .then((data) { if (!data.location) { reject(data.error || 上传失败); return; } resolve(data.location); }) .catch(() reject(上传失败)); }); }这个handler函数没法直接写进TINYMCE_DEFAULT_CONFIG因为Python配置最终要序列化给前端函数传不过去。如果坚持要在django-tinymce的自动渲染机制里用handler需要自定义widget去拼接这段JavaScript比较绕。我的实际建议是项目里如果只有一个页面用富文本直接用第6章说到的原生手动集成方式把tinymce.init写在模板里反而清晰可控。4. 回显、样式与安全4.1 模板里为什么必须safe内容保存到数据库时其实就是一段包含HTML标签的字符串。到了前端展示环节Django模板默认会转义变量里的HTML字符所以直接写div{{ article.content }}/div你会看到页面上把p标题/p这样的标签原样打印出来而不是渲染成段落。正确写法是加safe过滤器div classarticle-content{{ article.content|safe }}/divsafe的含义是告诉Django这段字符串可以当作HTML输出。这个过滤器本身不危险危险的是你对内容来源的信任程度。如果保存时没做任何过滤用户完全可以在编辑器里粘贴一段带script标签的内容或者构造一个带onerror属性的图片标签前端safe之后就会直接执行。所以安全的关键不在safe而在入库之前的内容清洗。4.2 用白名单清洗保存内容清洗富文本内容我的首选是bleach这个库。它不是黑名单拦截而是白名单机制只允许你明确指定的标签、属性和协议存在其余的一律剔除。这种方式对富文本来说更可靠因为你很难穷举所有危险写法但你可以明确项目里需要哪些合法标签。安装pip install bleach清洗函数可以这样写import bleach ALLOWED_TAGS [ p, br, strong, em, u, del, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote, pre, code, span, div, a, img, table, thead, tbody, tfoot, tr, th, td, iframe, video, source, hr, ] ALLOWED_ATTRIBUTES { a: [href, title, target, rel], img: [src, alt, title, width, height], code: [class], span: [style], div: [style], td: [colspan, rowspan], th: [colspan, rowspan], iframe: [src, width, height], video: [src, controls, width, height, muted], source: [src, type], } ALLOWED_PROTOCOLS [http, https, mailto, tel] def clean_html(raw_html: str) - str: return bleach.clean( raw_html, tagsALLOWED_TAGS, attributesALLOWED_ATTRIBUTES, protocolsALLOWED_PROTOCOLS, stripTrue, )这段代码的核心思路是标签白名单覆盖了正文排版需要的基本元素属性白名单只给文本链接、图片、表格和少数媒体标签放开必要属性。protocols限制链接可用的协议像javascript:这种协议会直接被移除。stripTrue表示不在白名单里的内容不是报错而是直接删掉体验上更温和。清洗的调用时机我通常放在ModelForm的clean方法里而不是用Signal或者model.save覆盖。因为表单层能拿到用户提交的原始值清洗后返回给字段后续保存、admin、API共用一套入口逻辑不会漏from django import forms from .models import Article class ArticleForm(forms.ModelForm): class Meta: model Article fields [title, content] def clean_content(self): raw self.cleaned_data.get(content, ) if not raw: return raw return clean_html(raw)4.3 href和iframe的安全边界清洗时除了标签本身还要注意两个容易忽视的边界。第一个是链接协议。用户完全可以构造一个a hrefjavascript:alert(x)点击/a。bleach的protocols参数就可以拦掉这类。上面代码里我把协议限制在http、https、mailto、tel项目里如果还有微信、支付宝之类的自定义协议可以继续加白名单原则是不认识的一律不放行。第二个是iframe。后台文章有时需要插入视频iframe如果iframe允许出现在白名单里那么src属性就必须做域名级别的限制。比较稳妥的做法是在清洗逻辑里单独拦截只允许指定的几个视频平台域名存活其他一律删掉src。不要图省事把所有iframe的src都放开否则等于给钓鱼页面开了绿灯。5. 高频问题排查实录5.1 编辑器没出现的定位顺序这是接入TinyMCE之后被问得最多的问题页面上就是一个普普通通的textarea编辑器完全没出来。我的排查顺序是这样的。先打开浏览器开发者工具看网络请求确认tinymce.min.js有没有真的被加载很多人第一步就卡在这里静态文件没collect或路径不对。接着确认页面里的textarea有没有id以及TinyMCE初始化逻辑里selector是否匹配上了这个id。如果selector写错了就算JS加载成功也找不到目标。再检查INSTALLED_APPS里有没有注册tinymce应用以及模型字段是否真的用了HTMLField。还有一个隐蔽情况项目里如果有老的模板手动加载过一版TinyMCE然后又引入了django-tinymce的自动初始化两个版本同时存在时编辑器区域会闪烁甚至干脆不出现在预期位置。解决办法是统一加载链路老的手动加载脚本和新包的初始化脚本只保留一套。5.2 图片上传失败的常见组合关于图片上传的坑我整理了一份速查表下面这些情况我都真实遇到过现象可能原因处理方式上传接口返回400CSRF校验失败内网后台可加csrf_exempt正式环境用前端handler带csrf token上传成功但图片显示404MEDIA_ROOT或MEDIA_URL没配置或开发环境没暴露media路由配置MEDIA相关设置并在urls.py中挂载static()上传图片后编辑器弹“无法处理该图片上传请求”接口返回JSON字段不是location确认返回格式为{location: 图片URL}上传大图被服务器拒收后端设置了大小限制同步调整前端提示和后端限制值上传文件名是中文导致存储异常部分存储后端对中文文件名兼容不好用uuid重命名保存参考上方视图代码5.3 保存后格式和样式丢失内容在编辑器里看着好好的保存后到前端一看就乱了这类问题通常有两个来源。第一数据库字段类型不对。如果当初用的是CharField并且给了max_length200保存时Django会把超长内容截断整段HTML结尾断在半截标签里前端自然渲染错乱。正确选择是TextField或者继承TextField的HTMLField不设置max_length或者设置一个足够大的容量。第二回显时没有safe。前面说过的转义问题模板输出时看到的是HTML源码而不是排版效果这不算内容丢失是渲染方式不对。还有一种情况是保存前清洗逻辑过于激进比如白名单里没有p标签那全文的段落结构都会被删掉变成纯文本。遇到这类问题先把清洗函数临时关掉看是否恢复正常再逐步收缩白名单定位罪魁祸首。6. 扩展与我的固定做法6.1 不想用包时的手动集成django-tinymce虽然好用但它封装了一层初始化逻辑遇到自定义handler或定制化场景时会有点绕。如果项目里只有一个编辑器我反而推荐手动集成完全可控。把TinyMCE的静态文件放到static目录下模板里直接初始化script src{% static app/tinymce/tinymce.min.js %}/script script tinymce.init({ selector: #id_content, height: 500px, plugins: link image code table lists codesample, toolbar: undo redo | blocks | bold italic | bullist numlist | link image table | code, }); /script表单字段不需要HTMLField普通Textarea就行模板里能保证textarea的id不变就一切好说。这种方式的好处是TinyMCE版本完全自己掌控上传handler、语言包、工具栏配置都能直接写在init参数里不用猜封装层做了什么。代价是每个用到的页面都要写一段init脚本页面多了比较啰嗦。6.2 代码高亮和样式统一技术类后台通常还需要在正文里插入代码块。TinyMCE的codesample插件负责编辑端的代码插入体验输出的是带classlanguage-python之类标记的pre标签。前端配合highlight.js或者Prism就能实现高亮link relstylesheet href{% static highlight/styles/atom-one-light.min.css %} script src{% static highlight/highlight.min.js %}/script scripthljs.highlightAll();/script这块有两个经验。一是编辑器里的代码样式和前端展示样式尽量用同一套CSS否则编辑时看到的效果和发布后的效果是两张脸。二是codesample的语言标签一般能直接被highlight.js识别但如果发现某篇文章的代码块没有高亮可以先看生成出来的pre标签class是否准确再检查前端CSS有没有被自己写的全局样式覆盖掉。6.3 空内容清理的小技巧最后分享一个我自己踩过多次的小细节。编辑在富文本里删空所有文字后提交的内容往往不是空字符串而是一段pnbsp;/p。这个值存进数据库后前端渲染时会出现一个莫名的空段落占位又难看。在清洗逻辑里顺手处理掉import re def clean_html(raw_html: str) - str: cleaned bleach.clean( raw_html, tagsALLOWED_TAGS, attributesALLOWED_ATTRIBUTES, protocolsALLOWED_PROTOCOLS, stripTrue, ) # 内容只剩空白符或空标签时统一返回空字符串 text re.sub(r[^], , cleaned).strip() if not text: return return cleaned现在我的项目里基本固定一套组合TinyMCE HTMLField bleach清洗 自建图片上传接口。编辑体验交给TinyMCE安全防线交给白名单机制存储走default_storage将来要换对象存储时项目代码不用动。如果你正在给Django后台接富文本照着这套流程跑通一次再按业务需求把工具栏和插件裁减到合适程度就好。最后补一句个人体会不要一上来就试图把每个插件、每个菜单栏都调得完美先让编辑器能用起来再根据真实用户反馈一点一点加维度比自己闷头配置高效得多。