30초 요약
Astro의 내장 Fonts API로 Google Fonts를 self-host하도록 설정하면, 공식 문서가 밝히듯 그 provider는 “폰트를 내려받아 캐시해서 사이트에서 직접 서빙”한다(Fonts 가이드). 이 “내려받기”는 빌드(또는 dev 서버 첫 실행) 시점에 Google 서버로 네트워크 요청을 보내는 단계이고, 이 요청이 CI 환경의 네트워크 제한이나 지연으로 실패하면 빌드가 느려지거나 아예 실패한다. 같은 구조의 문제는 Next.js의 next/font/google에서도 실제로 보고돼 있다. 배포 중 Google 서버 접근이 막혀 빌드가 깨지고 프로덕션이 여러 커밋 뒤에 멈춘 사례가 있다(GitHub 이슈). @fontsource/<폰트명> npm 패키지는 폰트 파일 자체를 패키지 안에 담아 배포하므로, npm install이 끝나는 시점에 이미 모든 폰트 파일이 node_modules에 있다. 이후 Astro 빌드 단계에서는 Google 쪽으로 추가 요청을 보낼 필요가 없다. Google Fonts <link>나 Fonts API의 google() provider를 걷어내고 해당 @fontsource 패키지의 CSS를 import하는 방식으로 바꾸면 된다.
증상/목표
Astro 프로젝트에서 한글 웹폰트(Noto Sans KR, IBM Plex Sans KR 등)를 쓰는 방법은 크게 두 갈래다.
- 레이아웃
<head>에https://fonts.googleapis.com/css2?family=...형태의<link>를 걸어 두고 방문자 브라우저가 매 방문마다 Google 서버에서 CSS와 폰트 파일을 받아오게 하는 방식 - Astro 내장 Fonts API에서
fontProviders.google()을 provider로 지정해, 빌드 시점에 Astro가 대신 Google에서 폰트를 내려받아 사이트 자체 자산으로 self-host하는 방식(Font Provider 문서)
두 번째 방식은 방문자 브라우저가 더 이상 Google 도메인에 접속하지 않아도 되므로 런타임 성능·프라이버시 면에서는 낫지만, 대신 그 “내려받기” 작업이 방문자의 브라우저가 아니라 빌드 파이프라인으로 옮겨질 뿐이다. Astro 문서는 이 provider들이 “폰트를 내려받아 캐시”한다고 설명하고, 캐시는 dev에서는 .astro/fonts, 빌드에서는 node_modules/.astro/fonts에 쌓인다(Fonts 가이드). 이 캐시가 비어 있는 첫 빌드(캐시를 정리했거나, 매번 새 컨테이너로 뜨는 CI 러너)에서는 여전히 Google 서버로 네트워크 요청이 필요하고, 이 요청이 실패하거나 느리면 빌드 전체가 그 영향을 받는다.
같은 유형의 문제는 Astro에 국한되지 않는다. Next.js의 next/font/google도 빌드 시점에 fonts.gstatic.com에서 폰트를 내려받는 구조이고, 이 접근이 막혀 CI 빌드가 깨지고 배포가 다섯 커밋 뒤로 멈춘 사례가 최근 보고됐다. 해당 이슈는 “제3자 서비스가 느리다는 이유로 빌드가 실패할 수 있다면 그건 프로덕션 등급이 아니다”라고 지적한다(GitHub 이슈).
목표는 빌드 파이프라인이 npm 레지스트리 외에 Google 도메인이라는 또 다른 외부 서비스의 가용성에 의존하지 않게 만드는 것이다.
원인
빌드 중 폰트 다운로드가 문제가 되는 근본 원인은 두 가지로 나뉜다.
- 네트워크 요청 자체의 실패: CI 러너가 사내망·방화벽·DNS 정책으로 Google 도메인에 접근하지 못하거나, Google 쪽 응답이 느려 타임아웃이 나는 경우
- 재현성 문제: 같은 커밋이어도 그날의 네트워크 상태에 따라 빌드가 성공하기도 실패하기도 한다. 코드는 그대로인데 빌드 결과가 달라지는 것은 CI 파이프라인이 피해야 할 상태다
@fontsource 패키지는 이 문제를 아키텍처 수준에서 없앤다. 폰트 파일(.woff2)과 그 파일을 가리키는 CSS를 npm 패키지 콘텐츠로 그대로 배포하기 때문에, 폰트를 “받는” 시점이 npm install로 앞당겨진다. 이 시점의 네트워크 요청은 어차피 다른 모든 의존성을 설치할 때도 필요한 요청이므로, 별도의 실패 지점이 새로 생기지 않는다. Fontsource 설치 문서는 이 CSS를 애플리케이션 진입점에서 그냥 import하면 된다고 설명한다(설치 문서).
해결 방법
1. 쓸 폰트의 @fontsource 패키지 확인하기
fontsource.org에서 폰트 이름으로 검색해 패키지가 있는지 확인한다. 한글 폰트는 @fontsource/ibm-plex-sans-kr, @fontsource/noto-sans-kr처럼 언어가 이름에 붙어 있는 경우가 많다. IBM Plex Sans KR 패키지는 100~700 사이 7단계 굵기를 제공한다(패키지 페이지). variable 폰트 버전(@fontsource-variable/...)이 있으면 그쪽이 굵기 하나로 여러 두께를 커버하므로 우선 검토 대상이다(설치 문서).
2. 패키지 설치하기
npm install @fontsource/ibm-plex-sans-kr @fontsource/ibm-plex-mono3. 실제로 쓰는 굵기만 import하기
기본 import(import "@fontsource/ibm-plex-sans-kr")는 굵기 400만 불러온다. 프로젝트에서 여러 굵기를 쓴다면 굵기별 CSS 파일을 각각 import한다. Fontsource 문서는 “프로젝트가 실제로 쓰는 굵기와 스타일만 import하라”고 명시한다. import 하나가 폰트 파일(face) 하나를 추가하기 때문이다(설치 문서).
// 레이아웃이나 전역 엔트리(예: BaseLayout.astro)에서 한 번만import '@fontsource/ibm-plex-sans-kr/400.css';import '@fontsource/ibm-plex-sans-kr/600.css';import '@fontsource/ibm-plex-sans-kr/700.css';import '@fontsource/ibm-plex-mono/400.css';normal 스타일 import에는 이탤릭이 포함되지 않으므로, 이탤릭도 쓴다면 600-italic.css처럼 따로 import해야 한다(설치 문서).
4. Google Fonts <link>와 Fonts API 설정 제거하기
레이아웃에 남아 있는 <link rel="preconnect" href="https://fonts.googleapis.com">, <link href="https://fonts.googleapis.com/css2?family=..."> 같은 태그를 지운다. Astro 내장 Fonts API의 google() provider를 쓰고 있었다면, astro.config의 해당 fonts 설정과 <Font> 컴포넌트 사용처도 함께 걷어낸다.
// 이전: astro.config에서 Google provider로 self-hostimport { fontProviders } from 'astro/config';
export default defineConfig({ experimental: { fonts: [ { provider: fontProviders.google(), name: 'Noto Sans KR', cssVariable: '--font-noto-sans-kr', }, ], },});이 설정 블록 전체를 삭제하고, 3단계에서 추가한 import '@fontsource/...' 줄로 대체한다.
5. font-family 이름 맞추기
CSS(또는 Tailwind 설정)의 font-family가 @fontsource CSS 안의 font-family 값과 정확히 일치하는지 확인한다. IBM Plex Sans KR 패키지의 경우 "IBM Plex Sans KR"이다.
body { font-family: 'IBM Plex Sans KR', system-ui, sans-serif;}확인
@fontsource 방식이 실제로 빌드 시점 네트워크 의존을 없애는지는 다음 두 단계로 재현해서 확인한다.
/etc/hosts에fonts.googleapis.com,fonts.gstatic.com을 루프백으로 매핑해 두 도메인에 대한 접속을 끊는다. 이 상태에서 해당 도메인으로 curl 요청을 보내 실패하는지 확인한다. 이것이 “빌드 중 Google Fonts 다운로드가 막힌 상황”의 재현이다- 같은(Google 도메인이 막힌) 환경에서
npm install @fontsource/ibm-plex-sans-kr을 실행하고, 설치된 CSS 파일이unicode-range로 문자셋을 나누고 있는지,fonts.googleapis.com·fonts.gstatic.com참조가 전혀 없는지,@font-face가 가리키는 모든.woff2/.woff파일이 패키지 안에 이미 로컬로 존재하는지 확인한다
검증 환경 6항목
| OS | Ubuntu 24.04.5 |
|---|---|
| npm | 10.9.8 |
| Node | 22.23.2 |
| curl | 8.5.0 |
| sudo | 1.9.15p5 |
| 실행 날짜 | 2026-09-24 |
이전 형식 기록이라 이름은 verify.sh의 도구 목록 순서로 붙였다. 버전은 괄호 앞만 옮겼다.
[PASS] Google Fonts 도메인 접속이 막혀 있음(빌드 중 다운로드 실패 재현) [PASS] Google 도메인이 막힌 상태에서도 npm install로 @fontsource 패키지 설치 성공 [PASS] 400 굵기 CSS 파일이 로컬에 존재 [PASS] font-family에 IBM Plex Sans KR 포함 [PASS] unicode-range로 서브셋이 나뉘어 있음 [PASS] CSS에 Google Fonts 외부 도메인 참조가 없음 [PASS] @font-face가 가리키는 폰트 파일이 모두 패키지 안에 로컬로 이미 존재(추가 다운로드 불필요)
주의
npm install자체는 npm 레지스트리에 대한 네트워크가 필요하다.@fontsource가 없애는 것은 “Google 도메인에 대한 빌드 타임 의존”이지 네트워크 자체의 필요성이 아니다.npm install이 끝난 뒤(또는 의존성이 캐시된 뒤)의astro build만 오프라인으로 재현 가능하다- 정적(static) 패키지는 굵기·스타일마다 별도로 import해야 한다. 안 쓰는 굵기까지 import하면 그만큼 CSS 크기가 늘어난다. variable 패키지가 있는 폰트라면 굵기 하나로 여러 두께를 커버할 수 있다(설치 문서)
- 생성된 CSS는
unicode-range로 서브셋을 나누므로 보통 특정 서브셋을 수동으로 고를 필요는 없다. 다만 필요하면latin.css처럼 서브셋 이름이 붙은 파일을 개별 import할 수 있다. Fontsource 문서는 이 방식을 “특별한 이유가 없다면 권장하지 않는다”고 밝힌다(서브셋 문서) - Astro 내장 Fonts API에는
fontsource()provider도 있어 Fontsource 폰트를 API를 통해 쓸 수 있다(Font Provider 문서). 다만 이 문서에서 다룬 방식은 API를 거치지 않고@fontsource패키지의 CSS를 직접 import하는 가장 단순한 경로다 - 이 빌드를 GitHub Actions에서 돌려 GitHub Pages에 올리는 과정은 Astro 블로그를 GitHub Actions로 배포하기에 있다.
자주 묻는 질문
Astro 내장 Fonts API로 Google Fonts를 self-host하면 이 문제가 해결되지 않나?
부분적으로만 해결된다. 방문자 브라우저가 Google 도메인에 접속하지 않아도 된다는 점에서는 같은 효과를 내지만, 그 다운로드 작업이 방문자에서 빌드 파이프라인으로 옮겨질 뿐이다. 공식 문서는 이 provider들이 “폰트를 내려받아 캐시”한다고 설명한다(Fonts 가이드). 캐시가 채워지기 전(첫 빌드, 캐시를 정리한 CI 러너)에는 여전히 Google 서버로 네트워크 요청이 필요하다. @fontsource 패키지를 직접 import하면 그 다운로드 자체가 npm install로 흡수되므로, astro build 단계에는 Google로 가는 요청이 아예 없다.
한글 폰트는 파일이 커서 사이트가 느려지지 않나?
Fontsource가 생성하는 CSS는 @font-face 블록마다 unicode-range를 지정해 문자 집합별로 파일을 나눈다. 브라우저는 실제 페이지에 쓰인 문자가 속한 서브셋 파일만 내려받는다(설치 문서). 다만 import한 굵기 수만큼 CSS 자체는 늘어나므로, 실제로 쓰는 굵기만 import하는 편이 좋다.
Google Fonts <link>를 그대로 두고 preconnect만 추가하면 안 되나?
preconnect는 연결 지연을 줄여줄 뿐, Google 서버 자체가 느리거나 접근이 막히는 상황을 해결하지는 못한다. 이 글이 다루는 문제는 “빌드 파이프라인이 Google 도메인 가용성에 성패를 걸게 되는 구조” 자체이고, preconnect는 이 구조를 바꾸지 않는다.
참고 자료
- docs.astro.build/en/guides/fonts/
- docs.astro.build/en/reference/font-provider-reference/
- docs.astro.build/en/reference/experimental-flags/fonts/
- fontsource.org/docs/getting-started/install
- fontsource.org/docs/getting-started/subsets
- fontsource.org/fonts/ibm-plex-sans-kr
- github.com/crclabs-hq/GateTest/issues/684