안녕하세요! 프론트엔드 개발자라는 멋진 목표를 향해 달려가고 계신 것을 환영합니다. 오늘 우리가 다룰 주제는 실무에서 정말, 진짜, 너무나도 중요한 CSS 디버깅(Debugging CSS)입니다.
화면을 만들다 보면 상태 관리 라이브러리(예: Zustand)로 데이터는 완벽하게 업데이트했는데, 화면에 보이는 UI 스타일이 깨지거나 내가 원하는 대로 요소가 배치되지 않아 당황스러운 순간이 반드시 옵니다. Next.js로 멋진 구조를 짜놓고도 CSS 때문에 끙끙 앓는 일이 생기죠. 오늘 이 공식 문서를 꼼꼼히 번역해 드리면서, 제가 실무에서 겪었던 팁들을 팍팍 뿌려드릴게요. 자, 시작해봅시다!
CSS 디버깅하기 (Debugging CSS)
- 이전: 홈페이지 색상 테마 정하기 (Home color scheme search)
- 목차: CSS 스타일링 기초 개요 (Overview: CSS styling basics)
- 다음: 텍스트 스타일링 (Text styling)
CSS를 작성하다 보면 가끔 내 CSS가 생각대로 동작하지 않는 문제를 마주하게 됩니다. 분명히 특정 선택자(selector)가 요소에 딱 맞게 적용되어야 한다고 생각했는데 아무 일도 일어나지 않거나, 박스 크기가 예상했던 것과 다르게 나올 때가 있죠. 이 문서는 CSS 문제를 디버깅(해결)하는 방법에 대한 가이드를 제공하고, 모든 모던 브라우저에 내장된 개발자 도구(DevTools)가 도대체 무슨 일이 일어나고 있는지 파악하는 데 어떤 도움을 주는지 보여줄 것입니다.
| 선행 조건 (Prerequisites): | 기본 HTML 구문 (Basic HTML syntax), CSS 스타일링 기초 (이 모듈의 이전 레슨들에서 다뤘습니다!) |
| 학습 목표 (Learning outcomes): |
|
브라우저 개발자 도구 접속 방법 (How to access browser DevTools)
브라우저 개발자 도구란 무엇인가 (What are browser developer tools) 문서를 보면 다양한 브라우저와 운영체제 환경에서 도구에 접속하는 방법을 알 수 있습니다. 평소에 주로 개발하는 특정 브라우저가 있어서 그 브라우저의 도구에 가장 익숙해지겠지만, 다른 브라우저들에서는 어떻게 접속하는지 알아두는 것도 가치가 있습니다. 여러 브라우저에서 화면이 다르게 렌더링되는 현상을 발견했을 때 큰 도움이 되거든요.
이 레슨에서는 CSS 작업을 위한 Firefox 개발자 도구의 몇 가지 유용한 기능들을 살펴볼 것입니다. 이를 위해 예제 파일(an example file)을 하나 사용할 텐데요. 직접 따라 해보고 싶으시다면 이 예제 파일을 새 탭에 띄운 뒤, 위에 링크된 문서에 설명된 대로 개발자 도구를 열어보세요.
💡 강사님의 실무 팁!
실무에서는 Chrome(크롬) 개발자 도구를 가장 많이 사용하긴 하지만, Firefox나 Safari에서만 발생하는 특이한 CSS 버그들도 종종 만납니다. 그래서 각 브라우저의 개발자 도구 단축키(보통F12또는Ctrl+Shift+I/ Mac은Cmd+Opt+I) 정도는 손에 익혀두시는 게 좋습니다!
DOM과 소스 보기의 차이점 (The DOM versus view source)
개발자 도구를 처음 접하는 분들이 자주 헷갈리는 부분이 있습니다. 바로 웹페이지의 소스 보기(view source)를 하거나 서버에 올린 HTML 원본 파일을 볼 때와, 개발자 도구의 HTML 패널(HTML Pane)에서 보는 화면이 다르다는 점입니다. 얼핏 보면 '소스 보기'와 비슷해 보이지만 몇 가지 결정적인 차이가 있어요.
렌더링된 DOM(Document Object Model) 안에서는 브라우저가 HTML을 정규화(normalized)했을 수 있습니다. 예를 들어, 여러분이 실수로 잘못 작성한 HTML을 브라우저가 알아서 고쳐주는 식이죠. <h2> 태그를 열어놓고 닫을 때는 실수로 </h3>로 닫았다면, 브라우저는 여러분의 의도를 파악해서 DOM 상의 HTML에서는 열려있는 <h2>를 </h2>로 올바르게 닫아줍니다. 또한 DOM은 자바스크립트(JavaScript)에 의해 변경된 모든 사항도 그대로 반영해서 보여줍니다.
이와 비교할 때, '소스 보기(View Source)'는 그저 서버에 저장되어 있던 날것의 HTML 소스 코드일 뿐입니다. 개발자 도구에 있는 HTML 트리(HTML tree)는 특정 순간에 브라우저가 화면에 렌더링하고 있는 '정확한 현재 상태'를 보여주므로, 지금 화면에서 진짜 무슨 일이 벌어지고 있는지 파악할 수 있는 통찰력을 제공합니다.
💡 강사님의 보충 설명!
이 부분은 Next.js 같은 모던 프레임워크를 다룰 때 극명하게 체감됩니다. 브라우저에서 '페이지 소스 보기'를 하면 초기 서버에서 내려준 정적인 HTML만 보이지만, 개발자 도구의 '요소(Elements/Inspector)' 탭을 보면 React가 실행되고 상태가 변경되면서 동적으로 생성된 복잡한 태그 구조들이 다 보이죠. 그래서 디버깅할 때는 무조건 개발자 도구의 DOM 트리를 봐야 합니다!
적용된 CSS 검사하기 (Inspecting the applied CSS)
페이지에서 요소를 하나 선택해 보세요. 요소를 우클릭(또는 ctrl+클릭)하고 검사(Inspect)를 누르거나, 개발자 도구 화면 왼쪽에 있는 HTML 트리에서 직접 요소를 클릭해서 선택할 수도 있습니다. box1이라는 클래스를 가진 요소를 선택해 보세요. 이 요소는 테두리가 그려진 박스 중 페이지의 첫 번째 요소입니다.
HTML 옆(또는 아래)에 있는 규칙 뷰(Rules view)를 보면 해당 요소에 적용된 CSS 속성과 값들을 볼 수 있습니다. box1 클래스에 직접 적용된 규칙뿐만 아니라 조상 요소(이 경우 <body>)로부터 상속받은 CSS도 보일 겁니다. 이것은 내가 예상치 못한 CSS가 어디선가 굴러들어와 적용되고 있을 때 아주 유용합니다. 아마 부모 요소로부터 상속받은 스타일일 텐데, 그럴 때는 이 요소의 문맥에 맞게 덮어쓰기(overwrite) 위한 규칙을 새로 추가해야겠죠.
또 유용한 기능 중 하나는 축약형(shorthand) 속성을 펼쳐서 볼 수 있는 기능입니다. 우리 예제에서는 margin 축약형이 사용되었습니다.
작은 화살표를 클릭하여 뷰를 확장하면, 각 개별 속성(longhand properties)과 그 값들이 풀려서 나타나는 것을 볼 수 있습니다.
규칙 뷰(Rules view)가 활성화되어 있을 때 이 값들을 켜거나 끌(toggle) 수 있습니다 — 마우스를 올리면 체크박스가 나타납니다. 예를 들어 border-radius 규칙의 체크박스를 해제하면 해당 CSS의 적용이 멈추게 됩니다.
이 기능을 사용하면 규칙이 적용되었을 때와 아닐 때를 비교(A/B 비교)하여 어떤 게 더 나은지 결정할 수도 있고, 디버깅을 할 때도 유용합니다. 예를 들어 레이아웃이 완전히 깨졌을 때 도대체 어떤 속성이 문제를 일으키고 있는지 찾아낼 때 말이죠.
값 수정하기 (Editing values)
속성을 켜고 끄는 것 외에도 값을 직접 편집할 수 있습니다. 다른 색상이 더 잘 어울릴지 확인해보고 싶거나 어떤 요소의 크기를 미세하게 조정하고 싶으신가요? 개발자 도구를 사용하면 텍스트 에디터에서 스타일시트를 일일이 수정하고 페이지를 새로고침하는 시간을 엄청나게 아낄 수 있습니다.
box1이 선택된 상태에서 테두리에 적용된 색상을 보여주는 견본(작은 색상 원)을 클릭해 보세요. 색상 선택기(color picker)가 열리고 다양한 색상들을 적용해 볼 수 있으며, 페이지에 실시간으로 업데이트됩니다. 비슷한 방식으로 테두리의 두께(width)나 스타일(style)도 변경해 볼 수 있습니다.
새로운 속성 추가하기 (Adding a new property)
개발자 도구를 사용해 아예 새로운 속성을 추가할 수도 있습니다. 혹시 박스가 <body> 요소의 폰트 크기를 그대로 상속받지 않고 독자적인 폰트 크기를 가졌으면 좋겠다고 생각하셨나요? 실제 CSS 파일에 코드를 적어넣기 전에 개발자 도구에서 먼저 테스트해 볼 수 있습니다.
해당 규칙(rule)의 닫는 중괄호(})를 클릭하면 새로운 선언을 입력할 수 있게 됩니다. 이때 새로운 속성 이름을 타이핑하기 시작하면 개발자 도구가 일치하는 속성들의 자동완성 목록을 보여줄 거예요. font-size를 선택한 후 테스트해 보고 싶은 값을 입력해 보세요. 또한 + 버튼을 클릭해서 동일한 선택자를 가진 규칙을 아예 새로 하나 더 추가하고, 거기에 새 규칙들을 넣을 수도 있습니다.
참고:
규칙 뷰(Rules view)에는 다른 유용한 기능들도 많습니다. 예를 들어, 유효하지 않은 잘못된 값을 가진 선언은 취소선(가로줄)이 그어집니다. 더 자세한 내용은 CSS 검사 및 편집(Examine and edit CSS)에서 확인하실 수 있습니다.
박스 모델 이해하기 (Understanding the box model)
이전 레슨들에서 우리는 박스 모델(the box model)에 대해 논의했고, 부여한 크기에 패딩과 테두리를 더해 요소의 크기를 계산하는 방식을 바꾸는 '대체 박스 모델(alternate box model)'이 존재한다는 사실을 배웠습니다. 개발자 도구는 요소의 크기가 도대체 어떻게 계산되고 있는지 명확하게 이해할 수 있도록 엄청난 도움을 줍니다.
레이아웃 뷰(Layout view)는 선택된 요소의 박스 모델 다이어그램을 보여주며, 요소의 배치를 결정짓는 속성과 값들에 대한 설명을 함께 제공합니다. 심지어 여러분이 명시적으로 작성하지 않았더라도 브라우저에 의해 초기값(initial values)이 설정되어 있는 속성들까지도 다 보여줍니다.
이 패널에서 자세히 볼 수 있는 속성 중 하나가 바로 요소가 어떤 박스 모델을 사용할지 제어하는 box-sizing 속성입니다.
클래스가 box1인 요소와 box2인 요소 두 개를 비교해 보세요. 둘 다 동일한 너비(400px)가 적용되어 있지만, 시각적으로는 box1이 더 넓어 보입니다. 레이아웃 패널에서 확인해 보면 box1은 content-box를 사용하고 있는 것을 알 수 있습니다. 이 값은 여러분이 부여한 크기(400px)에다가 패딩과 테두리 두께를 추가로 바깥에 덧붙여서 계산하는 방식입니다.
반면 box2 클래스를 가진 요소는 border-box를 사용하고 있습니다. 여기서는 패딩과 테두리가 여러분이 요소에 지정한 크기 '안쪽으로' 깎여 들어갑니다(파고듭니다). 즉, 이 박스가 페이지에서 차지하는 공간의 크기는 여러분이 지정한 크기인 width: 400px과 완전히 정확히 일치한다는 뜻입니다.
참고:
박스 모델에 대해 더 자세히 알아보려면 박스 모델 검사 및 확인(Examining and Inspecting the Box Model)을 참고하세요.
명시도 문제 해결하기 (Solving specificity issues)
개발을 하다 보면, 특히 기존에 이미 만들어진 사이트의 CSS를 수정해야 할 때, 아무리 CSS를 적어도 도무지 적용이 안 돼서 쩔쩔매는 상황을 겪게 될 것입니다. 무슨 짓을 해도 해당 요소가 그 CSS를 뱉어내는(?) 것처럼 보이죠. 이런 현상의 대부분은 '더 높은 명시도(more specific)'를 가진 다른 선택자가 여러분의 변경 사항을 덮어쓰고(overriding) 있기 때문입니다. 이때 개발자 도구가 진가를 발휘합니다.
우리 예제 파일에는 <em> 요소로 감싸진 두 개의 단어가 있습니다. 하나는 주황색(orange)으로 표시되고, 다른 하나는 핫핑크(hotpink)로 표시됩니다. 우리가 적용한 CSS는 다음과 같습니다:
em {
color: hotpink;
font-weight: bold;
}하지만 스타일시트 위쪽을 보면 .special 선택자를 가진 규칙이 하나 더 있습니다:
.special {
color: orange;
}명시도에 대해 다루었던 충돌 다루기(handling conflicts) 레슨을 기억하신다면 아시겠지만, 클래스(class) 선택자는 요소(element, 태그) 선택자보다 구체적(명시도가 높음)이므로 이 값이 적용되는 것입니다. 정보가 거대한 스타일시트 어딘가에 파묻혀 있을 때 개발자 도구는 이런 충돌을 찾아내는 데 큰 도움을 줍니다.
.special 클래스를 가진 <em> 요소를 검사해 보세요. 개발자 도구는 오렌지색이 적용되고 있음을 보여줄 것이고, 동시에 <em> 태그 자체에 적용된 color 속성은 취소선(가로줄)이 그어져 있는 것을 볼 수 있습니다. 이제 여러분은 클래스 선택자가 요소 선택자를 덮어쓰고(overriding) 있다는 사실을 한눈에 파악할 수 있습니다.
CSS 문제 디버깅하기 (Debugging problems in CSS)
개발자 도구는 CSS 문제를 해결할 때 훌륭한 조력자 역할을 합니다. 그렇다면 CSS가 내 마음대로 동작하지 않는 상황에 처했을 때, 구체적으로 어떻게 해결해 나가야 할까요? 다음의 단계들이 도움이 될 것입니다.
문제에서 한 걸음 물러나기 (Take a step back from the problem)
코딩 문제는 무엇이든 좌절감을 줄 수 있지만, 특히 CSS 문제는 온라인에서 검색해 볼 만한 명확한 '에러 메시지(Error message)'조차 던져주지 않는 경우가 많아 더욱 답답합니다. 화가 나기 시작했다면 잠시 문제에서 한 걸음 물러나 보세요. 산책을 하거나, 음료를 마시거나, 동료와 수다를 떨거나, 잠시 다른 작업을 해보세요. 가끔은 문제에 대해 생각을 멈췄을 때 마법처럼 해결책이 떠오르기도 하고, 그렇지 않더라도 머리를 식히고 다시 작업하면 훨씬 수월해집니다.
💡 강사님의 조언!
"안 되면 잠깐 쉬고 오세요"라는 말이 뻔해 보이지만, 진짜 진리입니다. 저도 실무에서 오타 하나, z-index 숫자 하나 잘못 쓴 것 때문에 몇 시간을 날린 적이 수두룩해요. 안 풀릴 땐 커피 한 잔의 여유를!
HTML과 CSS가 유효한가요? (Do you have valid HTML and CSS?)
브라우저는 여러분의 CSS와 HTML이 올바르게 작성되어 있을 것이라 기대하지만, 동시에 매우 관대하기도 해서 마크업이나 스타일시트에 에러가 있더라도 어떻게든 페이지를 렌더링하려고 최선을 다합니다. 코드에 실수가 있으면 브라우저는 여러분의 의도를 스스로 '추측'해야 하는데, 그 추측이 여러분의 의도와 완전히 다를 수 있습니다. 게다가 두 개의 다른 브라우저가 같은 오류를 서로 다른 방식으로 처리하기도 하죠. 따라서 가장 좋은 첫걸음은 HTML과 CSS를 검사기(validator)에 돌려서 오류를 찾아내고 수정하는 것입니다.
테스트 중인 브라우저가 해당 속성과 값을 지원하나요? (Are the property and value supported by the browser you are testing in?)
브라우저는 자신이 이해하지 못하는 CSS는 그냥 무시해버립니다. 테스트 중인 브라우저가 여러분이 작성한 속성이나 값을 지원하지 않는다면 에러를 내며 화면이 박살 나지는 않지만, 해당 CSS는 아예 적용되지 않습니다. 개발자 도구는 일반적으로 이렇게 지원되지 않는 속성과 값을 어떤 식으로든 강조해서 보여줍니다. 아래 스크린샷을 보면 브라우저가 grid-template-columns의 subgrid라는 값을 지원하지 않아서 취소선이 그어져 있는 것을 볼 수 있습니다.
또한 MDN의 각 속성 페이지 하단에 있는 브라우저 호환성 표(Browser compatibility tables)를 살펴보는 것도 좋습니다. 이 표는 해당 속성에 대한 각 브라우저의 지원 여부를 보여주며, 속성의 특정 기능은 지원하지만 다른 기능은 지원하지 않는 경우도 상세히 쪼개어 설명해 줍니다. grid-template-columns 속성의 호환성 표를 확인해 보세요.
다른 무언가가 내 CSS를 덮어쓰고 있나요? (Is something else overriding your CSS?)
이때 명시도(specificity)에 대해 배운 지식이 엄청난 빛을 발하게 됩니다. 여러분이 적용하려는 스타일보다 더 구체적인(명시도가 높은) 무언가가 스타일을 덮어쓰고 있다면, 도대체 무엇이 원인인지 찾아내느라 매우 짜증 나는 게임을 하게 됩니다. 하지만 위에서 설명했듯, 개발자 도구가 어떤 CSS가 적용되고 있는지 투명하게 보여주기 때문에 이를 확인하고 새로운 선택자의 명시도를 높여서 덮어쓸 수 있도록 조치할 수 있습니다.
문제의 축소된 테스트 케이스 만들기 (Make a reduced test case of the problem)
위의 단계들로도 문제가 해결되지 않는다면 더 깊은 조사가 필요합니다. 이 시점에서 할 수 있는 가장 좋은 방법은 소위 축소된 테스트 케이스(reduced test case)를 만드는 것입니다. "이슈를 최소 단위로 줄이는" 능력은 정말, 정말 유용한 기술입니다. 본인의 코드뿐만 아니라 동료의 코드에서 문제를 찾아내는 데 도움을 주며, 누군가에게 버그를 보고하거나 도움을 요청할 때도 훨씬 효과적입니다.
축소된 테스트 케이스란, 문제와 관련 없는 주변 콘텐츠나 스타일을 모두 제거하여 해당 문제를 가장 단순하고 순수한 형태로 보여주는 코드 예제입니다. 종종 문제가 되는 코드만 실제 복잡한 레이아웃에서 쏙 빼내어 그 코드나 기능만 덩그러니 보여주는 작은 예제를 만드는 것을 의미하죠.
축소된 테스트 케이스를 만드는 방법은 다음과 같습니다:
- 마크업이 동적으로 생성되는 경우(예: React, Next.js, CMS 등을 통해) — 문제를 보여주는 정적인(static) HTML 결과물 버전만 복사해서 만드세요. CodePen과 같은 코드 공유 사이트는 온라인에서 접속하기 쉽고 동료들과 빠르게 공유할 수 있어서 축소된 테스트 케이스를 올리기에 아주 좋습니다. 우선 페이지에서 소스 보기를 한 후 HTML을 CodePen에 복사하고, 관련된 CSS와 JavaScript만 가져와서 포함해 보세요. 그런 다음 그 환경에서도 여전히 문제가 발생하는지 확인합니다.
- JavaScript를 제거했는데도 문제가 사라지지 않는다면, JavaScript를 아예 포함하지 마세요. 반대로 JavaScript를 제거했더니 문제가 사라진다면, 문제를 일으키는 핵심 코드만 남기고 나머지 불필요한 JavaScript는 최대한 지워버리세요.
- 문제 발생에 원인을 제공하지 않는 HTML은 모두 제거하세요. 연관 없는 컴포넌트나 레이아웃의 메인 요소들까지 싹 다 지워버리세요. 거듭 말하지만, 버그가 재현되는 '가장 적은 양의 코드'만 남기는 것이 핵심입니다.
- 문제에 영향을 주지 않는 CSS도 모두 제거하세요.
이 과정을 거치다 보면 무언가를 제거했을 때 문제가 사라지고 다시 넣었을 때 문제가 발생하는 것을 보며 '아, 이게 원인이었구나!' 하고 스스로 깨닫게 되는 경우가 굉장히 많습니다. 원인을 발견할 때마다 코드에 주석(comments)을 달아두는 것도 좋은 습관입니다. 만약 다른 사람에게 도움을 요청하게 되더라도, 여러분이 이미 시도해 본 것들을 주석으로 보여줄 수 있으니까요. 이를 통해 검색 키워드를 얻거나 우회 방법(workarounds)을 찾아낼 수도 있습니다.
여전히 문제를 해결하는 데 어려움을 겪고 있더라도, 축소된 테스트 케이스가 있으면 포럼에 글을 올리거나 동료에게 보여줄 때 훨씬 질문하기가 좋습니다. 도움을 요청하기 전에 문제를 스스로 축소하고 정확히 어디서 에러가 터지는지 식별하는 노력을 보여주면, 상대방도 훨씬 더 기꺼이 도와주려 할 것입니다. 경험이 많은 개발자라면 단번에 문제를 파악하고 올바른 방향을 제시해 줄 수 있으며, 설령 바로 답을 모르더라도 최소한 빠르게 훑어보고 몇 가지 조언이라도 건넬 수 있게 됩니다.
만약 여러분의 문제가 실제 '브라우저 자체의 버그'로 판명 난 경우, 이 축소된 테스트 케이스는 해당 브라우저 제조사(예: Mozilla의 bugzilla 사이트)에 버그 리포트를 제출하는 용도로도 곧바로 쓰일 수 있습니다.
CSS 경험이 쌓일수록 문제를 파악하고 해결하는 속도는 점점 빨라질 것입니다. 하지만 아무리 경험이 많은 고수라도 가끔은 "도대체 세상에 이게 왜 이러는 거지?" 하며 머리를 쥐어뜯을 때가 있답니다. 체계적이고 논리적인 접근법을 취하고, 축소된 테스트 케이스를 만들고, 다른 사람에게 문제를 설명(고무오리 디버깅!)하다 보면 대개 해결책을 찾을 수 있을 겁니다.
요약 (Summary)
자, 이렇게 해서 CSS 디버깅에 대한 소개를 마칩니다! 이 지식들은 앞으로 여러분의 커리어 내내 CSS뿐만 아니라 다른 모든 종류의 코드를 디버깅할 때 두고두고 써먹을 수 있는 아주 유용한 기초 체력이 되어줄 것입니다.
이로써 이 모듈의 모든 레슨이 끝났습니다. 마무리를 위해, 다음 시간에는 지금까지 다룬 주제들에 대해 얼마나 잘 이해했는지 확인해 볼 수 있는 몇 가지 도전 과제(테스트)가 준비되어 있습니다.
같이 보기 (See also)
- Firefox > CSS 검사 및 편집(Examine and edit CSS), Firefox Source Docs
- Chrome > CSS 확인 및 변경(View and change CSS), developer.chrome.com
- 이전: 홈페이지 색상 테마 정하기 (Home color scheme search)
- 목차: CSS 스타일링 기초 개요 (Overview: CSS styling basics)
- 다음: 텍스트 스타일링 (Text styling)
MDN 개선에 도움을 주세요 (Help improve MDN)
기여하는 방법 알아보기 (Learn how to contribute)
이 페이지의 마지막 수정일은 Oct 30, 2025 이며, MDN 기여자들(MDN contributors)에 의해 작성되었습니다.
어떠신가요? 이번 레슨을 통해 브라우저 개발자 도구와 꽤 친해지셨기를 바랍니다. 상태 관리 라이브러리 값은 바뀌는데 화면이 그대로라면, 이제 당황하지 않고 F12를 눌러 Element 패널부터 확인해 보세요! 또 궁금한 점이나 다음 테스트로 넘어가기 전 복습하고 싶은 부분이 있다면 언제든 편하게 물어보세요.
