5分钟搞定！CKEditor 5与Spring Boot无缝集成指南
项目地址: https://gitcode.com/GitHub_Trending/ck/ckeditor5 你是否还在为富文本编辑器集成到Spring Boot项目中而烦恼？是否遇到过上传图片不显示、配置复杂、编辑器样式错乱等问题？本文将带你一步到位解决这些痛点，通过ZIP包快速集成CKEditor 5，并实现图片上传功能，让你的内容管理系统焕发新生。读完本文，你将掌握：
- 3步完成CKEditor 5与Spring Boot项目整合
- 5分钟实现本地图片上传功能
- 常见集成问题的解决方案与最佳实践
项目准备与依赖配置
首先确保你的Spring Boot项目已添加Web和Thymeleaf依赖。在pom.xml中添加以下配置：
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-thymeleaf</artifactId>
</dependency>
</dependencies>
如果你还没有项目，可以通过Spring Initializr快速创建，选择"Spring Web"和"Thymeleaf"依赖即可。
3步完成CKEditor 5集成
步骤1：下载并部署CKEditor 5资源
从CKEditor官方网站下载定制化构建的ZIP包，解压后将ckeditor5.js和ckeditor5.css文件复制到项目的src/main/resources/static/ckeditor5/目录下。正确的文件结构应如下所示：
src/main/resources/
├── static/
│ └── ckeditor5/
│ ├── ckeditor5.js
│ └── ckeditor5.css
└── templates/
└── index.html
步骤2：创建Thymeleaf模板文件
在src/main/resources/templates目录下创建index.html文件，添加以下内容：
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<title>CKEditor 5 - Spring Boot集成示例</title>
<link rel="stylesheet" href="/ckeditor5/ckeditor5.css">
</head>
<body>
<div class="container mt-4">
<h1>富文本编辑器示例</h1>
<div id="editor">
<p>Hello from CKEditor 5!</p>
</div>
</div>
<script type="importmap">
{
"imports": {
"ckeditor5": "/ckeditor5/ckeditor5.js",
"ckeditor5/": "/ckeditor5/"
}
}
</script>
<script type="module">
import {
ClassicEditor,
Essentials,
Paragraph,
Bold,
Italic,
Image,
ImageUpload
} from 'ckeditor5';
ClassicEditor
.create( document.querySelector( '#editor' ), {
licenseKey: 'GPL', // 开源项目使用GPL许可证
plugins: [ Essentials, Paragraph, Bold, Italic, Image, ImageUpload ],
toolbar: [
'undo', 'redo', '|', 'bold', 'italic', '|',
'imageUpload'
],
image: {
toolbar: [
'imageStyle:inline',
'imageStyle:block',
'imageStyle:side',
'|',
'toggleImageCaption',
'imageTextAlternative'
]
}
} )
.then( editor => {
console.log( 'Editor initialized', editor );
} )
.catch( error => {
console.error( error.stack );
} );
</script>
</body>
</html>
步骤3：创建控制器并运行项目
创建HomeController.java处理请求：
package com.example.demo;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
@Controller
public class HomeController {
@GetMapping("/")
public String index() {
return "index";
}
}
启动项目后访问http://localhost:8080，你将看到集成好的CKEditor 5编辑器：
图片上传功能实现
CKEditor 5提供多种图片上传方案，包括：
- Simple Upload Adapter：通过XMLHttpRequest直接上传
- CKBox：完整的文件管理解决方案
- Base64上传：将图片编码为Base64字符串（不推荐生产环境使用）
本地存储上传实现
添加图片上传控制器ImageUploadController.java：
package com.example.demo;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.multipart.MultipartFile;
import java.io.File;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;
@RestController
public class ImageUploadController {
@PostMapping("/upload-image")
public ResponseEntity<Map<String, String>> uploadImage(
@RequestParam("upload") MultipartFile file) throws IOException {
// 保存文件到本地
String uploadDir = System.getProperty("user.dir") + "/src/main/resources/static/uploads/";
File dir = new File(uploadDir);
if (!dir.exists()) dir.mkdirs();
String fileName = System.currentTimeMillis() + "_" + file.getOriginalFilename();
File dest = new File(uploadDir + fileName);
file.transferTo(dest);
// 返回图片URL
Map<String, String> response = new HashMap<>();
response.put("url", "/uploads/" + fileName);
return ResponseEntity.ok(response);
}
}
修改编辑器配置添加上传适配器：
ClassicEditor
.create( document.querySelector( '#editor' ), {
// ...其他配置
simpleUpload: {
uploadUrl: '/upload-image',
headers: {
'X-CSRF-TOKEN': document.querySelector('meta[name="csrf-token"]').content
}
}
} )
常见问题解决方案
1. 编辑器样式错乱
确保ckeditor5.css文件正确引入，检查浏览器控制台是否有404错误。推荐使用绝对路径：
<link rel="stylesheet" href="/ckeditor5/ckeditor5.css">
2. 图片上传403错误
Spring Boot默认开启CSRF保护，需要在请求头中添加CSRF令牌：
<meta name="_csrf" content="${_csrf.token}">
<meta name="_csrf_header" content="${_csrf.headerName}">
3. 编辑器工具栏不显示
检查plugins配置是否包含所需插件，确保没有拼写错误。基础工具栏推荐配置：
toolbar: [ 'undo', 'redo', '|', 'bold', 'italic', '|', 'imageUpload' ]
高级配置与最佳实践
自定义编辑器功能
通过CKEditor Builder定制所需功能：
- 访问CKEditor Builder
- 选择所需插件（如表格、代码块、数学公式等）
- 下载定制构建包并替换项目中的
ckeditor5目录
数据持久化
获取编辑器内容的方法：
const editorData = editor.getData();
// 通过AJAX发送到后端保存
fetch('/save-content', {
method: 'POST',
body: JSON.stringify({ content: editorData }),
headers: {
'Content-Type': 'application/json',
'X-CSRF-TOKEN': document.querySelector('meta[name="csrf-token"]').content
}
});
总结与扩展阅读
通过本文的3个步骤，你已成功将CKEditor 5集成到Spring Boot项目中，并实现了图片上传功能。更多高级功能可参考：
- 官方文档：docs/getting-started/integrations/spring-boot.md
- 图片上传指南：docs/features/image-upload.md
- 编辑器API文档：docs/api/index.md
现在，你可以专注于内容创作，让CKEditor 5处理所有富文本编辑需求。如有任何问题，欢迎在评论区留言讨论！
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
