CKEditor5 自定义图片上传实战：从配置到后端对接

原创

于 2026-03-09 08:50:34 发布 · 411 阅读

标签

1. 为什么你需要自定义图片上传？

如果你正在为你的网站或后台管理系统寻找一个强大的富文本编辑器，CKEditor5 很可能已经进入了你的视线。它界面现代，功能强大，特别是那个“从 Word 直接粘贴并保留格式和图片”的功能，对于需要处理大量来自 Office 文档内容的团队来说，简直是神器。但是，当你兴致勃勃地集成它，准备测试图片上传时，一盆冷水可能就浇下来了——官方默认的图片上传服务是收费的。

没错，CKEditor5 的云端服务（CKEditor Cloud Services）提供了包括图片存储、转换在内的一整套服务，但这意味着你的用户图片数据会经过第三方服务器，并且你需要持续付费。对于很多项目，尤其是国内的企业级应用、私有化部署场景，或者对数据安全有严格要求的项目，这显然不是最佳选择。

所以，“自定义图片上传”就成了我们必须掌握的核心技能。这不仅仅是省点钱的问题，更是将核心数据控制权牢牢握在自己手里的关键一步。你需要把用户上传的图片，直接发送到你自己的服务器上，存储在你自己的硬盘或对象存储（比如阿里云 OSS、腾讯云 COS）里，整个流程完全自主可控。

我经历过好几次从官方服务切换到自建后端的过程，踩过不少坑，也积累了一些让流程更顺滑的经验。这篇文章，我就带你从零开始，手把手搞定 CKEditor5 的自定义图片上传，从最开始的构建器选择，到前端适配器（Adapter）的编写，再到与后端（这里以 PHP 为例）的对接细节，让你彻底摆脱对官方服务的依赖。

2. 第一步：获取属于你的 CKEditor5 构建包

很多新手会直接去 GitHub 下载一个“标准版”的 CKEditor5，然后发现缺少图片上传插件，又不知道怎么加进去。其实，官方提供了最省心的工具——在线构建器（Online Builder）。这就像是一个自助餐厅，你只需要挑选你需要的功能插件，它就会为你打包好一个完整的、优化过的 ckeditor.js 文件。

2.1 使用在线构建器

访问入口：打开 CKEditor5 官网，找到 “Builds” -> “Installation” -> “Online builder”。或者直接访问这个链接（请注意，链接地址可能会更新，以官网最新为准）。
选择起点：进入后，你会看到几个预设的编辑器类型，比如 Classic（经典）、Inline（行内）、Balloon（气球）等。对于大多数后台管理场景，Classic Editor 是最常用、最符合直觉的。我们就选它。
挑选插件：接下来是最关键的一步。在插件选择页面，你会看到一个长长的列表。请务必找到并勾选以下与图片上传相关的核心插件：
- Image：基础图片插件，提供插入图片的能力。
- ImageUpload：图片上传功能的核心插件。没有它，工具栏上连上传按钮都不会出现。
- ImageToolbar：允许你配置图片被选中时弹出的浮动工具栏（比如添加替代文字、调整样式）。
- ImageStyle：提供“全宽”、“居左”、“居右”等图片样式选项。
- （可选）ImageResize：允许用户拖动调整图片大小。
- （可选）ImageCaption：为图片添加标题。
除了图片相关插件，你也可以按需添加 Table、MediaEmbed（嵌入视频）、Link 等。选好后，点击下一步。
个性化配置：这里可以设置编辑器语言（记得选 Chinese (Simplified)）、工具栏布局等。你可以先保持默认，后续在代码里也能调整。
构建与下载：最后一步，点击 “Build” 按钮。官方服务器会为你生成一个专属的构建包，并提供一个下载链接。这个包里面就包含了 ckeditor.js、ckeditor.css 以及所有依赖的翻译文件等。

提示：在线构建器生成的包已经是最优配置，剔除了未使用的代码，比你自己手动引入一堆 npm 包要清爽得多，特别适合传统前端项目。

2.2 在项目中引入

下载的压缩包解压后，你会看到一个 build 文件夹。将整个文件夹拷贝到你的项目静态资源目录下（比如 static/ 或 js/lib/）。然后在你的 HTML 页面中引入核心文件：

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>我的编辑器</title>
    <!-- 引入 CKEditor5 样式 -->
    <link rel="stylesheet" href="./build/ckeditor.css">
</head>
<body>

最低0.47元/天解锁文章