App Router는 정해진 이름의 파일이나 metadata 객체에서 아이콘 요소를 생성할 수 있습니다. 두 방식 모두 유효하지만 명확한 기준 없이 섞으면 서로 경쟁하는 선언이 생기기 쉽습니다.
파일 규칙 선택하기
favicon.ico는 app 루트에 두세요. 지원되는 icon 파일은 라우트 세그먼트 안에 둘 수 있으며 apple-icon은 Apple 기기용 아이콘을 지정합니다.
Next.js가 파일을 감지하고 필요한 속성을 결정한 뒤 head에 해당 link 요소를 추가합니다. 세그먼트에 놓은 아이콘은 그 세그먼트의 라우트에 적용됩니다.
| 파일 | 위치 | 용도 |
|---|---|---|
| favicon.ico | app/ | 사이트 기본 대체 아이콘 |
| icon.svg | app 세그먼트 | 브라우저 아이콘 |
| apple-icon.png | app 세그먼트 | Apple 아이콘 |
| manifest.webmanifest | app 세그먼트 | 앱 설치용 매니페스트 |
metadata로 경로 명시하기
파일이 public이나 이미지 호스트에 있다면 layout 또는 page에서 metadata.icons를 선언하세요. 일관된 URL로 icon, apple과 필요한 경우 shortcut을 지정하세요.
자식 세그먼트의 메타데이터는 부모에서 상속한 복합 필드를 대체할 수 있습니다. 부모의 모든 항목이 병합된다고 가정하지 말고 여러 라우트의 최종 head를 검사하세요.
요청 시 생성하는 아이콘에는 icon.tsx나 icon.js도 사용할 수 있습니다. 함수가 크기와 콘텐츠 유형을 명시한 이미지 데이터를 반환합니다. 실제로 동적인 구성이 필요할 때 사용하세요. 정적 파일이 캐시와 검사에 더 간단하고 배포마다 일관되게 제공하기 쉽습니다.
매니페스트와 아이콘 연결하기
정적 매니페스트 파일이나 manifest.ts 함수로 앱 이름, 색상, 설치용 아이콘을 지정할 수 있습니다. 매니페스트 아이콘 URL은 공개적으로 접근 가능하고 선언된 크기의 파일을 가리켜야 합니다.
매니페스트와 탭 파비콘의 역할을 구분하세요. 512×512 설치용 아이콘이 icon.svg나 favicon.ico를 자동으로 대체하지는 않습니다.
프로덕션 환경에서 테스트하기
프로덕션 빌드를 실행하고 영향을 받는 각 세그먼트에서 라우트 하나씩 열어 link 요소를 검사하세요. 각 파일 URL도 직접 열고 미들웨어가 요청을 가로채지 않는지 확인하세요.
basePath나 CDN을 사용한다면 배포 환경에서 생성된 URL을 테스트하세요. 잘못된 공개 기본 경로나 다시 쓰기 규칙은 로컬에서 드러나지 않을 수 있습니다.
공식 참고 자료
자주 묻는 질문
link 요소를 직접 작성해야 하나요?
아니요. 파일 규칙이나 metadata.icons가 생성할 수 있습니다. 기준이 되는 방식을 하나로 명확하게 정하세요.
favicon.ico는 어디에 두나요?
App Router에서 favicon.ico 파일 규칙은 app 디렉터리 루트에서 지원됩니다.
manifest.ts가 icon.svg를 대체하나요?
아니요. 매니페스트는 설치용 아이콘을 비롯한 앱 정보를 지정하고 icon.svg는 브라우저 아이콘을 직접 제공합니다.