Next.js 폰트가 로컬에서는 되는데 배포 서버에서만 실패할 때

로컬에서는 폰트가 잘 보이는데, 배포 환경에서만 로드 실패 에러가 난다면, 빌드 시점과 런타임의 환경 차이 때문이다.

로컬 빌드와 배포 환경의 차이를 찾는다

npm run build

빌드 로그를 자세히 읽는다. 특히 폰트 파일 경로, 정적 자산 처리, 최적화 관련 메시지가 있는지 본다.

배포 서버의 HTML 헤드를 확인한다

curl -s https://example.com | grep -Ei 'title|description|canonical|og:|twitter:|font|link'

폰트 링크 태그가 실제로 있는지, 경로가 올바른지 본다. 특히 href 속성이 절대 경로인지 상대 경로인지 확인한다.

폰트 파일이 실제로 배포되었는지 확인한다

curl -I https://example.com/fonts/my-font.woff2

404 에러가 나면 폰트 파일이 배포되지 않은 것이다. 빌드 프로세스에서 정적 폰트 파일이 포함되는지 확인해야 한다.

환경별 빌드 설정이 다른지 본다

Next.js next.config.js 파일에서 이미지나 폰트 최적화 설정이 환경에 따라 달라질 수 있다:

module.exports = {
  optimizeFonts: process.env.NODE_ENV === 'production' ? true : false,
}

로컬(development) 환경과 배포(production) 환경의 설정을 일치시킨다.

도메인과 경로를 점검한다

만약 앱을 서브도메인이나 서브 경로에 배포한다면:

const basePath = process.env.NEXT_PUBLIC_BASE_PATH || ''

폰트 경로가 베이스 경로를 포함하는지 확인한다.

한 가지씩 변경하고 테스트한다

폰트 로드 실패는 여러 원인이 조합될 수 있다. 경로를 바꾸고, 그 다음 환경 변수를 바꾸고, 이런 식으로 한 가지씩 테스트하면 원인을 명확히 파악할 수 있다.