SCSS 컴파일 개념

SCSS 컴파일이란?

컴파일(Compile)은 SCSS 코드를 브라우저가 이해할 수 있는 표준 CSS 코드로 변환하는 과정입니다.
SCSS는 전처리기 언어이므로, 반드시 컴파일 단계를 거쳐야 실제 웹 페이지에 적용할 수 있습니다.

컴파일의 필요성

브라우저는 SCSS 문법을 직접 해석하지 못합니다. 변수, 중첩, 믹스인 같은 SCSS 기능은 브라우저가 이해할 수 없기 때문입니다.
따라서 SCSS 파일을 작성한 후에는 반드시 표준 CSS로 변환해야 브라우저가 스타일을 적용할 수 있습니다.

								// style.scss
								$primary-color: #0a58ca;

								.button {
								  background: $primary-color;
								  &:hover {
								    background: darken($primary-color, 10%);
								  }
								}

								/* style.css */
								.button {
								  background: #0a58ca;
								}
								.button:hover {
								  background: #084298;
								}

위 예시처럼 SCSS의 변수와 중첩 문법이 표준 CSS로 변환되어 브라우저가 이해할 수 있는 형태가 됩니다.
컴파일러는 변수를 실제 값으로 치환하고, 중첩된 선택자를 평탄화하며, 믹스인을 실제 CSS 코드로 확장합니다.

컴파일러의 역할

SCSS 컴파일러는 다음과 같은 작업을 수행합니다:

변수 치환: $variable을 실제 값으로 변환
중첩 해제: 중첩된 선택자를 평탄한 CSS 선택자로 변환
믹스인 확장: @mixin을 실제 CSS 코드로 확장
파셜 병합: @use로 불러온 파일들을 하나로 합침
연산 처리: 수치 연산, 색상 함수 등을 계산하여 결과값으로 변환

이러한 변환 과정을 통해 개발자가 작성한 SCSS 코드가 최종적으로 표준 CSS가 됩니다.

SCSS 컴파일 방법

SCSS를 컴파일하는 방법은 여러 가지가 있습니다. 프로젝트 환경과 요구사항에 맞는 방법을 선택하면 됩니다.
간단한 학습용 프로젝트에서는 에디터 확장만으로도 충분하지만, 실무에서는 보통 빌드 도구나 CLI를 함께 사용해 자동화된 컴파일 흐름을 구성합니다.

빌드 도구를 이용한 컴파일

Gulp, Webpack, Vite 같은 빌드 도구를 사용하면 파일 저장 시 자동으로 컴파일되도록 설정할 수 있습니다.
대규모 프로젝트나 팀 프로젝트에서는 빌드 도구를 사용하는 것이 일반적입니다.

Gulp를 이용한 컴파일

Gulp는 gulp-sass 플러그인을 통해 SCSS를 컴파일합니다.

									const gulp = require('gulp');
									const sass = require('gulp-sass')(require('sass'));

									gulp.task('sass', function() {
									  return gulp.src('scss/**/*.scss')
									    .pipe(sass().on('error', sass.logError))
									    .pipe(gulp.dest('css'));
									});

									gulp.task('watch', function() {
									  gulp.watch('scss/**/*.scss', gulp.series('sass'));
									});

이 설정으로 gulp sass 명령을 실행하면 scss 폴더의 모든 SCSS 파일이 css 폴더로 컴파일됩니다.
gulp watch를 실행하면 파일 변경 시 자동으로 컴파일됩니다.

UXKM Gulp 커리큘럼 바로가기 UXKM Gulp > SCSS 컴파일 바로가기

Webpack을 이용한 컴파일

Webpack은 sass-loader를 통해 SCSS를 컴파일합니다.

									module.exports = {
									  module: {
									    rules: [
									      {
									        test: /\.scss$/,
									        use: [
									          'style-loader',
									          'css-loader',
									          'sass-loader'
									        ]
									      }
									    ]
									  }
									};

Webpack은 모듈 번들러이므로, SCSS 파일을 JavaScript 모듈처럼 import하여 사용할 수 있습니다.

VS Code 확장 프로그램

VS Code에서 "Live Sass Compiler" 같은 확장 프로그램을 설치하면, 에디터에서 바로 컴파일할 수 있습니다.
작은 프로젝트나 학습 목적에는 이 방법이 간편합니다.

확장 프로그램
설명
설치 방법

Live Sass Compiler

파일 저장 시 자동으로 SCSS를 CSS로 컴파일하고, Live Reload 기능 제공

VS Code 확장 프로그램에서 "Live Sass Compiler" 검색 후 설치
Sass

SCSS 문법 하이라이팅과 자동 완성 기능 제공

VS Code 확장 프로그램에서 "Sass" 검색 후 설치

VS Code 확장 프로그램은 별도의 설정 없이 바로 사용할 수 있어 초보자에게 적합합니다.
다만 프로젝트 규모가 커지면 빌드 도구를 사용하는 것이 더 효율적입니다.

Sass CLI (명령줄 도구)

Sass 공식 CLI 도구를 사용하면 터미널에서 직접 컴파일할 수 있습니다.
Node.js가 설치되어 있다면 npm을 통해 설치할 수 있습니다.

								// Sass CLI 설치
								npm install -g sass

								// 단일 파일 컴파일
								sass input.scss output.css

								// 폴더 전체 컴파일 (변경 감지)
								sass --watch scss:css

CLI 도구는 빌드 도구 없이 간단하게 컴파일하고 싶을 때 유용합니다.
--watch 옵션을 사용하면 파일 변경 시 자동으로 재컴파일됩니다.

온라인 컴파일러

웹 브라우저에서 바로 사용할 수 있는 온라인 SCSS 컴파일러도 있습니다.
간단한 테스트나 학습 목적으로 사용하기 좋습니다.

CodePen: SCSS를 지원하는 온라인 코드 에디터
CodePen 바로가기
JSFiddle: SCSS를 지원하는 온라인 코드 에디터
JSFiddle 바로가기

온라인 컴파일러는 설치나 설정 없이 바로 사용할 수 있지만, 대규모 프로젝트에는 적합하지 않습니다.

컴파일 옵션

SCSS 컴파일 시 다양한 옵션을 설정하여 출력 결과를 제어할 수 있습니다.
출력 스타일, 소스맵, 인클루드 경로 같은 옵션을 이해해 두면, 개발 환경과 배포 환경에서 각기 다른 형태의 CSS를 손쉽게 만들어낼 수 있습니다.

출력 스타일 (Output Style)

컴파일된 CSS의 포맷 형식을 선택할 수 있습니다.

스타일
설명
용도

expanded

읽기 쉬운 형식, 들여쓰기와 줄바꿈 포함

개발 환경, 디버깅
compressed

모든 공백 제거, 한 줄로 압축

프로덕션 환경, 파일 크기 최소화
compact

각 규칙을 한 줄로 표시

중간 형식
nested

중첩 구조를 유지한 형식

중첩 구조 확인

								sass({
								  outputStyle: 'expanded'  // 또는 'compressed', 'compact', 'nested'
								})

소스맵 (Source Map)

소스맵은 컴파일된 CSS와 원본 SCSS 파일을 연결해주는 파일입니다.
브라우저 개발자 도구에서 원본 SCSS 파일의 위치를 확인할 수 있게 해줍니다.

								sass({
								  sourceMap: true,
								  sourceMapContents: true
								})

소스맵을 사용하면 디버깅이 훨씬 쉬워집니다.
브라우저 개발자 도구에서 스타일을 확인할 때, 컴파일된 CSS가 아닌 원본 SCSS 파일의 줄 번호를 볼 수 있습니다.

인클루드 경로 (Include Paths)

@use나 @import로 파일을 불러올 때 검색할 경로를 지정할 수 있습니다.

								sass({
								  includePaths: [
								    'node_modules',
								    'scss'
								  ]
								})

이렇게 설정하면 @use "variables"처럼 상대 경로 없이도 파일을 불러올 수 있습니다.

컴파일 과정 상세 예시

실제 SCSS 코드가 어떻게 CSS로 변환되는지 단계별로 살펴봅니다.
변수 치환, 중첩 해제, 믹스인 확장, 파셜 병합이 각각 어떤 형태의 CSS로 바뀌는지 눈으로 확인해 보면, 추상적인 개념이 아닌 “코드 수준에서 일어나는 변화”를 직관적으로 이해할 수 있습니다.

변수 치환

SCSS 변수는 컴파일 시 실제 값으로 치환됩니다.

_variables.scss

									$primary-color: #0a58ca;
									$font-size-base: 16px;
									$spacing: 8px;

style.scss

									@use "variables";

									.button {
									  background: variables.$primary-color;
									  font-size: variables.$font-size-base;
									  padding: variables.$spacing;
									}

컴파일된 style.css

									.button {
									  background: #0a58ca;
									  font-size: 16px;
									  padding: 8px;
									}

중첩 해제

중첩된 선택자는 평탄한 CSS 선택자로 변환됩니다.

								.card {
								  padding: 16px;

								  .card__title {
								    font-size: 18px;
								  }

								  .card__body {
								    margin-top: 8px;
								  }
								}

								.card {
								  padding: 16px;
								}
								.card .card__title {
								  font-size: 18px;
								}
								.card .card__body {
								  margin-top: 8px;
								}

믹스인 확장

믹스인은 컴파일 시 실제 CSS 코드로 확장됩니다.

_mixins.scss

									@mixin flex-center {
									  display: flex;
									  align-items: center;
									  justify-content: center;
									}

style.scss

									@use "mixins";

									.button-group {
									  @include mixins.flex-center;
									}

컴파일된 style.css

									.button-group {
									  display: flex;
									  align-items: center;
									  justify-content: center;
									}

파셜 병합

여러 파셜 파일을 불러오면 하나의 CSS 파일로 병합됩니다.

								@use "variables";
								@use "mixins";
								@use "components/buttons";
								@use "components/cards";
								@use "layout/header";

이렇게 불러온 모든 파일의 내용이 하나의 main.css 파일로 합쳐집니다.
HTML에서는 이 하나의 CSS 파일만 연결하면 됩니다.

컴파일 시 주의사항

SCSS 컴파일은 대부분 자동으로 진행되지만, 몇 가지 주의해야 할 사항이 있습니다.
컴파일 과정에서 발생할 수 있는 문제를 미리 알고 대비하면, 개발 시간을 절약하고 실수를 줄일 수 있습니다.

특히 초보자라면 컴파일이 실패했을 때 어디서 문제가 발생했는지 파악하는 것이 중요합니다.
에러 메시지를 제대로 읽고 해석할 수 있으면, 문법 오류나 설정 문제를 빠르게 해결할 수 있습니다.

컴파일 전 파일 저장 확인

SCSS 파일을 수정한 후에는 반드시 저장해야 컴파일이 실행됩니다.
자동 컴파일이 설정되어 있어도 파일이 저장되지 않으면 변경사항이 반영되지 않습니다.

에디터의 자동 저장 기능을 활성화하면 파일 수정 시 자동으로 저장되어 컴파일이 즉시 실행됩니다.
VS Code: File → Auto Save
WebStorm: File → Settings → Appearance & Behavior → System Settings → Save files automatically

만약 컴파일이 실행되지 않는다면, 파일이 제대로 저장되었는지 확인하고 필요시 수동으로 저장(Ctrl+S 또는 Cmd+S)을 해보세요.

컴파일 에러 확인 및 해결

SCSS 문법 오류가 있으면 컴파일이 실패합니다.
터미널이나 에디터의 에러 메시지를 정확히 읽고 해석하면 문제를 빠르게 해결할 수 있습니다.

일반적인 컴파일 에러 유형

다음은 자주 발생하는 컴파일 에러와 해결 방법입니다.

에러: 변수명 오타
$primary-color: #0a58ca; .button { background: $primary-colr; // 오타: $primary-color가 아님 }

에러 메시지: Undefined variable: "$primary-colr"
해결 방법: 변수명을 정확히 확인하고 오타를 수정합니다. 에디터의 자동 완성 기능을 활용하면 오타를 줄일 수 있습니다.
에러: 중괄호 누락
.button { background: #0a58ca; // 닫는 중괄호 누락

에러 메시지: Expected "}"
해결 방법: 열린 중괄호와 닫힌 중괄호의 개수를 확인하고, 누락된 중괄호를 추가합니다. 에디터의 중괄호 하이라이팅 기능을 활용하면 쉽게 찾을 수 있습니다.
에러: 세미콜론 누락
.button { background: #0a58ca // 세미콜론 누락 padding: 8px 16px; }

에러 메시지: Expected ";"
해결 방법: 각 CSS 속성 선언 뒤에 세미콜론을 추가합니다. 에디터의 자동 포맷팅 기능을 사용하면 자동으로 추가됩니다.
에러: 존재하지 않는 파일 불러오기
// @use "nonexistent-file";

에러 메시지: Can't find stylesheet to import
해결 방법: 파일 경로와 파일명을 정확히 확인합니다. 파셜 파일은 _ 접두사와 확장자를 생략하고 불러옵니다.

에러 메시지 읽는 방법

에러 메시지는 보통 다음과 같은 형식으로 표시됩니다:

									Error: Undefined variable: "$primary-colr"
									  ╷
									3 │   background: $primary-colr;
									  │              ^^^^^^^^^^^^^^
									  ╵
									  scss/components/_button.scss 3:15  root stylesheet

에러 유형: "Error: Undefined variable" - 어떤 종류의 에러인지 알려줍니다
에러 위치: 줄 번호와 열 번호 (3:15) - 어디서 에러가 발생했는지 정확히 표시
파일 경로: "scss/components/_button.scss" - 어떤 파일에서 에러가 발생했는지 표시
에러가 난 코드: ^ 표시로 정확한 위치를 가리킴

에러 메시지를 읽을 때는 파일 경로와 줄 번호를 먼저 확인하고, 해당 위치의 코드를 살펴보면 문제를 빠르게 찾을 수 있습니다.

개발/프로덕션 환경 분리

개발 환경과 프로덕션 환경에서는 서로 다른 컴파일 설정을 사용하는 것이 좋습니다.
개발 중에는 디버깅이 쉬운 형식을, 배포 시에는 최적화된 형식을 사용합니다.

환경
출력 스타일
소스맵
이유

개발 환경

expanded 또는 nested

활성화

읽기 쉬운 코드, 디버깅 용이, 원본 SCSS 위치 확인 가능
프로덕션 환경

compressed

비활성화 (선택)

파일 크기 최소화, 로딩 속도 향상, 보안 (소스 코드 숨김)

Gulp에서 환경별 설정 예시

Gulp에서는 환경 변수나 별도의 설정 파일을 통해 개발/프로덕션 환경을 구분할 수 있습니다.

									const isDev = process.env.NODE_ENV !== 'production';

									sass({
									  outputStyle: isDev ? 'expanded' : 'compressed',
									  sourceMap: isDev
									})

이렇게 설정하면 NODE_ENV=production으로 실행할 때만 압축된 CSS가 생성됩니다.

파일 경로 및 출력 경로 확인

컴파일 설정에서 입력 파일 경로와 출력 파일 경로를 정확히 지정해야 합니다.
경로가 잘못되면 컴파일이 실패하거나 예상치 못한 위치에 파일이 생성될 수 있습니다.

상대 경로 vs 절대 경로: 프로젝트 루트를 기준으로 한 상대 경로를 사용하는 것이 일반적입니다
와일드카드 사용: scss/**/*.scss처럼 모든 하위 폴더의 SCSS 파일을 포함할 수 있습니다
제외 경로 설정: node_modules나 .git 폴더는 컴파일에서 제외하는 것이 좋습니다

컴파일 후 생성된 CSS 파일의 위치를 확인하고, HTML에서 올바른 경로로 연결되어 있는지 확인하세요.

캐시 문제 해결

브라우저나 빌드 도구가 이전에 컴파일된 CSS 파일을 캐시하고 있을 수 있습니다.
변경사항이 반영되지 않는다면 캐시를 지우고 다시 컴파일해보세요.

브라우저 캐시: 개발자 도구에서 "Disable cache" 옵션 활성화 또는 Ctrl+Shift+R (하드 리프레시)
빌드 도구 캐시: Gulp나 Webpack의 캐시를 지우고 다시 빌드
파일명 변경: CSS 파일명에 버전 번호를 추가하여 캐시 무효화 (style.css?v=1.0.1)

성능 최적화 팁

대규모 프로젝트에서는 컴파일 시간이 길어질 수 있습니다. 다음 팁을 활용하면 컴파일 속도를 향상시킬 수 있습니다.

증분 컴파일: 변경된 파일만 컴파일하는 방식 사용 (Gulp의 gulp-dependents 등)
불필요한 파일 제외: 컴파일 대상에서 제외할 파일을 명확히 지정
파일 구조 최적화: 너무 깊은 중첩 구조를 피하고, 필요한 파일만 불러오기
컴파일러 버전: 최신 버전의 Sass 컴파일러 사용 (성능 개선이 포함될 수 있음)

정리

SCSS 컴파일 개념에 대해 알아본 내용을 정리합니다.

컴파일 필요성: SCSS는 브라우저가 직접 읽을 수 없으므로 반드시 CSS로 변환해야 함
컴파일 방법: 빌드 도구(Gulp, Webpack), VS Code 확장 프로그램, CLI, 온라인 컴파일러 등
컴파일 옵션: 출력 스타일, 소스맵, 인클루드 경로 등을 설정 가능
변환 과정: 변수 치환, 중첩 해제, 믹스인 확장, 파셜 병합 등이 자동으로 수행됨

다음 페이지에서는 VS Code와 WebStorm에서 SCSS를 사용하는 방법을 상세히 알아봅니다.