- 后端（Java）：提供文件上传服务、配置 CKEditor 需要的选项（如上传 URL）。
- 前端（HTML/JS）：引入 CKEditor 的核心文件,并初始化编辑器。
- 集成：将后端提供的配置传递给前端 CKEditor 实例。
下面我将提供一个完整、分步的指南，以一个常见的 Spring Boot 项目为例，详细说明如何配置 CKEditor 5，并实现一个功能齐全的富文本编辑器，包括文件上传功能。
（图片来源网络，侵删）
整体流程概览
- 添加依赖：在
pom.xml中添加 Spring Boot Web 依赖。 - 创建前端页面：在
resources/templates下创建 HTML 文件，引入 CKEditor 5 核心文件。 - 配置文件上传：在后端创建一个控制器，处理文件上传请求并返回 CKEditor 5 所需的 JSON 格式。
- 初始化 CKEditor：在前端页面中，使用 JavaScript 初始化 CKEditor,并将其配置为使用我们创建的上传端点。
- 测试：启动应用，访问页面,测试编辑和上传功能。
步骤 1: 项目准备 (Spring Boot)
假设你使用的是 Spring Initializr 创建了一个项目，请确保在 pom.xml 中包含了 spring-boot-starter-web 依赖。
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- 其他依赖... -->
</dependencies>
步骤 2: 准备前端文件
CKEditor 5 有两种使用方式：经典版 和 _inline_版，这里我们使用更灵活的 经典版。
1 下载 CKEditor 5
访问 CKEditor 5 官网，选择 "Classic editor" 并下载，下载后，解压你会得到一个 ckeditor 文件夹。
2 创建 HTML 页面
在你的 Spring Boot 项目中，创建 src/main/resources/templates 目录（如果不存在），然后在该目录下创建一个名为 editor.html 的文件。
（图片来源网络，侵删）
将解压后的 ckeditor 文件夹中的以下内容复制到 src/main/resources/static 目录下：
ckeditor.jstranslations(可选,用于语言包)build目录 (包含核心构建文件)
你的项目结构大概是这样：
src/
└── main/
├── resources/
│ ├── static/
│ │ └── ckeditor/ <-- 复制过来的 CKEditor 文件
│ │ ├── ckeditor.js
│ │ ├── build/
│ │ └── translations/
│ └── templates/
│ └── editor.html <-- 我们要创建的页面
└── java/
└── ... (你的 Spring Boot 启动类等)3 编写 editor.html
编辑 src/main/resources/templates/editor.html 文件。
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">CKEditor 5 集成示例</title>
<!-- 1. 引入 CKEditor 5 样式 -->
<link rel="stylesheet" href="/ckeditor/ckeditor.css">
</head>
<body>
<h1>CKEditor 5 富文本编辑器</h1>
<!-- 2. 创建一个 div 作为编辑器的容器 -->
<div id="editor">
<p>在这里输入一些内容...</p>
</div>
<!-- 3. 引入 CKEditor 5 核心 -->
<script src="/ckeditor/ckeditor.js"></script>
<!-- 4. 初始化编辑器 -->
<script>
ClassicEditor
.create(document.querySelector('#editor'), {
// 在这里配置 CKEditor
toolbar: {
items: [
'heading', '|',
'bold', 'italic', 'link', 'bulletedList', 'numberedList', '|',
'outdent', 'indent', '|',
'blockQuote', 'insertTable', 'undo', 'redo',
'ckfinder' // 添加 CKFinder 按钮，用于文件上传
]
},
// 关键配置：设置文件上传的 URL
// 这个 URL 将指向我们后端创建的上传接口
ckfinder: {
uploadUrl: '/api/upload'
}
})
.then(editor => {
console.log('编辑器已初始化', editor);
})
.catch(error => {
console.error('初始化编辑器时发生错误', error);
});
</script>
</body>
</html>
代码解释:
（图片来源网络，侵删）
ClassicEditor.create(...): 初始化经典编辑器。toolbar: 自定义工具栏，我们添加了一个名为ckfinder的按钮，这个按钮是 CKEditor 5 的一个官方插件,专门用来处理文件上传。ckfinder.uploadUrl: 这是最关键的一步，它告诉 CKEditor，当用户点击上传按钮时，应该将文件发送到哪个 URL，这里我们指向/api/upload，这个 URL 将由我们的 Java 后端提供。
步骤 3: 后端配置 (Java)
我们需要创建一个 Spring MVC 控制器来处理 /api/upload 请求，这个控制器需要接收文件，保存它，并返回一个符合 CKEditor 5 期望的 JSON 响应。
1 创建文件上传目录
在你的项目根目录下创建一个 uploads 文件夹,用于存放上传的文件。
项目根目录/
└── uploads/2 创建控制器类
创建一个 Java 类，EditorController.java。
package com.example.demo.controller;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;
import java.io.File;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.HashMap;
import java.util.Map;
import java.util.UUID;
@RestController
@RequestMapping("/api")
public class EditorController {
// 从 application.properties 中读取上传路径
@Value("${file.upload-dir:uploads}")
private String uploadDir;
@PostMapping("/upload")
public ResponseEntity<?> uploadFile(@RequestParam("upload") MultipartFile file) {
// 1. 检查文件是否为空
if (file.isEmpty()) {
return ResponseEntity.badRequest().body("请选择一个文件。");
}
try {
// 2. 确保上传目录存在
Path uploadPath = Paths.get(uploadDir);
if (!Files.exists(uploadPath)) {
Files.createDirectories(uploadPath);
}
// 3. 生成唯一的文件名以防止冲突
String originalFilename = file.getOriginalFilename();
String fileExtension = originalFilename.substring(originalFilename.lastIndexOf("."));
String uniqueFilename = UUID.randomUUID().toString() + fileExtension;
// 4. 保存文件
Path filePath = uploadPath.resolve(uniqueFilename);
Files.copy(file.getInputStream(), filePath);
// 5. 构造 CKEditor 5 期望的响应格式
// URL 应该是可以通过 Web 访问的路径
String fileUrl = "/" + uploadDir + "/" + uniqueFilename;
Map<String, Object> response = new HashMap<>();
response.put("uploaded", true);
response.put("url", fileUrl);
return ResponseEntity.ok(response);
} catch (IOException e) {
e.printStackTrace();
return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body("文件上传失败。");
}
}
}
3 配置上传路径（推荐）
在 src/main/resources/application.properties 文件中，定义上传目录的路径,这样更容易管理。
# 设置文件上传目录 file.upload-dir=uploads
代码解释:
@RestController: 标记这是一个 REST 控制器。@PostMapping("/api/upload"): 处理 POST 请求到/api/upload。@RequestParam("upload") MultipartFile file: CKEditor 5 默认会将文件字段名设置为upload，所以这里必须使用upload作为参数名。- 响应格式: CKEditor 5 期望一个 JSON 响应，包含
uploaded(布尔值) 和url(上传后文件的访问链接),我们的代码严格按照这个格式返回。 - 文件 URL: 返回的 URL 是一个相对于项目根路径的 URL (
/uploads/abc123.png)，这样前端就可以直接通过这个 URL 访问上传的图片。
步骤 4: 运行和测试
- 启动 Spring Boot 应用。
- 在浏览器中访问
http://localhost:8080/editor.html(假设你的应用运行在 8080 端口)。 - 你会看到一个 CKEditor 5 编辑器界面。
- 点击工具栏中的图片上传按钮（一个带有山脉图标的按钮）。
- 选择一张本地图片上传。
- 如果一切顺利，图片会立即插入到编辑器中，并且文件已经保存在你项目的
uploads目录下。
进阶配置与常见问题
自定义上传逻辑
在上传控制器中,你可以添加更多逻辑，
- 文件类型限制: 检查文件扩展名或 MIME 类型,只允许上传图片。
- 文件大小限制: 检查文件大小,防止上传过大的文件。
- 存储到云服务: 不将文件保存在本地，而是上传到 AWS S3、阿里云 OSS 等云存储服务，然后将云存储的 URL 返回给 CKEditor。
使用 CKEditor 5 的官方 CKFinder
上面的例子中，我们使用了 ckfinder 配置项，它实际上是在调用一个简化的上传接口，如果你需要更强大的文件管理功能（如文件夹浏览、重命名、删除等），可以集成 CKEditor 5 的官方商业插件 CKFinder，这需要额外的许可证，并且配置会更复杂,但功能也更强大。
获取编辑器内容
当你需要保存用户输入时，可以通过获取编辑器实例的 data 属性。
// 假设 editor 是你初始化时的 editor 实例
const editorData = editor.getData();
console.log(editorData);
// 然后可以将这个数据通过 AJAX 发送到后端进行保存
fetch('/api/save-content', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({ content: editorData })
});
解决跨域问题
如果你的前端和后端部署在不同的域名下，可能会遇到跨域问题，你可以在 Spring Boot 控制器上添加 @CrossOrigin 注解来解决。
@RestController
@RequestMapping("/api")
@CrossOrigin(origins = "http://localhost:8080") // 允许来自前端地址的请求
public class EditorController {
// ...
}
通过以上步骤，你就成功地在 Java (Spring Boot) 项目中集成了一个功能完整的 CKEditor 5 富文本编辑器,并实现了文件上传功能。
