웹 개발을 하다 보면 누구나 한 번쯤 이런 문제를 마주하게 됩니다.
HTML 코드를 그대로 웹 페이지에 보여줘야 하는데 브라우저가 태그로 해석해 의도한 결과가 나오지 않는 경우. 또는 사용자가 입력한 내용을 적절한 인코딩 없이 화면에 출력했다가 XSS 공격에 노출되는 경우입니다.
이런 문제를 줄이기 위해 자주 사용하는 대표적인 방법이 바로 HTML 이스케이프(HTML Escape)입니다.
이 글에서는 HTML 이스케이프가 무엇인지 왜 필요한지 그리고 실제로 어떻게 활용하는지를 처음 접하는 분도 이해할 수 있도록 차근차근 설명합니다. 더불어 실무에서 반복되는 변환 작업을 빠르게 처리할 수 있는 온라인 도구도 함께 소개합니다.
HTML 이스케이프, 왜 필요한가요?
HTML은 꺾쇠괄호(<, >), 앰퍼샌드(&), 따옴표(", ') 같은 문자를 태그, 속성, HTML 엔터티를 표현하는 문법 요소로 사용됩니다. 그런데 이 특수문자들이 데이터 안에 포함되어 있으면 문제가 생깁니다. 브라우저가 해당 내용을 일반 텍스트가 아닌 HTML 문법으로 해석하기 때문입니다.
예를 들어, 웹 페이지에 다음 내용을 그대로 출력하고 싶다고 가정해봅니다.
<p>This is a <strong>test</strong> page.</p>이 내용을 이스케이프 없이 HTML 문서에 출력하면 브라우저는 이를 텍스트가 아니라 실제 HTML 코드로 처리합니다.
즉, <p>와 <strong> 태그가 그냥 렌더링되어버립니다. 결과적으로 텍스트로 보여주고 싶었던 내용이 화면에서 실제 요소로 렌더링됩니다.
이스케이프를 적용하면 아래처럼 변환됩니다.
<p>This is a <strong>test</strong> page.</p>이제 브라우저는 이것을 태그가 아닌 순수한 텍스트로 인식하고 화면에 그대로 표시합니다. 이것이 HTML 이스케이프의 핵심 역할입니다.
보안 관점에서도 필수입니다
기술적인 이유만이 아닙니다. HTML 이스케이프는 보안에서도 매우 중요합니다.
사용자가 입력한 값을 그대로 웹 페이지에 출력하면 XSS(Cross-Site Scripting) 공격에 노출될 수 있습니다. 공격자가 악성 스크립트를 입력값으로 심어두면, 이스케이프 처리 없이 그대로 렌더링될 때 해당 스크립트가 실행됩니다.
<!-- 위험한 입력값 예시 -->
alert('XSS <test> & "injection" 😊');
<!-- 이스케이프 처리 후 -->
alert('XSS <test> & "injection" 😊');이스케이프 처리를 하면 스크립트가 실행되지 않고 그냥 문자열로 표시됩니다. 프론트엔드에서든 백엔드에서든 사용자 입력값은 반드시 이스케이프 처리 후 출력하는 것이 기본 보안 수칙입니다.
꼭 알아야 할 HTML 엔터티 변환표
HTML 이스케이프는 특정 문자를 HTML 엔터티(HTML Entity)로 바꾸는 작업입니다. 자주 사용하는 변환 규칙을 정리하면 다음과 같습니다.
| 원본 문자 | 이름 | HTML 엔터티 | 숫자 표기 |
|---|---|---|---|
| < | less-than | < | < |
| > | greater-than | > | > |
| & | ampersand | & | & |
| " | double-quote | " | " |
| ' | single-quote | ' | ' |
이 5가지가 HTML 이스케이프에서 가장 기본이 되는 변환 쌍입니다. 실무에서는 이것만 잘 처리해도 대부분의 문제를 예방할 수 있습니다.
언이스케이프(Unescape)는 반대 방향 변환, 즉 HTML 엔터티를 원본 문자로 되돌리는 작업을 말합니다.
비볼디 HTML 이스케이프 도구 사용법
개념을 이해했다면 이제 직접 사용해 볼 차례입니다. 매번 HTML 엔터티 변환 규칙을 찾아가며 수동으로 수정하는 방식은 번거롭고 코드가 길어질수록 실수 가능성도 커집니다. 그래서 온라인 변환 도구를 활용하면 훨씬 효율적으로 작업할 수 있습니다.
비볼디(Vivoldi)의 HTML 이스케이프 도구는 좌우 분할 에디터 방식으로 구성되어 있어 원본과 변환 결과를 동시에 비교할 수 있습니다. 사용 방법도 간단합니다.
기본 사용 흐름
- 입력: 왼쪽 에디터에 변환할 HTML 코드나 텍스트를 입력하거나 붙여넣습니다. 파일 업로드도 지원합니다.
- 실행: 상단의 ▶ ESCAPE 버튼을 클릭하면 변환 결과가 즉시 오른쪽 패널에 반영됩니다. 이미 이스케이프된 코드를 원래 상태로 되돌릴 때는 ◀ UNESCAPE 버튼을 사용합니다.
- 결과 확인: 오른쪽 패널에서 변환 결과를 확인하고 복사 버튼으로 바로 클립보드에 저장할 수 있습니다.
- 샘플 활용: 처음 사용하는 경우에는 샘플 기능을 이용해 예제 코드를 불러와 변환 과정을 확인해 보세요.
상태바에서는 문자 수, 줄 수, 바이트 수를 실시간으로 확인할 수 있습니다. 변환 전후 데이터 크기 변화도 함께 비교할 수 있어 결과를 빠르게 검토하기 편리합니다.
출력 형식 선택: HTML / JS / JSON
오른쪽 결과 패널에서는 HTML, JS, JSON 형식으로 결과를 전환해 확인할 수 있습니다. 상황에 따라 바로 사용할 수 있어 실무에서 특히 유용합니다.
같은 문자열이라도 출력되는 위치와 문맥(HTML, JavaScript, JSON)에 따라 필요한 이스케이프 규칙이 달라지기 때문입니다.
- HTML 탭: HTML 문서 본문이나 속성값에 안전하게 출력할 때 사용하는 HTML 엔터티 형식입니다.
<,&같은 형태로 출력됩니다. - JS 탭: JavaScript 문자열 안에 포함할 수 있도록 따옴표, 줄바꿈, 특수문자 등을 JavaScript 문자열 규칙에 맞게 변환합니다.
- JSON 탭: API 응답이나 JSON 데이터 안에 HTML을 포함시킬 때 사용합니다. JSON 문자열 안에서 유효하게 동작하도록 JSON 규칙에 맞춰 특수문자를 이스케이프합니다.
백엔드 개발자라면 API 응답이나 저장된 콘텐츠 데이터를 JSON으로 전달하면서 HTML 문자열을 함께 포함해야 하는 경우가 있습니다. 이럴 때 JSON 탭으로 바로 전환해서 사용할 수 있으니 편리합니다.
DIFF 기능으로 변환 전후 비교
결과 패널 상단의 DIFF 버튼을 클릭하면 원본과 변환 결과를 나란히 비교할 수 있습니다.
어떤 부분이 변경되었는지 한눈에 파악할 수 있어, 긴 코드나 대량 텍스트를 변환할 때 변경된 부분만 빠르게 검토할 수 있어 실수를 줄이는데 도움이 됩니다.
세밀하게 조정하는 옵션 기능
모든 특수문자를 일괄적으로 이스케이프하는 방식이 항상 최선은 아닙니다. 상황에 따라 일부 문자만 변환하거나 특정 영역은 그대로 유지해야 하는 경우도 있습니다.
비볼디 HTML 이스케이프 도구의 옵션 기능이 이런 세밀한 조정을 도와줍니다.
이스케이프 대상 선택
옵션 패널에서는 이스케이프할 문자를 개별적으로 ON/OFF할 수 있습니다.
기본적으로 다섯 가지 특수문자(<, >, &, ", ') 모두 활성화되어 있습니다. 특정 문자만 선택적으로 처리하고 싶다면 해당 토글을 끄면 됩니다.
예를 들어 사용 환경에 따라 일부 문자만 선택적으로 변환해야 하는 경우 원하는 문자만 활성화해 사용할 수 있습니다.
다만 HTML 속성값이나 사용자 입력 처리에서는 일반적으로 기본 설정을 유지하는 것이 안전합니다.
태그 보호 기능
코드를 보여주는 기술 문서나 개발 블로그를 작성할 때 자주 마주치는 상황이 있습니다. <pre>나 <code> 태그 내부는 이미 별도 처리되거나 원본 형식을 유지해야 하는 경우가 많습니다. 이미 처리된 코드 블록까지 다시 이스케이프하면 의도하지 않은 출력 결과가 생길 수 있습니다.
태그 보호 옵션에서 <script>, <style>, <pre>, <code> 등 특정 태그를 보호 대상으로 설정하면, 해당 태그 안의 내용은 이스케이프에서 제외됩니다. 문서 작성이나 코드 예제 관리 시 반복 작업을 줄이는데 도움이 됩니다.
중복 이스케이프 방지
이미 한 번 이스케이프된 코드를 다시 이스케이프하면 <가 &lt;가 되어버리는 문제가 생깁니다. 옵션에서 ‘이미 이스케이프된 문자 건너뜀’ 옵션을 활성화하면 이런 상황을 자동으로 줄일 수 있습니다.
외부에서 가져온 코드 일부가 이미 변환된 상태일 때 특히 편리합니다.
이모지 변환 옵션
이모지를 HTML 엔터티로 변환하는 기능도 제공합니다. 기본값은 비활성화되어 있어 이모지는 그대로 유지됩니다.
일부 레거시 시스템이나 HTML 엔터티 기반 저장·전송 환경에서는 이 옵션을 통해 이모지를 엔터티 형식으로 변환해 사용할 수 있습니다.
코드 내보내기: 블로그와 문서에 바로 활용하기
코드 예제를 블로그나 문서에 자주 삽입한다면 유용한 기능이 하나 더 있습니다. 바로 코드 내보내기 기능입니다.
결과 패널의 내보내기 버튼을 클릭하면 테마 선택 화면이 열립니다.
GitHub, Dracula, Monokai, VS Code Light, VS Code Dark, One Dark 등 6가지 코드 하이라이팅 테마를 선택할 수 있습니다.
선택한 테마를 미리보기로 확인한 뒤 복사 버튼을 누르면 인라인 스타일이 포함된 HTML 코드가 클립보드에 복사됩니다.
생성된 코드는 별도 CSS 설정 없이 다양한 HTML 환경에서 바로 활용할 수 있습니다.
기술 문서나 HTML 기반 블로그 환경에서는 코드 블록 스타일을 일관되게 유지하는 데 도움이 되며, 별도의 스타일링 작업을 줄여 문서 작성 시간을 절약할 수 있습니다.
작업 방식에 맞게 에디터 설정하기
도구를 반복해서 사용하다 보면 작은 설정 차이도 작업 효율에 영향을 주게 됩니다.
비볼디 HTML 이스케이프 도구는 에디터 환경을 조정할 수 있는 여러 설정도 제공합니다.
- 폰트 크기: A− / A+ 버튼으로 글자 크기를 조절할 수 있습니다. 화면 크기와 작업 환경에 맞게 편하게 설정해 사용할 수 있습니다.
- Tab/Spaces: 들여쓰기 방식을 탭 또는 스페이스(2칸, 4칸 등)로 선택할 수 있습니다. 기본값은 Spaces(4)입니다.
- 스크롤 동기화: 좌우 패널을 함께 스크롤하도록 설정할 수 있습니다. 긴 코드나 대량 텍스트를 비교할 때 변경 내용을 더 쉽게 확인할 수 있습니다.
- 테마: 에디터 자체의 테마도 Light / Dark 중에서 선택할 수 있습니다. 작업 환경과 취향에 따라 원하는 화면 구성을 사용할 수 있습니다.
좌우 패널 각각을 전체화면으로 확장할 수 있습니다. 내용이 많을 때 더 넓은 작업 공간에서 집중해서 확인할 수 있습니다.
실제로 이런 상황에서 사용됩니다
HTML 이스케이프는 생각보다 다양한 환경에서 활용됩니다.
기술 블로그나 문서 작성
코드를 설명하는 글에서는 HTML 태그 자체를 텍스트로 보여줘야 하는 경우가 자주 있습니다.
예를 들어, <div> 같은 태그를 그대로 출력하면 브라우저가 이를 실제 HTML 요소로 해석해 의도한 코드 예제가 보이지 않거나 문서 구조가 달라질 수 있습니다. 미리 이스케이프한 뒤 삽입하면 이런 문제를 줄일 수 있습니다.
이메일 템플릿 제작
HTML 이메일에서는 클라이언트마다 HTML 지원 범위와 렌더링 방식이 다를 수 있습니다.
이메일 클라이언트마다 HTML 해석 방식이 다르기 때문에, 코드나 특수문자를 텍스트로 보여줘야 하는 경우 적절한 이스케이프 처리가 도움이 됩니다.
서버에서 동적 콘텐츠 출력
사용자 입력값을 HTML 페이지에 출력할 때는 적절한 이스케이프가 필요합니다.
대부분의 템플릿 엔진과 프레임워크는 자동 이스케이프를 제공하지만 설정이 변경되었거나 특수한 출력 상황에서는 별도 처리가 필요할 수 있습니다.
API 응답에 HTML 포함
API 응답에서 HTML 문자열이나 서식이 포함된 콘텐츠를 JSON 형태로 전달해야 하는 경우가 있습니다.
이런 상황에서는 HTML 문자열 처리와 JSON 문자열 규칙을 함께 고려해야 하며 JSON 형식 출력 기능을 활용하면 검토에 도움이 됩니다.
CMS나 위키에 코드 삽입
WordPress, Confluence 같은 CMS나 문서 도구에 코드 예제를 삽입할 때도 HTML 처리 방식에 따라 별도 이스케이프가 필요할 수 있습니다.
플랫폼 특성에 맞게 출력 형식을 조정하면 코드가 더 안정적으로 표시됩니다.
HTML 이스케이프를 직접 구현한다면
개발자라면 직접 이스케이프 함수를 구현할 일도 있습니다. 기본 로직은 간단합니다. 문자열을 순회하면서 특수문자를 엔터티로 치환하면 됩니다.
JavaScript에서는 이렇게 작성합니다.
function escapeHtml(str) {
return str
.replace(/&/g, '&')
.replace(/</g, '<')
.replace(/>/g, '>')
.replace(/"/g, '"')
.replace(/'/g, ''');
}한 가지 주의할 점이 있습니다. &를 반드시 가장 먼저 처리해야 합니다. 나중에 처리하면 이미 변환된 <의 &까지 다시 이스케이프되어 &lt;가 되어버립니다.
Java에서는 Apache Commons Text 라이브러리의 StringEscapeUtils.escapeHtml4()를 많이 활용합니다. Spring Boot 환경에서는 Thymeleaf 템플릿 엔진이 기본적으로 자동 이스케이프를 지원하지만, th:utext를 사용할 때는 별도로 주의가 필요합니다.
// Java - Apache Commons Text
import org.apache.commons.text.StringEscapeUtils;
String escaped = StringEscapeUtils.escapeHtml4(rawInput);
// Thymeleaf - 자동 이스케이프 (기본 동작)
<p th:text="${userInput}"></p>
// Thymeleaf - 이스케이프 없이 출력 (주의 필요)
<p th:utext="${trustedHtmlContent}"></p>Python에서는 표준 라이브러리에 포함된 html.escape() 함수를 사용하면 됩니다.
import html
escaped = html.escape('<script>alert("XSS")</script>')
# 결과: <script>alert("XSS")</script>코드로 처리할 때와 도구로 처리할 때는 결과가 동일하지만, 도구는 대량의 텍스트를 빠르게 확인하거나 팀원과 공유할 때, 개발 환경 없이 변환 결과가 즉시 필요할 때 특히 유용합니다.
자주 하는 실수와 주의할 점
HTML 이스케이프를 사용할 때 자주 발생하는 실수도 함께 알아두면 좋습니다.
- 중복 이스케이프: 이미 변환된 값을 다시 이스케이프하면 < 가 &lt; 처럼 의도하지 않은 문자 변환이 발생할 수 있습니다. 이스케이프 처리가 어느 단계에서 수행되는지 확인하고 중복 적용되지 않도록 관리하세요. 비볼디 도구에서는 ‘이미 이스케이프된 문자 건너뜀’ 옵션으로 이를 줄일 수 있습니다.
- URL 속성 혼동: href 나 src 같은 URL 속성은 HTML 이스케이프만으로 충분하지 않을 수 있습니다. URL 인코딩(
%xx형태)과 HTML 이스케이프는 목적이 다르므로 구분해서 사용해야 합니다. - CSS/JS 컨텍스트 혼용: HTML 이스케이프는 HTML 문맥에서 사용하는 방식입니다. JavaScript 문자열, CSS 값, URL 파라미터처럼 출력 위치마다 필요한 인코딩 규칙이 달라집니다.
- 저장과 출력 단계를 혼용: 일반적으로는 데이터를 원본 형태로 저장하고 출력 시점에 컨텍스트에 맞게 이스케이프하는 방식이 관리와 재사용 측면에서 유리합니다. 저장과 출력 단계에서 동시에 처리하면 중복 이스케이프가 발생할 수 있습니다.
마치며: 작은 습관이 큰 문제를 막습니다
HTML 이스케이프는 처음에는 번거롭게 느껴질 수 있습니다. 하지만 출력 환경에 맞는 처리를 놓치면 화면 표시 오류나 보안 취약점, 예상하지 못한 출력 결과가 발생할 수 있습니다. 이런 문제는 뒤늦게 수정할수록 비용이 커지는 경우가 많습니다.
처음부터 출력 컨텍스트에 맞는 처리 방식을 익혀두면 유지보수와 안정성 측면에서 도움이 됩니다.
직접 구현하기보다 언어와 프레임워크에서 제공하는 표준 이스케이프 기능을 우선 활용하고, 빠르게 결과를 검토하거나 변환이 필요한 경우에는 온라인 도구를 함께 활용해보세요.
비볼디 HTML 이스케이프 도구는 이스케이프, 언이스케이프, 출력 형식 전환, 코드 내보내기 등 HTML 변환과 검토에 필요한 기능을 한 화면에서 사용할 수 있습니다. 처음 사용하는 경우에는 샘플 기능으로 동작 방식을 빠르게 확인해볼 수 있습니다.
아래 링크에서 직접 사용해보세요. 별도 설치 없이 브라우저에서 바로 사용할 수 있습니다.
HTML 이스케이프와 함께 URL 인코딩·디코딩, Base64 인코딩·디코딩, JSON 포맷터, URL 단축 등 다양한 온라인 도구도 비볼디에서 함께 사용할 수 있습니다.
