CKEditor5를 활용해보기 위한 과정에서
정말 많은 오류를 만났다.
대부분 CDN 이슈였으며 이를 해결하기 위해
다양한 방법들을 시도해봤으나 해결되지 않아
결국 노드js 설치 후 커스텀 빌드를 꾸리게 되었다.
혹시나 CKEditor5를 활용해보고 싶은 분이 있다면
쉽고 간편한 CDN 방식에 속아 넘어가지 말고
꼭, 반드시, 젯타이!!!
노드js 설치 후 필요한 기능을
추가하는 방식으로 사용해보길 권헌다.
▼ 일반적인 클래식 에디터 CDN
<script src="https://cdn.ckeditor.com/ckeditor5/40.1.0/classic/ckeditor.js"></script>기본 CDN 사용 시 정상적으로 구동
일반적인 텍스트 기능은 정상적으로 구동됨을 확인할 수 있다.
하지만 이미지 추가 기능을 사용하기부터
오류 파티가 시작되는데...
1. 슈퍼빌드 사용 시 오류 발생
이미지 기능을 간단히 추가할 수 있는
CDN이 있었는데 바로 슈퍼빌드였다.
하지만 슈퍼빌드 CDN 사용 시 아래와 같이
오류가 발생하였고 원인은 유료 시스템이었기 때문이다.
> Super-build(슈퍼빌드) = 기업용 플러그인 덩어리
Super-build는 원래 CKEditor가
“우리 기능 다 써봐!” 하고 보여주는 데모용 패키지로
여기에 포함된 플러그인은 대부분 유료다.
| 플러그인 | 특징 |
| 실시간 협업(TrackChanges, Comments 등) | 서버 필요(유료) |
| WProofreader | 별도 API 키(유료) |
| CKBox / CKFinder | 서버 설정 필수 |
| ExportPdf / ExportWord | 구독 필요(유료) |
| DocumentOutline | 사이드바 UI 컨테이너 필요 |
우리는 실제로 쓰지도 않을 기능들이 들어있고,
DOM이나 서버 설정 없으면 계속 에러 터짐.
그래서 Super-build는 기능이 많아서 편한 게 아니라,
안 쓰는 기능 때문에 계속 오류가 나는 구조
“Super-build를 가져오면 모든 플러그인이 한 번에 켜짐”
그래서 계속:
- collaboration-missing-channelid
- no-wproofreader-configuration
- document-outline-container-not-provided
- 기타 모듈 에러
이런 것들이 터지게 된다.
결국 클래식 에디터를 활용해
가장 기초적인 이미지 기능만을 구현해보고 싶었으나
클래식 에디터 CDN 조차 이미지 기능 추가 시
클래식 CDN이 호출되지 않는 현상이 발생한다.
2. 서버 환경 구축: Front Controller와 MultipartConfig
(=수정해봤으나 결국 CDN 로드 되진 않았음)
CKEditor 5는 파일을 uploadImage.do와 같은 특정
엔드포인트로 멀티파트 요청(Multipart Request) 방식으로 전송
따라서 서버(Servlet)가 이 요청을 올바르게 받아서
처리하는 것이 첫 번째 핵심 과제이다.
오류 1: 파일 업로드 요청 처리 실패
원인)
Tomcat이나 WAS(Web Application Server)는
기본적으로 멀티파트 요청을 처리하지 못한다.
요청을 서블릿으로 보내기 전에 컨테이너 레벨에서
파일 데이터 처리를 지시해야 한다.
| 파일 | 문제점 | 해결 방법 |
| UploadImageAction.java | 일반 Java 클래스에는 @MultipartConfig를 적용할 수 없다. |
Front Controller (Servlet)인 FrontController.java로 @MultipartConfig 어노테이션을 이동한다. |
| FrontController.java | @MultipartConfig가 누락되어 있다. |
@WebServlet("*.do") 위에 @MultipartConfig(...)를 추가하여 WAS가 모든 .do 요청에 대해 파일 데이터를 처리하도록 지시한다. |
오류 2: 이미지 업로드 후 Front Controller의 불필요한 포워딩
원인)
UploadImageAction.java는 파일을 저장한 후
CKEditor가 요구하는 { "url": "..." } 형태의
JSON 응답을 직접 완료해야 한다.
그러나 Action 객체의 기본 로직은 항상
ActionForward 객체를 반환하여
JSP로 포워딩/리다이렉션을 시도하는 것이다.
| 파일 | 문제점 | 해결 방법 |
| UploadImageAction.java | JSON 응답 후에도 ActionForward를 반환하려고 한다. |
JSON 응답 완료 후 return null;을 실행하여 즉시 메서드를 종료한다. |
| FrontController.java | null 반환 시 처리가 누락되어 있다. |
forward = action.execute (request, response); 실행 직후 if (forward == null) { return; } 코드를 추가하여 추가 포워딩을 방지한다. |
3. 클라이언트 환경 구축: CDN 로드 타이밍 문제 (만성 오류)
서버 로직이 완벽하게 정리된 후에도,
클라이언트 측에서 Uncaught ReferenceError:
ClassicEditor is not defined 오류가 지속적으로 발생했다.
이는 CKEditor 5를 CDN 방식으로 사용할 때
발생하는 고질적인 타이밍 문제이다.
오류 3: ClassicEditor is not defined (타이밍 문제)
원인)
ClassicEditor.create(...)를 호출하는 초기화 JavaScript 코드가
CKEditor CDN 파일의 다운로드 및 실행이 완료되어
ClassicEditor 객체가 메모리에 정의되기 전에 먼저 실행되었기 때문이다.
| 시도한 방법 | 결과 | 논리적 분석 |
| CDN 스크립트를 <body> 하단으로 이동 |
오류 지속 | 다른 로컬 스크립트와 동기적으로 실행되는 과정에서 타이밍 불일치가 발생한다. |
| CDN 스크립트에 type="text/javascript" 추가 |
오류 지속 | 브라우저가 파일 타입을 올바르게 인식하도록 도와주는 조치이지만, 근본적인 타이밍 문제를 해결하지 못한다. |
| CDN 스크립트에 defer 또는 async 추가 |
오류 지속 | 다운로드는 비동기로 시작되지만, 실행이 완료되는 시점과 초기화 코드가 실행되는 시점 사이의 순서 보장이 여전히 완벽하지 않다. |
> 가장 강력한 논리적 해결 시도: window.onload
해결 방법)
모든 JavaScript 파일의 다운로드 및 실행을 포함하여,
웹 페이지의 모든 리소스 로드가 완료된 후에
초기화 코드를 실행하도록 강제한다.
// BoardWrite.jsp 파일의 초기화 스크립트 블록 전체를 감싸는 코드
window.addEventListener('load', function() {
// 여기에 ClassicEditor.create(...)를 포함한 전체 초기화 코드가 위치함
});
window.onload는 이론적으로
CDN 타이밍 문제를 해결하는 가장 안전한 방법이지만,
이 프로젝트에서는 ERR_BLOCKED_BY_ORB라는
보안 오류가 발생하면서 CDN 사용의 한계를 드러냈다.
오류 4: net::ERR_BLOCKED_BY_ORB (브라우저 보안 차단)
원인)
브라우저(크롬)가 CKEditor CDN 응답을
잠재적인 보안 위협이 있는 크로스 오리진 리소스로
판단하고 로드를 차단한 문제이다.
이 오류는 브라우저의 보안 정책을
직접적으로 건드릴 수 없음을 의미한다.
- BoardWrite.jsp 의 CKEditor CDN <script> 태그에
type="text/javascript" 속성을 추가하기 - 하드 리로드 (Ctrl + Shift + R) 를 수행하여
브라우저가 변경된 HTML과 함께
CDN 파일을 다시 로드하도록 시도
▶ 결국 CDN 방식을 포기하기로 하였다.
포스팅한 오류 외에도 많은 CDN 로드 불가 오류가 console에 나타났었다..
최종 결정: Node.js 빌드 환경으로 전환
수많은 논리적 코드 수정과 브라우저 환경 초기화 시도에도 불구하고
CDN 오류가 해결되지 않고 보안 차단 문제까지 발생함에 따라,
이는 CDN 제공 환경 자체의 한계로 판단한다.
최종 해결 방안
Node.js 환경에서 CKEditor 5 소스 코드를 직접 설치(npm)하고,
Webpack 등을 이용하여 커스텀 빌드 파일을 생성하여
프로젝트의 로컬 파일로 사용하기로 결정!