Astro + Tailwind 폰트 적용 트러블슈팅 (feat. v4 vs v3)

#Astro #TailwindCSS #Debug #Pretendard #TIL

1. 목표: Pretendard 폰트 적용하기

Astro와 Tailwind CSS로 블로그를 만들면서, 기본 폰트를 Pretendard로 변경하는 간단한 작업을 시작했다.

tailwind.config.mjs에 폰트 설정을 추가하고, Layout.astro의 <body>에 font-sans 클래스만 적용하면 끝날 줄 알았다.

2. 첫 번째 난관: 폰트가 로드되지 않음

F12 개발자 도구로 확인해 보니 <body>의 font-family는 system-ui로 나오고, 네트워크 탭에는 pretendard.css 파일 요청이 아예 없었다.

CDN <link> 태그, globals.css의 @import 위치 변경, --- 프론트매터에서의 import 등 다양한 방법을 시도했지만 모두 실패했다.

3. 결정적 단서: “tailwind.config.mjs를 내가 만들었다”

Gemini와 대화 중, npx astro add tailwind 명령어가 실패해서 tailwind.config.mjs 파일을 내가 수동으로 생성했다는 사실을 떠올렸다.

이것이 결정적인 단서였다. npx astro add tailwind 명령어는 원래 3가지 일을 한다.

  1. @astrojs/tailwind 패키지 설치
  2. tailwind.config.mjs 파일 생성
  3. astro.config.mjs에 통합(integration) 코드 추가

나는 3번이 누락된 것이었다.

4. 두 번째 난관: 의존성 충돌 (ERESOLVE)

astro.config.mjs에 import tailwind from "@astrojs/tailwind";를 추가하고 npm install @astrojs/tailwind를 실행하자, 이번엔 ERESOLVE 오류가 발생했다.

npm error peer tailwindcss@"^3.0.24" from @astrojs/tailwind@6.0.2
npm error Found: tailwindcss@4.1.17

원인은 내가 설치했던 tailwindcss는 최신 v4였고, @astrojs/tailwind 통합 도구는 v3가 필요했기 때문이었다.

5. 최종 해결 과정

모든 문제를 해결하기 위해 다음 단계를 순서대로 진행했다.

  1. 충돌을 일으키는 v4 제거: npm uninstall tailwindcss

  2. Astro 통합 도구와 호환되는 v3 설치: npm install @astrojs/tailwind tailwindcss@^3

  3. astro.config.mjs에 integrations: [tailwind()] 추가.

  4. tailwind.config.mjs에 Pretendard 폰트 설정 (fontFamily.sans) 및 typography 플러그인 추가.

  5. globals.css 맨 위에 @import로 Pretendard CDN 추가.

  6. 모든 레이아웃 파일(Layout.astro, BlogPostLayout.astro)의 --- 블록에서 import ’../styles/globals.css’; 실행.

  7. 모든 레이아웃 파일의 태그에 class=“font-sans antialiased” 적용.

6. 결론

“폰트 적용”이라는 간단한 작업이 폰트 로드 방식, Tailwind 설정, Astro 통합 설정, npm 의존성 버전 관리까지 연결된 복잡한 문제였다. F12 개발자 도구의 네트워크 탭과 콘솔 오류 로그를 꼼꼼히 확인하는 것이 디버깅의 핵심이었다.

블로그 목록으로 돌아가기