Next.js용 파비콘
Next.js 14+ App Router는 파일 기반 아이콘 규칙을 도입했습니다. favicon.ico 또는 icon.png를 /app 디렉터리에 놓으면 Next.js가 자동으로 올바른 `<link>` 태그를 내보냅니다. 수동 헤드 구성 요소가 필요하지 않습니다. Pages Router 프로젝트의 경우 favicon.ico를 /public에 배치하고 _document.tsx에서 연결하세요. favicon generator는 하나의 소스 이미지에서 전체 파일 세트를 생성하고 best favicon size guide는 각 컨텍스트에 중요한 크기를 다룹니다.
App Router가 포함된 Next.js 13+는 /app 디렉터리의 특수 파일 이름을 메타데이터 규칙으로 처리합니다. favicon.ico, icon.png, icon.svg 및 apple-icon.png라는 이름의 파일은 Next.js 메타데이터 시스템에서 자동으로 인식되며, 레이아웃.tsx 또는 메타데이터 내보내기의 구성 없이 올바른 응답 헤더 및 `<link>` 태그와 함께 제공됩니다.
파일 규칙을 사용하려면 favicon.ico를 /app 디렉터리(/public 아님)에 넣으세요. Next.js는 /favicon.ico 경로에서 이를 제공하고 해당 레이아웃을 공유하는 모든 페이지에 링크 태그를 삽입합니다. 아이콘 파일은 전역적으로 적용하려면 루트 레이아웃.tsx와 동일한 수준에 있어야 합니다.
App Router를 사용하는 높은 DPI 아이콘의 경우 /app 안에 icon.png를 배치하세요. Next.js는 치수를 읽고 적절한 '<link rel='icon' sizes='...' href='...'>' 태그를 생성합니다. 다양한 크기를 제공하려면 icon.png(32×32), icon@2x.png(64×64) 등 다양한 숫자 접미사를 사용하여 여러 아이콘 파일을 내보내거나 무한히 확장 가능한 단일 파일에 icon.svg를 사용하세요.
App Router는 iOS 홈 화면 아이콘에 대한 전용 apple-icon.png 파일도 지원합니다. /app 안에 apple-icon.png(180×180)를 배치하면 Next.js가 자동으로 `<link rel='apple-touch-icon' href='...'>`를 내보냅니다. 이는 가장 깔끔한 접근 방식입니다. 수동으로 메타데이터를 내보낼 필요가 없습니다.
파일 규칙을 통하지 않고 코드에서 파비콘을 선언하려는 경우 레이아웃.tsx에서 메타데이터 개체를 내보냅니다. 아이콘 속성은 바로가기, 아이콘, 사과 및 기타 필드가 있는 개체를 허용합니다. 예: `const 메타데이터 내보내기: 메타데이터 = { 아이콘: { 아이콘: '/favicon.ico', apple: '/apple-touch-icon.png' } }`. 이 방법은 로케일이나 환경을 기반으로 하는 동적 아이콘 경로가 필요할 때 유용합니다.
Pages Router 프로젝트(Next.js 12 이하 또는 App Router로 마이그레이션되지 않은 프로젝트)의 경우 파비콘 처리가 다르게 작동합니다. /public 디렉터리에 favicon.ico를 배치합니다. — Next.js는 루트 URL에서 /public를 제공합니다. `<Head>` 구성 요소 내부의 페이지/_document.tsx에 링크 태그를 추가합니다: `<link rel='icon' href='/favicon.ico' />`. 이 `<Head>`는 페이지별 다음/헤드 가져오기가 아닌 문서 수준 헤드입니다.
다음/헤드 구성요소('next/head'에서 헤드 가져오기)는 Pages Router의 페이지별 아이콘 재정의에 대해 작동합니다. 특정 페이지에 다른 파비콘을 원할 경우 해당 페이지 구성 요소의 `<Head>` 안에 '<link rel='icon'>'를 포함하세요. 페이지별 태그는 문서 수준 태그보다 우선 적용됩니다. 이는 하나의 Next.js 배포에서 제공되는 다중 브랜드 사이트에 유용합니다.
SVG 파비콘은 Next.js App Router 규칙에 의해 완벽하게 지원됩니다. 파일 이름을 icon.svg로 지정하고 /app에 넣습니다. Next.js는 '<link rel='icon' type='image/svg+xml' href='/_next/static/media/icon.svg...'>'를 방출합니다. Next.js는 캐시 무효화를 위해 정적 파일 이름을 해시하므로 파비콘 캐시 무효화에 대해 걱정할 필요가 없습니다. 파일을 변경하면 해시가 변경되고 브라우저가 다시 가져오게 됩니다.
Next.js App Router의 웹 매니페스트는 /app의 매니페스트.ts 파일을 통해 구성됩니다. 아이콘 크기를 포함하는 MetadataRoute.Manifest 객체를 반환하는 기본 함수를 내보냅니다. Next.js는 이를 /manifest.webmanifest에서 application/manifest+json으로 렌더링합니다. 매니페스트에서 참조된 192×192 및 512×512 PNG는 /public에 배치되어야 합니다.
Turbopack(Next.js 14+의 실험적 번들러)은 webpack과 동일하게 /public의 정적 자산을 처리합니다. /public의 파비콘 파일은 번들링 없이 제공됩니다. /app(아이콘 규칙)의 파일의 경우 Turbopack은 해당 파일을 메타데이터 자산으로 처리하므로 Turbopack과 webpack 간에 전환할 때 구성 변경이 필요하지 않습니다.
Next.js ISR(증분 정적 재생) 및 에지 배포는 파비콘 제공에 영향을 주지 않습니다. 파비콘 파일은 ISR 캐시가 아닌 CDN 에지에서 제공되는 정적 자산입니다. 이는 파비콘 업데이트가 페이지 재검증을 기다리지 않고 배포 후 즉시 전파됨을 의미합니다.
다중 로케일 Next.js 앱에는 로케일 인식 아이콘이 필요한 경우가 많습니다. params 개체를 기반으로 로케일별 아이콘 경로를 반환하려면 레이아웃.tsx의 generateMetadata 함수를 사용하세요. 이는 App Router 전용 기능입니다. Pages Router 사이트에는 로케일별 파비콘을 구현하려면 맞춤 _document.tsx 로직 또는 맞춤 서버가 필요합니다.
배포 후 favicon tester를 사용하여 Next.js 파비콘을 확인하세요. /favicon.ico, /icon.svg 및 /apple-touch-icon.png가 모두 올바른 콘텐츠 유형 헤더와 함께 200개의 응답을 반환하는지 확인하세요. 또한 배포된 사이트의 '<head>' HTML를 검사하여 Next.js가 예상되는 모든 링크 태그를 내보냈는지 확인하세요.
작동 방식
- 1
파비콘 패키지 생성
512×512 PNG 또는 SVG를 [favicon generator](tool:favicon-generator)에 업로드합니다. favicon.ico, icon.svg, apple-touch-icon.png(180×180) 및 매니페스트 PNG를 다운로드합니다.
- 2
/app(App Router)에 favicon.ico 배치
favicon.ico를 레이아웃.tsx와 함께 프로젝트의 /app 디렉터리에 복사합니다. Next.js는 자동으로 이를 제공하고 링크 태그를 삽입합니다. Pages Router의 경우 대신 /public에 배치하세요.
- 3
선명한 렌더링을 위해 icon.svg 추가
SVG의 이름을 icon.svg로 바꾸고 /app(App Router)에 넣습니다. Next.js는 SVG 링크 태그를 자동으로 내보냅니다. Pages Router의 경우 /public에 배치하고 _document.tsx에 링크 태그를 추가하세요.
- 4
iOS 설치를 위해 apple-icon.png 추가
180×180 PNG의 이름을 apple-icon.png로 바꾸고 /app(App Router)에 배치합니다. Pages Router의 경우 /public에 apple-touch-icon.png를 배치하고 _document.tsx에 링크 태그를 추가하세요.
- 5
웹 매니페스트 구성
App Router의 경우 /app/manifest.ts를 생성하고 192×192 및 512×512 아이콘 항목을 포함한 매니페스트 메타데이터를 내보냅니다. PNG를 /public에 배치합니다. Pages Router의 경우 /public에 site.webmanifest를 배치하고 _document.tsx에 매니페스트 링크 태그를 추가합니다.
- 6
프로덕션에서 확인
배포 후 실제 URL에서 소스를 보고 모든 링크 태그가 있는지 확인하세요. [favicon tester](utility:favicon-tester)를 사용하여 모든 아이콘 URL이 올바른 콘텐츠 유형으로 200을 반환하는지 확인하세요.
지금 사용해 보기
Next.js 지원 파비콘 생성
파비콘 생성기자주 묻는 질문
Next.js App Router에서 파비콘은 어디로 이동하나요?+
/app 디렉토리 내부. favicon.ico, icon.png, icon.svg 및 apple-icon.png라는 파일이 자동으로 인식되고 연결됩니다. 글로벌 파비콘은 /app에 들어갑니다. 레이아웃별 레이아웃은 해당 레이아웃 하위 디렉터리에 들어갑니다.
Next.js Pages Router에서 파비콘은 어디에 있나요?+
/public 디렉터리에 있습니다. `<Head>` 구성 요소 내부의 페이지/_document.tsx에 링크 태그를 추가합니다. Next.js는 루트 URL에서 /public 파일을 제공합니다. — /public/favicon.ico는 https://yourdomain.com/favicon.ico에서 액세스할 수 있습니다.
App Router에 파비콘을 추가하려면 레이아웃.tsx를 편집해야 합니까?+
아니요, 파일 규칙(/app의 favicon.ico)을 사용하는 경우입니다. 코드를 선호하는 경우 아이콘 속성을 사용하여 메타데이터 개체를 내보냅니다. 두 접근 방식 모두 렌더링된 HTML에서 동일한 `<link>` 태그를 생성합니다.
Next.js는 SVG 파비콘을 지원합니까?+
예. App Router의 경우 /app에 icon.svg를 배치하거나 Pages Router의 경우 _document.tsx에 `<link rel='icon' type='image/svg+xml' href='/favicon.svg'>`를 추가하세요. App Router는 파일 규칙에서 SVG 링크 태그를 자동으로 내보냅니다.
Next.js에 apple-touch-icon를 어떻게 추가하나요?+
App Router의 경우: /app에 apple-icon.png(180×180)를 배치합니다. Next.js는 apple-touch-icon 링크 태그를 자동으로 내보냅니다. Pages Router의 경우: /public에 apple-touch-icon.png를 배치하고 _document.tsx에 링크 태그를 추가합니다.
Next.js는 파비콘을 자동으로 캐시 무효화합니까?+
/app에 있는 파일의 경우 그렇습니다. Next.js는 제공된 파일 이름에 콘텐츠 해시를 추가하므로 파일이 변경될 때마다 새로운 가져오기가 트리거됩니다. /public에 있는 파일의 경우 자동 캐시 버스팅이 없습니다. 필요한 경우 쿼리 문자열을 수동으로 추가합니다.
Next.js에서 페이지마다 다른 파비콘을 사용할 수 있나요?+
예. App Router에서 사용자 정의 아이콘 값을 사용하여 특정 경로의 page.tsx에 generateMetadata 함수를 내보냅니다. Pages Router에서 페이지별 `<Head>` 구성 요소 내에 '<link rel='icon'>'를 추가하세요. 이는 문서 수준 기본값을 재정의합니다.