企业官网建设流程全解析

做后台系统的时候，几乎每个内容编辑模块都离不开富文本编辑器。最近我在某个内容管理项目里就用了 wangeditor 作为编辑器，需求列表里有一项写得很简单：“支持图片和视频上传”。但真正动手才发现，这几个字背后藏着不少工作：默认编辑器插图片是转成 base64，内容一多数据库分分钟被塞爆；视频上传更是要自己搭一套接口；更别提 token 鉴权、跨域、回调格式这些坑。这篇文章就把我从零配置 wangeditor 图片和视频上传的完整过程整理一遍，包括前端配置、后端接口约定、常见报错和排查方法。不管你是前端、全栈，还是偶尔需要改后台的运维，照着本文的思路都能搞定。

1. 项目概述：先搞清楚“支持图片和视频上传”到底要做什么

1.1 标题背后真正要解决的事

很多第一次接触富文本编辑器的人，拿到 wangeditor 会觉得很奇怪：明明工具栏里有“图片”“视频”按钮，点开也能选文件，为什么还要单独做“上传”配置？这里的关键在于编辑器的默认行为。

wangeditor 默认处理图片的方式是 base64 编码。也就是说，你选一张图，编辑器的 JavaScript 会把图片二进制数据转成一段长字符串，直接塞进<img src="data:image/png;base64,xxxxxx">里。这个方案在本地演示、写个简单 demo 是完全没问题的，但在真实业务里就是隐患：

• 一张 2MB 的图片转成 base64 后大概变成 2.7MB，编辑器内容字段会以这个体积存进数据库；
• 内容列表接口如果直接返回正文，每次查询都要搬运大量无用字符串；
• 插入视频文件时，浏览器基本不会给你 base64 内联方案，因为视频体积通常几十 MB 甚至更大，内存直接爆掉。

所以标题里“支持图片和视频上传”真正要解决的事是：把用户选择的文件从前端上传到我们自己的服务器（或者对象存储/CDN），编辑器里只插入一个可以公开访问的 URL。这样编辑器内容体积小、加载快，文件也便于统一管理和清理。

1.2 适用场景与基本实现思路

这个需求一般在以下场景里出现：

• 内容管理后台（CMS）的新闻编辑页、文章发布页；
• 运营系统里的活动公告、图文编辑工具；
• 带有素材库功能的定制化后台系统，需要把图片、视频统一归档。

实现思路并不复杂，核心就三步：

1. 前端给 wangeditor 配置上传接口地址，告诉它“用户选了文件之后，往这个地址发请求”；
2. 后端写一个接收文件的接口，保存文件，返回规定格式的 JSON；
3. 前端拿到 JSON 里的 URL，把图片或视频标签插入编辑器正文。

听着简单，实际踩坑的都在第二步的“规定格式”和前后端之间的鉴权、跨域上。下面我从机制讲起，再给完整可复制的配置。

2. 摸清 wangeditor 的上传机制：默认行为与可扩展点

2.1 内置的图片插入与视频插入逻辑

先以 wangeditor v5（后面代码都基于 v5，如果你还在用 v4，配置项名称有很大差别，不要硬套）为例说默认行为。

打开工具栏的“图片”按钮，里面有两个 tab：一个是“从图片地址插入”，另一个是“上传图片”。如果你只是配置了编辑器最基本的初始化，没有设置uploadImage，那么“上传图片”这个 tab 走的是 base64 内联逻辑。选中文件后，图片会以 data URL 的形式直接显示，一旦提交表单，数据库中存储的就是那一大串编码。

视频按钮也是类似的 UI，分成“网络视频”和“上传视频”。网络视频就是给一个https://...的地址，编辑器直接插入<video src="...">；上传视频在未配置时，大概率是点击后没有响应或者报错。因为富文本编辑器在纯前端环境里，不可能自己把文件送到某个地方去，上传这个动作必须后端配合。

所以，凡是看到“某某编辑器支持图片和视频上传”这种需求描述，第一件事就是去查对应版本的上传配置 API，然后规划后端接口，而不是去翻工具栏按钮该怎么调出来。按钮本来就存在，缺的是让它工作的“管道”。

2.2 官方预留的上传配置入口

wangeditor v5 的上传能力集中在editorConfig里，两个核心对象：

• uploadImage：图片上传配置；
• uploadVideo：视频上传配置。

两者都支持这些关键字段：

配置在初始化编辑器时写进config即可。

2.3 网络视频与上传视频的差异

很多没仔细看文档的开发者会问：“我已经配了视频上传，为什么用户还能填网络视频？” 这是两个不同的功能入口，不是一个开关控制的。

工具栏的视频菜单里有“网络视频”和“上传视频”两个选项：

• 网络视频适合插入已有的公开视频地址，比如产品演示链接、外部视频文件的直链；
• 上传视频才是把本地文件发到你的服务器。

如果你不想让用户随便填外部地址，可以拿到工具栏实例后，通过toolbarConfig.excludeKeys排除掉“视频”菜单里的某个 tab，或者干脆从insertKeys里重新组织菜单顺序。不过大多数业务场景下，两个入口同时保留反而更灵活，我建议第一版都放着，后续根据运营反馈再决定要不要收。

3. 实操：从零配置图片上传，完整对接流程

3.1 前端配置 uploadImage 的完整代码

先看一段实际能跑的初始化代码。假设项目已经通过 npm 装好了@wangeditor/editor：

import { createEditor, createToolbar } from '@wangeditor/editor' const editorConfig = { placeholder: '请输入正文...', // 图片上传相关配置 uploadImage: { server: '/api/upload/image', fieldName: 'file', maxFileSize: 5 * 1024 * 1024, // 5MB，单位是字节 allowedFileTypes: ['image/jpeg', 'image/png', 'image/gif', 'image/webp'], // 自定义插入，明确告诉编辑器“把响应里的 url 插进正文” customInsert(res, insertFn) { if (res.errno === 0) { const { url, alt = '', href = '' } = res.data insertFn(url, alt, href) } }, }, } const editor = createEditor({ selector: '#editor-container', html: '<p>初始内容</p>', config: editorConfig, mode: 'default', // 或者 'simple' }) const toolbar = createToolbar({ editor, selector: '#toolbar-container', config: {}, })

几个地方要解释：

• selector指向一个真实存在的 DOM 节点，编辑器会挂载到这个节点上；
• maxFileSize的单位是字节，不是 KB 也不是 MB。如果你想限制 2MB，那就写2 * 1024 * 1024，不要直接写'2MB'之类；
• allowedFileTypes是 MIME 类型白名单，注意图片的image/pjpeg在部分浏览器里会被识别成image/jpeg，最好后端也按这套类型校验；
• customInsert为什么会存在？因为 wangeditor 内置逻辑只认errno和data.url，但有些后端是别的系统写的，返回结构可能不同，这时你可以在customInsert里做一层适配，把后端字段翻译成编辑器想要的。

完成这些配置后，用户在编辑器里点“上传图片”，wangeditor 会自动把文件 POST 到server，请求体是multipart/form-data，文件字段名就是fieldName。

3.2 后端接口的请求与响应硬性约定

前端配置好了，后端接口返回格式不对，上传依然会失败。这是 wangeditor 对接里最常踩的坑。先记住一个响应约定：

// 成功 { "errno": 0, "data": { "url": "https://cdn.example.com/uploads/xxx.jpg", "alt": "", "href": "" } } // 失败 { "errno": 1, "message": "文件超出大小限制" }

errno必须是数字 0 表示成功，非 0 表示失败。很多后端同学喜欢返回{ code: 0, data: ... }或者{ success: true, result: ... }，这在别的场景没问题，但在这里编辑器不认识，它只会往控制台报“上传失败”。

下面给一个 Node.js + Express + Multer 的示例接口，覆盖图片和视频两种上传，字段名用file，跟前面前端fieldName保持一致：

const express = require('express') const multer = require('multer') const path = require('path') const crypto = require('crypto') const fs = require('fs') const app = express() const uploadDir = path.join(__dirname, 'uploads') if (!fs.existsSync(uploadDir)) { fs.mkdirSync(uploadDir) } const storage = multer.diskStorage({ destination(req, file, cb) { cb(null, uploadDir) }, filename(req, file, cb) { // 用随机文件名，避免中文名和特殊字符带来的问题 const ext = path.extname(file.originalname).toLowerCase() const name = crypto.randomBytes(16).toString('hex') cb(null, `${name}${ext}`) }, }) const upload = multer({ storage, limits: { fileSize: 100 * 1024 * 1024, // 服务端限制最大 100MB }, fileFilter(req, file, cb) { const isImage = file.mimetype.startsWith('image/') const isVideo = file.mimetype.startsWith('video/') if (isImage || isVideo) { cb(null, true) } else { cb(new Error('invalid file type')) } }, }) app.post('/api/upload/image', upload.single('file'), (req, res) => { if (!req.file) { return res.json({ errno: 1, message: '没有接收到文件' }) } // 实际项目中这里应该返回可访问的完整 URL const url = `https://cdn.example.com/uploads/${req.file.filename}` res.json({ errno: 0, data: { url, alt: req.body.alt || '', href: req.body.href || '', }, }) }) app.post('/api/upload/video', upload.single('file'), (req, res) => { if (!req.file) { return res.json({ errno: 1, message: '没有接收到文件' }) } const url = `https://cdn.example.com/uploads/${req.file.filename}` res.json({ errno: 0, data: { url, }, }) }) app.listen(3000)

这个后端示例里我故意做了几个细节：

• 文件名用了随机数，不保留用户原始文件名，防止路径穿越和重名覆盖；
• 文件扩展名用path.extname(file.originalname).toLowerCase()从原始名里取，但不信任它作为唯一校验，真正的类型校验交给了fileFilter里的 MIME 检查；
• 返回的 URL 中的域名只是一个占位符。实际项目里，如果你没有 CDN，那么应该是http://服务器IP:端口/uploads/文件名，并且需要把静态目录通过app.use('/uploads', express.static(uploadDir))暴露出来。

上面前端代码我故意没有处理上传失败时的 toast 提示，因为每个人用的 UI 库都不一样，留给你自己补。但排查时记得：上传失败时，浏览器 Network 面板里能看到实际返回，这是最直接的排查入口。

3.3 携带鉴权信息的三条可行路线

后台系统几乎都有登录鉴权。上传接口是 POST 请求，你不能让它裸奔，所以携带 token 是必须的。wangeditor 内置上传逻辑里，能不能直接配 headers？在 v5 中我没有找到像 v4 时代那种简单粗暴的uploadImgHeaders配置，但有三条路是可行的。

第一，最保守的方案：用customUpload把上传逻辑完全接管。你自己发请求，想带什么 header、想走什么拦截器都随意：

const token = localStorage.getItem('token') uploadImage: { customUpload(file, insertFn) { const formData = new FormData() formData.append('file', file) fetch('/api/upload/image', { method: 'POST', headers: { Authorization: `Bearer ${token}`, }, // 注意：不要手动设置 Content-Type， // fetch 会根据 FormData 自动生成带 boundary 的 multipart 请求头 body: formData, }) .then((res) => res.json()) .then((res) => { if (res.errno === 0) { insertFn(res.data.url, res.data.alt || '', res.data.href || '') } else { console.error(res.message) } }) .catch((err) => { console.error(err) }) }, }

这里如果你用 axios，就更简单了，可以复用你的请求拦截器里自动注入 token 的逻辑：

uploadImage: { customUpload(file, insertFn) { const formData = new FormData() formData.append('file', file) axios.post('/api/upload/image', formData) .then((response) => { const res = response.data if (res.errno === 0) { insertFn(res.data.url, res.data.alt, res.data.href) } }) }, }

第二，如果后端用 JWT 并且允许在请求参数里带 token，某些项目会把 token 放到 URL query 或者表单字段里，比如：

POST /api/upload/image?token=xxxx

这种方式绕开了自定义上传，但安全性差一些，token 容易出现在日志里，不建议生产环境用。

第三，后端做白名单或一次性签名 URL。图片服务器本身有防盗链需求的话，可以让后端生成带签名的上传地址，前端拿到签名地址后直接上传。这种玩法更偏基建，一般有独立文件服务时才会用。

我的建议是：项目里如果已经有 axios 封装，就优先走customUpload，代码量少，逻辑直观，还能顺手做上传进度条。

3.4 Vue / React 里的组件封装要点

如果你是在 Vue 或 React 项目里用 wangeditor，我建议直接用官方提供的框架组件，而不是手动管理 editor 实例。

Vue 3 示例：

<template> <div> <Toolbar :editor="editorRef" :defaultConfig="toolbarConfig" /> <Editor v-model="valueHtml" :defaultConfig="editorConfig" mode="default" @onCreated="handleCreated" /> </div> </template> <script setup> import '@wangeditor/editor/dist/css/style.css' import { Editor, Toolbar } from '@wangeditor/editor-for-vue' import { shallowRef } from 'vue' const editorRef = shallowRef() const editorConfig = { placeholder: '请输入正文...', uploadImage: { server: '/api/upload/image', fieldName: 'file', }, uploadVideo: { server: '/api/upload/video', fieldName: 'file', }, } const handleCreated = (editor) => { editorRef.value = editor } </script>

几个关键点：

• editor实例不要用普通ref存，用shallowRef，否则 Vue 的响应式代理会把 editor 内部复杂的对象全部处理一遍，轻则性能下降，重则导致编辑器行为异常；
• 组件卸载时，要记得调用editor.destroy()，官方 for-vue 组件在生命周期结束时会自动处理，但如果你手动创建编辑器，就必须自己清理；
• v-model绑定的是 HTML 字符串，提交表单前可以用editor.getHtml()获取最终内容，其中包含<img src="...">和<video src="...">标签。

4. 实操：视频上传配置与场景化改造

4.1 基础视频上传配置与接口对接

视频上传的配置和图片几乎一样，只是字段名换了。在editorConfig里加上：

const editorConfig = { uploadImage: { // ...上面的图片配置 }, uploadVideo: { server: '/api/upload/video', fieldName: 'file', maxFileSize: 100 * 1024 * 1024, // 100MB，按实际业务调整 allowedFileTypes: ['video/mp4', 'video/webm', 'video/ogg'], // 同样的自定义插入逻辑 customInsert(res, insertFn) { if (res.errno === 0) { insertFn(res.data.url) } }, }, }

视频接口的返回格式和图片接口一致，成功时res.data.url就是视频地址。wangeditor 会将地址渲染成类似这样的 HTML（细节会带一些自定义属性，这里只展示核心结构）：

<video src="https://cdn.example.com/uploads/xxxxx.mp4"></video>

这里有一个隐藏要求：视频地址必须能被浏览器直接播放。也就是说，后端返回的 URL 对应的静态资源服务，必须支持 HTTP Range 请求。浏览器播放<video>时，会分段拉取数据，而不会一次性把整个文件加载到内存。如果你用 Nginx 托管上传目录，默认是支持 Range 的；如果用某些不支持 Range 的开发服务器调试，可能会出现视频拖不动进度条、或者根本播不了的情况。

4.2 限制上传大小与类型：前后端别各顾各的

视频文件大，限制条件就特别需要提前规划。前端限制只是体验上的拦截，防不了恶意请求，后端才是最后一道防线。

前端配置maxFileSize后，超过大小的文件在选择时就会被拦截，并弹出默认的错误提示。这里要注意：不同浏览器的文件对话框大小显示单位不一样，有的是 KB，有的是 MB，你在提示信息里写清楚“视频最大 100MB”就好。

后端要做的事情更多：

• Nginx 层：如果你在 Nginx 后面，默认client_max_body_size是 1MB，不调大，任何超过 1MB 的视频上传都会直接收到 413 错误。要加到对应 server 块：

server { client_max_body_size 100m; }

• Node 层：Multer 的limits.fileSize已经限制单文件大小，但 Express 的 body-parser 一般不会解析 multipart 请求，所以主要看 Multer 的配置；
• 应用层：除了 MIME 白名单，最好在保存文件后用扩展名 + magic number 双重校验，防止有人上传伪装成视频的恶意文件。

有的项目需要限制视频时长、禁止上传超过 10 分钟的视频，这种前端很难直接判断（需要解析文件元数据），更稳妥的是后端在上传后做异步检测，或者在发布流程里进行转码时校验。

4.3 视频封面与多格式兼容处理

默认插入的是<video src>，没有封面，页面上显示一个黑底播放器，用户体验一般。比较好的方案是把封面图和视频一起处理。

思路是：后端在上传视频后，可选地生成一张封面图（比如用 ffmpeg 抽取视频首帧），然后返回的响应里多加一个字段：

{ "errno": 0, "data": { "url": "https://cdn.example.com/uploads/xxxxx.mp4", "poster": "https://cdn.example.com/uploads/xxxxx-cover.jpg" } }

接着在customInsert里手动构造带poster的视频标签。wangeditor 的insertFn会帮你插入，但如果想插入带属性的 video 标签，可以用 editor 实例的 API 手动插入节点，或者简单一点，利用插入 HTML 的能力：

customInsert(res, insertFn) { if (res.errno === 0) { const { url, poster } = res.data // 方案一：直接用 insertFn，能得到基础 video 标签 // insertFn(url) // 方案二：通过 editor API 插入带 poster 的 video const editor = getCurrentEditor() // 你自己维护的全局 editor 实例 editor.restoreSelection() editor.dangerouslyInsertHtml( `<video src="${url}" poster="${poster || ''}" controls style="max-width:100%;"></video>` ) } }

dangerouslyInsertHtml是 wangeditor v5 提供的插入 HTML 的 API，这个名字很直白，确实很危险，使用时必须小心。只插入受信任的、后端返回的数据，不要拼接用户输入的内容，否则等于给自己开了一个 XSS 入口。如果你不想冒风险，就老老实实用insertFn(url)，封面问题可以放到前端渲染时用 CSS 或者给 video 元素加 poster 样式去处理。

格式兼容方面，目前浏览器普遍能播mp4 / webm / ogg，但老一点的浏览器对 h.265 编码的 MP4 支持很差。如果你的业务需要兼容老旧环境，最好在后端做视频转码，统一转成 h.264 编码的 MP4，再返回给前端。这个话题能写一篇单独文章，这里不展开，只提醒你“能上传”不等于“能播放”。

5. 踩坑实录：我实际遇到的问题与排查方法

5.1 回调数据格式不对导致“上传失败”

这是我在对接中遇到最多的问题。后端同事把接口写成：

{ "code": 0, "data": { "url": "https://example.com/xxx.jpg" } }

前端配置好之后，一上传就提示失败。打开 Network 面板一看，请求明明成功，文件也存到服务器了，但编辑器就是不认。原因就是前面说的：wangeditor 内置逻辑只认errno字段。遇到这种情况有两类修法：

• 改后端，把code换成errno，这是推荐方案，毕竟后面可能还有别的系统对接；
• 不改后端，在前端customInsert里做适配，把res.code === 0翻译成成功，调用insertFn。

排查这类问题，我习惯的路径是：先看 Network 面板确认请求状态码是不是 2xx，再看返回体结构，最后看控制台有没有[wangEditor]前缀的错误提示。wangeditor 的错误提示一般很明确，顺着英文提示基本能定位。

5.2 跨域问题：前后端分离环境下的配置

如果你的前端页面在https://admin.example.com，上传接口在https://api.example.com，必然遇到跨域。具体表现是上传请求发出，但被浏览器拦截，提示 CORS 错误。

后端需要处理两件事：

一是响应允许跨域访问，带上必要的 CORS 头：

app.use((req, res, next) => { res.setHeader('Access-Control-Allow-Origin', 'https://admin.example.com') res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS') res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization') if (req.method === 'OPTIONS') { return res.sendStatus(204) } next() })

二是在携带Authorization头的情况下，浏览器会先发一个OPTIONS预检请求。上面代码里对OPTIONS直接返回 204，同时Access-Control-Allow-Headers里明确列出了Authorization，这样预检才能通过。

要注意的是，如果你把Access-Control-Allow-Origin配成*，一旦请求里带了Authorization头，浏览器也会拦截，因为凭证信息不允许通配。生产环境请把域名写成具体的，别图省事。

5.3 上传进度、loading 与交互体验

wangeditor 内置上传时，上传过程中工具栏按钮上会有 loading 状态，但这个反馈在视觉上还是比较淡的。如果你的用户经常上传大视频，建议在customUpload里自己做进度反馈。

用 axios 上传时，可以在onUploadProgress里拿到进度：

uploadVideo: { customUpload(file, insertFn) { const formData = new FormData() formData.append('file', file) axios.post('/api/upload/video', formData, { onUploadProgress: (e) => { const percent = Math.round((e.loaded / e.total) * 100) console.log(`视频上传进度：${percent}%`) // 这里可以弹一个全局 loading 提示 }, }).then((response) => { const res = response.data if (res.errno === 0) { insertFn(res.data.url) } }) }, }

进度条比普通的“转圈提示”舒服很多。对于几十上百 MB 的视频，用户看到进度在动，就不会觉得卡死了。这是很细节但很能提升体验的点。

5.4 其他常见问题速查表

这些坑是我在不同项目里实际遇到过的，不是文档上能看出来的。最想强调的一点：做上传功能时，前后端提前约定好字段名和返回结构，比什么都重要。接口文档里写清楚“errno 为 0 表示成功，data.url 为文件完整访问地址”，能省掉无数个互相甩锅的下午。

6. 实操心得与扩展建议

6.1 别忘了服务端文件清理与安全

上传功能上线后，服务器上的文件只会越来越多。我在一个项目里吃过亏：用户上传的图片没有做内容管理，结果存储空间被无效文件占满。所以项目规划时就要考虑：

• 上传的图片/视频是随内容一起发布，还是独立素材？如果是前者，发布成功后可以把文件标记为“已关联”，定期清理未关联的临时文件；
• 文件重名问题用随机文件名解决，但要保留扩展名，否则浏览器可能无法正确识别 MIME；
• 对象存储的防盗链要配置，防止图片被其他站点直接引用；
• 图片和视频的访问域名尽量用独立的 CDN 域名，不使用带 cookie 的站点主域名，否则图片加载会携带无关的 cookie，浪费带宽。

服务端做文件类型校验时，不要只看扩展名，也不要只信请求头里的Content-Type，它是由浏览器决定的，可以被伪造。稳妥的做法是读取文件开头几个字节，检测 magic number。比如 JPEG 开头是FF D8 FF，PNG 开头是89 50 4E 47，MP4 一般在第 4 个字节处有一个ftyp盒子标识。这个工作在 Node 里可以用file-type库做，非常方便。

6.2 后续还可以这样扩展

如果你不只是想把功能跑通，还想做得更完善，有几个方向可以继续花时间：

• 大文件分片上传：视频超过 100MB 后，单请求上传体验很差，断网就得重来。可以考虑使用分片上传方案，前端把文件切片，后端按顺序接收并合并，wangeditor 这边只要在customUpload里接入分片逻辑即可；
• 图片压缩与水印：用户在编辑器里上传的原始图片可能几 MB 大，直接回填会影响页面加载速度。可以让后端在保存时统一做压缩、旋转矫正，并按需添加水印；
• 素材管理面板：如果运营需要反复使用同一张图，可以做一个独立的素材选择面板，选中后通过编辑器 API 插入图片，而不是每次重新上传一份。

这些扩展都不改变 wangeditor 本身的用法，只是在customUpload或后端接口里做文章。上传这块的思路是通用的，编辑器只是一个触发入口，真正的复杂度都在文件存储和传输层。

最后再分享一个小技巧：对接完以后，建议写一个自动化冒烟测试，直接调用上传接口，断言返回的errno === 0且data.url是一个可访问的地址。这样以后后端升级、服务迁移、存储桶权限变动的时候，你不需要每次手动点一遍编辑器就能发现链路是否正常。上传看起来是小功能，但它是内容生产的第一步，一旦坏了，整个编辑流程都会停滞。把这些约定和数据格式提前固化下来，后续维护会轻松很多。