Tailwind CSS Unknown at rule 경고 해결: VS Code와 PostCSS 설정 확인하기

• 경고가 Tailwind 설치 실패는 아닌 이유
• VS Code에서만 경고가 보이는 경우
• PostCSS 설정을 확인해야 하는 경우
• Tailwind v3와 v4 설정을 섞지 않기
• 다시 확인할 체크리스트
• 정리

경고가 Tailwind 설치 실패는 아닌 이유

Tailwind CSS를 설치하고 전역 CSS 파일을 열었을 때 @tailwind, @apply, @import "tailwindcss" 근처에 노란 밑줄이 보이면 설치가 잘못된 것처럼 느껴질 수 있습니다. 경고 문구도 Unknown at rule이라서 CSS 문법 자체가 틀렸다고 받아들이기 쉽습니다.

다만 이 경고는 발생 위치를 먼저 나눠야 합니다. 하나는 VS Code의 CSS 검사기가 Tailwind 전용 지시어를 모르는 경우이고, 다른 하나는 빌드 과정에서 PostCSS가 Tailwind를 처리하지 못하는 경우입니다. 둘은 화면에 비슷하게 보이지만 손봐야 할 파일이 다릅니다.

브라우저 화면에는 Tailwind 클래스가 정상 적용되고 터미널에도 오류가 없다면 에디터 인식 문제일 가능성이 큽니다. 반대로 npm run dev나 npm run build에서 PostCSS 관련 오류가 함께 나온다면 VS Code 설정만 바꿔서는 해결되지 않습니다.

처음에는 노란 밑줄 자체보다 스타일이 실제로 만들어지는지 보는 편이 빠릅니다. 버튼에 bg-blue-500 같은 클래스를 붙였는데 화면 색상이 바뀐다면 Tailwind 빌드가 동작하고 있을 가능성이 높습니다. 화면도 그대로이고 터미널에도 오류가 있다면 프로젝트 설정 쪽으로 넘어가야 합니다.

보이는 증상	먼저 볼 위치	판단 기준
VS Code에서만 노란 밑줄이 보임	에디터 설정	화면 스타일과 빌드가 정상인지 확인
터미널에도 PostCSS 오류가 나옴	프로젝트 설정	postcss.config와 Tailwind 버전 확인
클래스 자동완성이 전혀 안 됨	확장 프로그램	Tailwind CSS IntelliSense와 파일 모드 확인

경고를 없애는 설정은 원인을 확인한 뒤 적용하는 정리 단계에 가깝습니다. 이 순서를 건너뛰면 경고는 사라졌는데 스타일은 여전히 적용되지 않는 상황이 생깁니다.

VS Code에서만 경고가 보이는 경우

VS Code는 CSS 파일을 열면 기본 CSS 검사 기능으로 문법을 확인합니다. 표준 CSS의 @media, @supports 같은 at-rule은 알고 있지만, Tailwind가 빌드 과정에서 처리하는 전용 지시어는 기본 CSS 문법만으로는 모를 수 있습니다.

이 상황에서는 Tailwind CSS IntelliSense 확장 프로그램이 설치되어 있는지부터 확인합니다. 이 확장은 클래스 자동완성, 문법 강조, Tailwind 관련 lint 기능을 보강합니다. 설치 후에도 반영되지 않는다면 VS Code 창을 다시 로드하거나, CSS 파일이 실제 프로젝트 루트 안에 있는지 봐야 합니다.

VS Code 경고만 숨기는 설정

{
    "css.lint.unknownAtRules": "ignore",
    "scss.lint.unknownAtRules": "ignore",
    "less.lint.unknownAtRules": "ignore"
}

이 설정은 VS Code의 기본 CSS lint 경고를 줄이는 방법입니다. Tailwind 빌드 문제를 고치는 설정은 아닙니다. 화면에 스타일이 적용되고 터미널 오류가 없다는 점을 확인한 뒤 적용해야 합니다.

팀 프로젝트라면 이 설정을 저장소에 포함할지도 따로 판단해야 합니다. 개인 작업 환경에서만 밑줄을 숨기고 싶다면 사용자 설정에 두는 편이 낫고, 프로젝트 구성상 Tailwind 지시어를 계속 사용하는 구조라면 워크스페이스 설정으로 관리할 수 있습니다.

@apply를 CSS 파일 안에서 쓸 때도 같은 경고가 자주 보입니다. 예를 들어 버튼이나 폼 요소를 공통 스타일로 묶으려고 @apply를 작성했는데 VS Code가 이를 알 수 없는 at-rule로 표시할 수 있습니다. 이때도 실제 CSS가 생성되는지 확인하면 원인을 좁힐 수 있습니다.

파일 언어 모드도 같이 확인하기

의외로 자주 놓치는 부분이 파일 언어 모드입니다. globals.css 파일이 CSS가 아닌 Plain Text로 열려 있거나, 확장 프로그램 충돌로 Tailwind 인식이 제대로 동작하지 않을 수 있습니다. VS Code 오른쪽 아래의 언어 모드가 CSS, SCSS, PostCSS 등 의도한 형식인지 확인해야 합니다.

단순한 경고라면 프로젝트 실행에는 영향을 주지 않습니다. 하지만 같은 파일에서 자동완성도 안 되고, Tailwind 클래스 정렬이나 lint도 전혀 반응하지 않는다면 확장 프로그램이 프로젝트를 제대로 인식하지 못하는 상태일 수 있습니다.

PostCSS 설정을 확인해야 하는 경우

터미널에 오류가 함께 나온다면 에디터 경고와 다른 문제입니다. Tailwind는 CSS 파일에 적힌 지시어를 그대로 브라우저에 보내는 것이 아니라, 빌드 도구와 PostCSS 과정에서 실제 CSS로 변환합니다. 이 처리 과정이 연결되지 않으면 @import "tailwindcss"나 @tailwind를 써도 최종 스타일이 제대로 나오지 않습니다.

Tailwind CSS v4에서 PostCSS를 사용하는 프로젝트라면 @tailwindcss/postcss 플러그인 설정을 확인해야 합니다. 예전 자료를 보고 tailwindcss를 PostCSS 플러그인처럼 직접 넣은 상태라면 v4 기준과 맞지 않아 오류가 날 수 있습니다.

Tailwind CSS v4 기준 PostCSS 설정

export default {
    plugins: {
        "@tailwindcss/postcss": {},
    },
};

파일명은 프로젝트 설정에 따라 postcss.config.mjs, postcss.config.js처럼 다를 수 있습니다. 여기서 봐야 할 지점은 현재 Tailwind 버전에서 요구하는 플러그인 이름과 설정 방식이 맞는지입니다.

필요한 패키지 확인

npm list tailwindcss @tailwindcss/postcss postcss

패키지가 빠져 있다면 설정 파일이 맞아도 빌드가 실패할 수 있습니다. 새로 설치하기 전에 현재 설치 상태를 먼저 보는 이유는, 이미 다른 버전이 들어가 있거나 Vite 플러그인 방식으로 구성된 프로젝트일 수 있기 때문입니다.

Tailwind CSS v4 기준 CSS 진입점

@import "tailwindcss";

v4 기준으로 새 프로젝트를 구성했다면 전역 CSS에는 보통 이 한 줄을 진입점으로 둡니다. 이 파일이 실제 앱에 import되어 있는지도 함께 확인해야 합니다. React 프로젝트라면 main.jsx나 main.tsx, Next.js App Router라면 app/layout.tsx에서 전역 CSS가 연결되어 있어야 합니다.

빌드 오류를 볼 때는 VS Code의 노란 밑줄보다 터미널 로그가 더 직접적인 단서입니다. PostCSS plugin, Cannot find module, @tailwindcss/postcss 같은 문구가 보이면 패키지 설치와 설정 파일을 먼저 봐야 합니다.

Tailwind v3와 v4 설정을 섞지 않기

검색해서 나온 Tailwind 예제는 버전이 섞여 있는 경우가 많습니다. 특히 오래된 글에서는 CSS 파일에 아래처럼 작성하는 예제가 흔합니다.

Tailwind CSS v3에서 자주 보던 방식

@tailwind base;
@tailwind components;
@tailwind utilities;

이 방식이 항상 틀렸다는 뜻은 아닙니다. Tailwind CSS v3 프로젝트에서는 익숙한 설정입니다. 문제는 v4로 새 프로젝트를 만들었는데 v3 글을 보고 설정을 그대로 가져오는 경우입니다. 이때 CSS 진입점, PostCSS 플러그인, 설정 파일 구조가 어긋나면서 경고와 빌드 오류가 동시에 보일 수 있습니다.

반대로 기존 v3 프로젝트를 유지하고 있다면 무조건 v4 방식으로 바꾸는 것도 위험합니다. 프로젝트의 package.json에서 Tailwind 버전을 먼저 확인하고, 그 버전에 맞는 문서를 기준으로 설정을 정리해야 합니다.

버전 확인 명령어

npm list tailwindcss

이 명령어로 현재 프로젝트에 설치된 Tailwind 버전을 확인할 수 있습니다. 여러 글을 섞어서 따라 하기 전에 버전부터 확인하면 설정 충돌을 줄일 수 있습니다.

Vite 프로젝트라면 v4에서 @tailwindcss/vite 플러그인을 쓰는 흐름도 있습니다. Next.js나 다른 빌드 환경에서는 PostCSS 설정을 쓰는 경우가 많습니다. 그래서 설치법을 하나로 외우기보다 현재 프로젝트가 Vite 플러그인 방식인지, PostCSS 방식인지 나눠 봐야 합니다.

다시 확인할 체크리스트

같은 경고가 다시 보이면 아래 순서로 확인하면 됩니다. 처음부터 설정을 많이 바꾸기보다, 증상이 어디에서 발생하는지 좁히는 방식이 덜 흔들립니다.

확인 순서

1. 브라우저 화면에 Tailwind 스타일이 적용되는지 확인
2. 터미널에 PostCSS 또는 빌드 오류가 있는지 확인
3. Tailwind CSS IntelliSense 설치 여부 확인
4. CSS 파일의 언어 모드 확인
5. package.json에서 Tailwind 버전 확인
6. v4라면 @tailwindcss/postcss 또는 @tailwindcss/vite 설정 확인
7. 빌드가 정상일 때만 VS Code unknownAtRules 경고 숨김 처리

이 순서의 목적은 경고를 바로 숨기지 않는 데 있습니다. 경고가 불편해서 ignore 설정부터 넣으면 실제 설정 오류까지 덮어버릴 수 있습니다. 반대로 빌드와 화면이 정상인 상황이라면 에디터 경고를 줄이는 설정은 작업 집중도를 높이는 선택이 될 수 있습니다.

CSS 파일 위치도 같이 봐야 합니다. Tailwind 진입점이 되는 CSS 파일을 만들었더라도 앱에서 import하지 않으면 스타일이 적용되지 않습니다. 이 경우 VS Code 경고와 별개로 화면에는 아무 변화가 없습니다.

확인해야 할 파일

파일	확인할 내용
package.json	Tailwind CSS 버전과 관련 패키지 설치 여부
postcss.config.mjs	PostCSS 플러그인 이름이 현재 버전과 맞는지
src/index.css 또는 globals.css	Tailwind CSS 진입점이 작성되어 있는지
main.tsx, layout.tsx	전역 CSS 파일이 실제 앱에 연결되어 있는지
.vscode/settings.json	에디터 경고 설정을 프로젝트 단위로 관리하는지

프로젝트 전체 설정을 바꾸기 부담스럽다면 워크스페이스 설정으로만 조정하는 방식도 가능합니다. 팀 프로젝트라면 개인 취향으로 경고를 숨기는 설정을 저장소에 포함할지, 개인 VS Code 설정에만 둘지도 따로 판단해야 합니다.

정리

Unknown at rule 경고는 Tailwind CSS가 무조건 잘못 설치됐다는 뜻이 아닙니다. VS Code의 CSS 검사기가 Tailwind 전용 지시어를 모르는 상황일 수도 있고, PostCSS 설정이 실제로 맞지 않는 상황일 수도 있습니다.

확인 순서는 단순합니다. 화면 스타일이 적용되는지 보고, 터미널 빌드 로그를 확인한 뒤, 그다음 VS Code 확장 프로그램과 lint 설정을 정리합니다. Tailwind CSS v4 프로젝트라면 @import "tailwindcss"와 @tailwindcss/postcss 설정을 기준으로 보고, v3 예제와 섞이지 않게 버전을 먼저 확인해야 합니다.

경고를 없애는 것보다 원인 위치를 나누는 것이 먼저입니다. 이 기준을 잡아두면 다음에 @apply, @theme, @utility 같은 Tailwind 지시어에서 비슷한 경고가 보여도 에디터 문제인지 빌드 문제인지 빠르게 판단할 수 있습니다.