스프링 부트 CKEditor

스프링 부트 CKEditor 19 - 오류 사항 및 플러그인 관련 설명

카테고리 : 개발자 유미

https://youtu.be/92RoFOQX4B4?si=XVL-Tj3CXp-DVdYH

스프링 부트 CKEditor 19 - 오류 사항 및 플러그인 관련 설명

Spring Boot CKEditor 5 사용 시 자주 발생하는 오류 및 해결 방법 정리

CKEditor 5를 Spring Boot 프로젝트에 연동하다 보면 생각보다 다양한 오류를 만나게 된다.

특히:

  • 게시글 저장 시 WhiteLabel Error
  • 에디터 높이 조절 시 이미지 깨짐
  • 줄바꿈 문제
  • 이미지 크기 조절 문제
  • HTML 소스 편집 문제

등은 실제로 가장 많이 발생하는 이슈들이다.

이번 글에서는 CKEditor 5를 사용하면서 자주 발생하는 문제와 해결 방법을 정리해본다.

1. 게시글 저장 시 WhiteLabel Error 발생

가장 많이 발생하는 오류 중 하나다.

증상

게시글 작성 후 저장 버튼 클릭 시:

Whitelabel Error Page

발생

또는:

Data too long for column

오류 발생

2. 원인

대부분 원인은:

DB 컬럼 크기 부족

이다.

문제 상황 예시

content VARCHAR(255)

로 설정된 경우

CKEditor는 HTML 태그까지 저장한다.

예시:

<h1>안녕하세요</h1>
<p>내용입니다</p>
<img src="...">

즉 실제 저장 문자열 길이가 매우 길어진다.

3. 해결 방법

VARCHAR → LONGTEXT 변경

ALTER TABLE contents
MODIFY content LONGTEXT;

추천 타입

타입용도
VARCHAR짧은 문자열
TEXT일반 게시글
LONGTEXTCKEditor HTML 저장

4. 왜 LONGTEXT를 추천할까?

CKEditor는:

  • HTML
  • 이미지 태그
  • 스타일
  • 테이블
  • 링크

등이 모두 포함된다.

따라서 실제 데이터 크기가 매우 커진다.

실무에서는 거의 대부분:

LONGTEXT

사용

5. CKEditor 높이 조절 시 발생하는 문제

많이 하는 실수 중 하나다.

일반적인 높이 조절 방식

.ck-editor__editable {
    height: 500px;
}

6. 문제점

이 방식은:

에디터 내부 이미지까지 height 영향을 받는다

즉:

  • 이미지 크기 깨짐
  • 테이블 레이아웃 깨짐
  • 비율 깨짐

발생 가능

7. 실제 문제 예시

원래:

200px 이미지

였는데

CSS 영향으로:

450px

로 늘어나는 문제 발생

8. 올바른 해결 방법

NOT 선택자 활용

.ck-editor__editable:not(.ck-comment__input *) {
    min-height: 500px;
}

또는:

.ck-editor__editable_inline {
    min-height: 500px;
}

사용 권장

9. 왜 min-height를 사용할까?

height

는 강제 고정

반면:

min-height

는:

최소 높이만 보장

하므로

내부 이미지나 테이블에 영향이 훨씬 적다.

10. 게시글 줄바꿈 문제

증상

브라우저 폭이 줄어들 때:

자동 줄바꿈이 안됨

결과:

  • 가로 스크롤 발생
  • 레이아웃 깨짐

11. 원인

CKEditor HTML 내부의:

긴 문자열
긴 URL
코드 블럭

등이 줄바꿈되지 않음

12. 해결 방법

CSS 적용

.content-area {
    word-break: break-all;
    overflow-wrap: break-word;
}

추천 설정

.content-area {
    overflow-wrap: anywhere;
}

최신 브라우저에서 매우 안정적

13. 이미지 크기 조절 기능 추가

CKEditor 기본 상태에서는:

이미지 크기 조절 기능 없음

14. 해결 방법

Image Resize Plugin 추가

CKEditor Custom Build에서:

Image Resize

플러그인 추가

15. 주의사항

이 기능은:

다운로드 방식 CKEditor

에서만 가능

CDN 방식 제한

CDN 방식은:

플러그인 추가 어려움

존재

16. Custom Build 방식 추천 이유

실무에서는 대부분:

Custom Build

사용

이유:

  • 원하는 플러그인 추가 가능
  • 최적화 가능
  • 번들 크기 감소
  • 커스터마이징 가능

17. 소스 코드 편집 기능 추가

개발 블로그나 기술 게시판에서는 매우 중요하다.

Source Editing Plugin

추가 시:

HTML 직접 수정 가능

18. 활용 예시

  • HTML 직접 편집
  • iframe 삽입
  • custom style 추가
  • syntax highlight
  • embed 코드 추가

19. Plugin 추가 방법

CKEditor Custom Build 사이트에서:

Source Editing

검색 후 추가

20. 실무에서 많이 사용하는 플러그인

추천 플러그인 목록

플러그인용도
Image Resize이미지 크기 조절
Source EditingHTML 직접 수정
Table표 삽입
Media Embed유튜브 삽입
Code Block코드 블럭
Highlight하이라이트
Autoformat자동 포맷

21. Premium 플러그인 주의

CKEditor에는:

Premium

표시 플러그인 존재

의미

유료 플러그인

예시:

  • 협업 기능
  • 댓글 기능
  • Track Changes
  • AI 기능

22. 무료 플러그인만 사용하는 방법

Custom Build 생성 시:

Premium 체크 제외

하면 무료 구성 가능

23. 실무에서 가장 중요한 포인트

CKEditor는 단순 에디터가 아니다.

사실상:

HTML 생성기

에 가깝다.

따라서:

  • DB 타입
  • CSS 영향
  • HTML 렌더링
  • XSS
  • 이미지 처리

모두 고려해야 한다.

24. 실무에서 추가로 꼭 해야 하는 작업

1) XSS 방어

사용자가:

<script>

삽입 가능

해결 방법

  • Jsoup Sanitizer
  • OWASP Sanitizer

사용 권장

25. HTML Sanitizing 예시

String safeHtml =
    Jsoup.clean(
        html,
        Safelist.basicWithImages()
    );

26. 이미지 업로드 용량 제한

필수 설정

spring.servlet.multipart.max-file-size=10MB
spring.servlet.multipart.max-request-size=10MB

27. CKEditor에서 Base64 업로드 비추천

일부 설정에서는:

이미지를 Base64로 HTML에 직접 저장

가능

하지만:

  • DB 급격히 증가
  • 성능 저하
  • HTML 크기 폭증

문제로 인해

실무에서는:

S3 URL 저장 방식

사용

28. 추천 구조

실무 권장 구조:

CKEditor
↓
Spring Boot
↓
S3 업로드
↓
이미지 URL 저장

29. 이번 글 핵심 정리

WhiteLabel Error 원인

VARCHAR 크기 부족

→ LONGTEXT 변경

높이 조절 문제

height

직접 사용 주의

→ min-height 권장

이미지 깨짐 방지

editable 전체 height 강제 지정 금지

줄바꿈 문제

overflow-wrap

활용

이미지 리사이즈

Image Resize Plugin 추가

HTML 직접 수정

Source Editing Plugin 활용

마무리

CKEditor 5는 단순한 텍스트 에디터가 아니라 거의 하나의 작은 CMS 수준의 기능을 제공한다.

따라서:

  • DB 설계
  • CSS 구조
  • 보안
  • 파일 업로드
  • HTML 렌더링

전체를 함께 고려해야 안정적인 서비스를 만들 수 있다.

특히 실무에서는:

에디터 자체보다
"에디터가 생성하는 HTML"

을 어떻게 안전하게 저장하고 렌더링할지가 핵심이다.

© 2020. All rights reserved.

SIKSIK