说到富文本编辑器Vue项目里在地选择Tinymce的人真不少我也是被它的扩展性吸引的。但前阵子做某知识库后台客户要求用户能直接从本地选择视频传到编辑器里并且要在文章里正常播放。原以为Tinymce自带的媒体插件能搞定结果默认弹窗只支持填视频网址本地文件的按钮根本不存在。最后花了不少时间走了一遍“选文件、传服务器、插入编辑器”的完整链路中间踩了大大小小一堆坑这里完整整理出来。这套方案不依赖某个特定后端核心是Tinymce的file_picker_callback入口加上自己实现的上传逻辑适配Vue 2和Vue 3。文章适合正在用Tinymce做内容系统、需要支持本地视频上传的前端同学也可以作为图片上传的参考只是文件类型过滤和回插参数不同。1. 先搞清楚Tinymce的视频上传逻辑1.1 默认媒体弹窗到底做了什么Tinymce的media插件负责“插入/编辑视频”功能。点工具栏的视频按钮弹出的对话框里只有一个URL输入框让用户填视频链接或者在线视频嵌入代码。它本身不提供“浏览本地文件”的入口这是很多刚接触的人第一个懵的地方。这个设计其实合理编辑器只是一个内容编辑壳子不负责文件存储。所有通过URL引用的资源都假定已经存在于某个可访问的地址上。图片上传之所以“开箱即感受不错”是因为不少项目额外配置了image_list、images_upload_handler之类的钩子文件被传到了自己的对象存储或服务器。而视频资源体积大、接口不同、鉴权复杂Tinymce官方刻意不越权帮你做。所以结论很明确想要在Vue项目里使用Tinymce编辑器自定义本地上传视频必须自己接管文件选择、上传接口调用、URL回插这三个环节。media插件保留但它只负责最终视频标签的渲染和编辑。1.2 file_picker_callback是绕不过去的入口Tinymce在打开媒体对话框时会检查初始化配置里的file_picker_callback。如果存在用户点“插入/编辑媒体”时原本只有URL输入框的界面之外会额外出现一个“从本地选择”类型的能力入口。这个回调接收三个参数callback、value、meta。meta里最关键的是filetype常见取值有image、media、file。当用户是在媒体弹窗里点文件选择meta.filetype就是media。你在这个回调里创建一个隐藏的input[typefile]并触发选择拿到本地文件后执行上传最后把得到的URL通过callback回传给编辑器。需要注意的是这个回调同样会响应图片选择。所以判断meta.filetype时不能写死不能不论什么类型都走视频上传逻辑否则点图片也会弹视频选择框。2. Vue项目里的接入思路与基础配置2.1 为什么推荐封装成独立上传模块我在实际项目里不建议把上传逻辑直接写死在编辑器初始化配置里。一个后台系统的编辑器可能出现在文章发布、活动配置、个人简介等多个页面每个页面都要用视频上传如果逻辑都塞在组件里后期改接口、加校验会非常痛苦。我习惯的拆分方式是把“上传视频”抽成一个单独的JS模块专门负责文件格式校验、大小校验、FormData组装、调用接口、返回URL。编辑器组件里只负责拿到file对象调这个模块再处理回调结果。这样Vue页面代码干净遇到视频上传出问题也能单独测试。这里也涉及一点工程化考虑Tinymce初始化配置是一个普通对象但它内部很多回调函数不是在Vue响应式系统里运行的。如果你在回调里直接访问组件data可能会出现闭包捕获旧值、this指向丢失等问题。把上传逻辑放到外部工具函数里可以避免这些响应式副作用。2.2 在初始化配置里挂上自定义媒体选择器使用tinymce-vue封装组件时核心是init配置。先安装依赖npm install tinymce tinymce/tinymce-vue然后引入需要的插件和主题把file_picker_callback配进去。下面是一个基础骨架后面会逐步补全。import tinymce from tinymce/tinymce import tinymce/themes/silver/theme import tinymce/icons/default import tinymce/plugins/media import tinymce/plugins/link import tinymce/plugins/image import tinymce/plugins/table import tinymce/plugins/lists const initOptions { plugins: media link image table lists, toolbar: media image ..., media_live_embeds: true, file_picker_callback: (callback, value, meta) { // 在这里处理本地视频选择 } }只配置到这里还不行file_picker_callback要做的第一件事就是判断meta.filetype。判断通过后生成文件输入框并模拟点击这是所有自定义上传的基础套路。3. 本地视频上传三步走选文件、传接口、回插编辑器3.1 第一步拿到文件对象并做基础校验无论UI交互是点击按钮还是拖拽上传核心都是拿到一个File对象。我在file_picker_callback里通常直接创建一个input元素设置accept为video/*然后触发click。file_picker_callback: (callback, value, meta) { if (meta.filetype ! media) return const input document.createElement(input) input.type file input.accept video/* input.style.display none document.body.appendChild(input) input.click() input.onchange async () { const file input.files input.files[0] document.body.removeChild(input) if (!file) return // 校验 } }文件校验不要只信扩展名。有些用户会把MP4改名为MP3后台系统容易被传一堆垃圾。校验类型我通常会限定video下的常见MIMEconst allowTypes [ video/mp4, video/webm, video/ogg, video/x-m4v, video/quicktime ] if (!allowTypes.includes(file.type)) { console.warn(不支持该视频格式) return } if (file.size 200 * 1024 * 1024) { console.warn(视频超过200MB请先压缩或改用分片上传) return }大小限制要根据自己后端和服务器带宽来定。如果项目没有对象存储别为了通吃就放开到1GB后端接口超时、服务器磁盘被写满是早晚的事。3.2 第二步把视频通过FormData上传到服务端拿到合法文件后上传方式很多最通用的是FormData加axios。视频文件大要调整超时时间默认30秒肯定不行。import request from /utils/request async function uploadVideo(file, onProgress) { const formData new FormData() formData.append(file, file) formData.append(bizType, article_video) const res await request.post(/upload/video, formData, { headers: { Content-Type: multipart/form-data }, timeout: 600000, onUploadProgress: (e) { if (onProgress) onProgress(e) } }) return res.data.data.url }这里有一个容易踩的细节后端返回的URL可能是相对路径也可能是全路径。全路径通常包含文件域名但如果是内网环境或前端页面部署在CDN之后全路径反而会跨域。我这边一般让后端返回可在前端直接拼接的相对路径或者返回文件唯一ID由前端拼出完整地址。如果项目视频量大建议后端在上传接口里返回视频尺寸、时长、封面截图地址前端一次性存进编辑器数据结构。虽然这一步不是必须但文章列表页需要视频封面时你会感谢当时多存了这些字段。3.3 第三步把上传得到的URL回插给Tinymce上传成功后调用file_picker_callback的第一个参数callback把URL传给编辑器。关键点来了callback不只是一个字符串很多情况下需要同时传视频源信息和展示属性。callback(url, { source: url, poster: coverPoster, width: 100%, height: 400, controls: true })第二个参数里的source表示真实视频地址。如果你只传一个字符串URLTinymce也能插入视频但有些版本会丢失controls、poster等属性。传一个对象更保险。另外要注意callback调用完成后用户可能还会继续编辑这个视频。比如改尺寸Tinymce会重新走file_picker_callback去获取新的视频地址。如果此时回调里没有保留旧值用户会感觉“明明选了视频一改属性怎么丢了”。因此file_picker_callback里的value参数要用起来它是当前已有的视频URL可以在callback里作为默认值回显。4. 我踩过的坑和解决记录4.1 视频文件太大导致接口超时与预览卡顿第一次测试时我选了一个300多MB的MP4前端axios设置的120秒超时结果后端从对接存储到自己服务器花了快两分钟直接超时失败。更麻烦的是即使上传成功用户在编辑器里预览也要从服务器拉整个文件体验非常差。后来我做的调整是三个方向并行。第一前端限制文件大小超过200MB就提示用户先压缩或者走单独的大文件上传页面。第二后端做转码和切片前端拿到的是转码后的标准MP4地址。第三上传接口增加进度条避免用户以为页面卡死。如果你的项目没有转码条件至少要让用户选完文件后有个明确的进度提示。FormData上传要知道进度很容易axios的onUploadProgress就能拿到loaded和total可以画一个简单的进度条或者显示百分比。4.2 二次打开编辑时视频源丢失这个问题最坑现象是第一次插入视频完全正常但保存后再次打开编辑文章视频区域要么是空白要么只有一个链接。排查了后端数据发现HTML里明明有video标签src也在但Tinymce初始化后媒体弹窗里显示不了。原因是Tinymce的media插件对视频的解析依赖data-mce-src、data-mce-poster等自定义属性。如果后端富文本过滤或数据库存储时把这些属性丢了或者前端在服务端渲染时给清洗掉了编辑器就识别不出这个视频。解决方法是保存内容时不要对内容做过于激进的自定义HTML清洗尤其是保留data-*属性。同时初始化编辑器时可以把内容字符串调试打印出来确认video标签是否完整。这个坑通常不是Tinymce的问题而是项目里现成的HTML过滤器太“勤劳”。4.3 视频自动播放和尺寸控制需要额外处理客户希望文章里的视频自动播放结果简单在init配置里设置autoplay属性没用。因为Tinymce的media插件默认不允许所有媒体属性autoplay、playsinline这类属性会被过滤或者只在某个条件下生效。我最后的处理是在保存内容时用正则给video标签补偿属性或者更稳妥一点在初始化时给媒体弹窗的模板补充自定义字段。如果只追求最终显示效果可以在渲染文章详情页时不直接渲染富文本内容而是先处理video标签给每个视频包裹一层容器再设置autoplay。实际项目中我倾向于后者因为编辑器里是否自动播放不重要重要的是文章正式发布后播放器行为可控。编辑器里保留了原始资源和宽高属性阅读页统一处理反而少踩坑。4.4 后端返回视频地址含有特殊字符导致插入错误视频文件名称如果带着中文、空格、#号后端拼接URL时又没有做URL编码src会变成不可用的地址。头一次测的时候文件名是“企业培训 第1讲.mp4”上传成功后端返回的地址里空格直接就成了非法字符视频加载不出来。这个问题解决不复杂但容易被忽略。前端在传给后端时可以强制重命名文件用时间戳加随机串file.name太小众的字符多干脆弃用原名。后端返回时也要确保地址是编码后的至少空格要转成%20中文要做encodeURIComponent。检查时可以手动在浏览器打开后端返回的地址如果404多半是编码问题如果能打开就是前端回插参数的问题。5. 常见问题速查与排查清单5.1 高频问题对照表这里整理了一份我实际遇到过、或者被问过的短视频上传高频问题排查思路基本都在表格里。问题现象可能原因处理办法弹窗里没有文件选择入口file_picker_callback未配置或meta.filetype判断错误检查init配置确认是media类型accept设置成video/*还是能选图片部分浏览器input accept过滤不严格选中后增加file.type白名单校验上传成功但视频黑屏转码后地址失效或视频编码不符合浏览器标准检查播放地址确认后端输出MP4 H.264编辑保存后视频丢失>// utils/videoUpload.js import request from /utils/request const MAX_SIZE 200 * 1024 * 1024 const ACCEPT_TYPES [video/mp4, video/webm, video/ogg, video/x-m4v, video/quicktime] export async function uploadVideo(file, onProgress) { if (!file) throw new Error(没有选择文件) if (file.size MAX_SIZE) { throw new Error(视频大小不能超过200MB) } if (!ACCEPT_TYPES.includes(file.type)) { throw new Error(视频格式不支持请上传MP4或WebM) } const newFileName ${Date.now()}_${(Math.random() * 10000).toFixed(0)}.${file.name.split(.).pop()} const formData new FormData() formData.append(file, new File([file], newFileName, { type: file.type })) const res await request.post(/upload/video, formData, { headers: { Content-Type: multipart/form-data }, timeout: 600000, onUploadProgress: onProgress }) return res.data.data.url }这个封装做了三件重要的事过滤文件、调整超时、重命名文件。其中重命名看起来多余实际上解决了文件原名可能包含中文字符和特殊字符导致的URL编码问题属于花钱买教训后总结出来的。6.2 组件里完整接入TinymceVue组件里我需要同时拿到视频URL、缩略图、上传进度。Tinymce的file_picker_callback只是一个回调函数不能直接触发Vue组件data更新所以不能像平时那样在回调里console一下就当完事。我用了临时变量和事件机制保证组件状态同步。template div editor v-modelcontent :initeditorInit inputhandleInput / div v-ifuploadProgress 0 uploadProgress 100 正在上传视频{{ uploadProgress }}% /div /div /template script import Editor from tinymce/tinymce-vue import { uploadVideo } from /utils/videoUpload export default { components: { Editor }, data() { return { content: , uploadProgress: 0 } }, computed: { editorInit() { return { plugins: media link image tables lists, toolbar: undo redo | styles | bold italic | bullist numlist | media image link | table, file_picker_callback: (callback, value, meta) { if (meta.filetype ! media) return const input document.createElement(input) input.type file input.accept video/* input.style.display none document.body.appendChild(input) input.click() input.onchange async () { const file input.files input.files[0] document.body.removeChild(input) if (!file) return try { const url await uploadVideo(file, (e) { if (e.total 0) { this.uploadProgress Math.round((e.loaded / e.total) * 100) } }) callback(url, { source: url, controls: true, width: 100% }) } catch (err) { console.error(err) this.$message.error(err.message) } finally { this.uploadProgress 0 } } } } } }, methods: { handleInput(val) { this.content val } } } /script这段代码里有一点要特别注意file_picker_callback内部的箭头函数继承了组件实例的this所以我可以在里面直接访问uploadProgress。如果换成普通function这一步就会出错。6.3 几个值得保留的边界处理第一个边界是连续多次打开媒体弹窗。我见过有同事在回调里每次都创建input但不移除页面里累计了一堆隐藏input导致第二次点击没反应。建议每次用完立即清除DOM元素。第二个边界是上传中用户关闭了弹窗。如果用户选择视频后上传还没结束就点了取消有可能出现关闭媒体窗口后进度条还挂在页面上。这个我是在finally里重置uploadProgress同时上传接口本身要支持中断axios可以通过AbortController实现组件销毁时cancel即可。第三个边界是编辑器内容isTrusted校验。有些情况下用户不点击文件输入框而是通过浏览器自动填写或拖拽触发input事件可能来自非用户交互。虽然没有严格必要但为了不让视频上传接口被机器人打建议在onchange里判断event.isTrusted至少记录下来。不过这个看业务部分后台系统需要允许管理员脚本自动上传这里就不做强制限制。7. 写在最后本地视频上传其实是个链路工程单看“Vue项目用Tinymce自定义本地上传视频”很多人以为只是配置一个回调实际上把文件校验、上传接口、回插参数、二次编辑、大文件超时这些问题全部理顺才算真正完成。我最大的体会是不要指望富文本编辑器帮你做资源管理它只负责把用户操作翻译成HTML。你现在如果也在做类似功能建议先拿一个小MP4文件跑通全链路再逐步加上大文件、进度条、封面。视频上传涉及的前后端配合点比图片多不要等联调时再临时补接口字段。最后分享一个小技巧Tinymce配置文件里可以给media插件设置media_filter_html为true这样从外部粘贴的视频HTML会被清洗反而容易丢属性。如果你正常上传没问题只是粘贴视频内容有问题先查这个参数被我当成bug排查了好几个小时。希望这篇文章能帮你少走这段弯路。