iPhone에서 Next.js 사이트를 홈 화면에 추가했을 때 빈 회색 사각형이 표시된 적이 있다면, Apple 터치 아이콘이 누락된 것입니다. 브라우저 탭의 파비콘은 정상적으로 보일 수 있지만, iOS는 별도의 파일을 사용하며 Next.js는 이를 제공하는 특정한 방법이 있습니다.
이 가이드에서는 App Router의 파일 기반 메타데이터 시스템을 사용한 Next.js Apple 아이콘 설정 방법을 안내합니다. 사용자 정의 API 라우트나 _document.tsx에 수동으로 <link> 태그를 작성할 필요 없이, 올바른 폴더에 파일을 넣기만 하면 됩니다.
사전 요구 사항
시작하기 전에 다음이 준비되어 있는지 확인하세요:
- App Router를 사용하는 Next.js 프로젝트(버전 13.2 이상).
- 아이콘용 이미지 파일. Apple은 터치 아이콘에 180×180 PNG를 권장하지만, 잠시 후에 자세히 다루겠습니다.
- 프로젝트의
app/디렉토리에 대한 기본적인 이해.
1단계: Apple 터치 아이콘 준비
Apple 터치 아이콘은 사용자가 사이트를 홈 화면에 추가할 때 iOS가 사용하는 PNG 파일입니다. 권장 크기는 180×180 픽셀이며, iPad Pro용 167×167, 구형 iPad용 152×152도 제공할 수 있습니다. 그러나 iOS는 180×180 아이콘을 자동으로 축소하므로 하나의 파일만 있으면 됩니다.
준비된 아이콘이 없다면 Mzu favicondl과 같은 도구를 사용하여 로고에서 생성할 수 있습니다. 올바른 투명도와 패딩이 적용된 180×180 PNG를 내보낼 수 있습니다.
2단계: App 디렉토리에 파일 배치
Next.js App Router에서는 apple-icon.png(또는 apple-icon.jpg)를 app/ 디렉토리에 직접 추가할 수 있습니다. Next.js는 이를 자동으로 감지하여 사이트 루트에서 제공합니다. 파일은 layout.tsx와 같은 폴더(일반적으로 app/)에 배치해야 합니다.
다음은 폴더 구조 예시입니다:
app/
├── layout.tsx
├── page.tsx
├── apple-icon.png
└── icon.png이것으로 끝입니다. Next.js는 페이지의 head에 적절한 <link rel='apple-touch-icon'> 태그를 자동으로 생성합니다. HTML을 수동으로 작성할 필요가 없습니다.
3단계: 생성된 HTML 확인
아이콘이 제대로 제공되는지 확인하려면 개발 서버를 실행하고 페이지 소스를 검사하세요. 다음과 같은 줄이 표시되어야 합니다:
<link rel='apple-touch-icon' href='/apple-icon.png' sizes='180x180' type='image/png'/>이 줄이 보이지 않으면 파일 이름이 정확히 apple-icon.png인지, 올바른 디렉토리에 있는지 확인하세요. Next.js는 Linux와 macOS에서 대소문자를 구분합니다.
4단계: 더 많은 제어를 위한 Metadata API 사용
여러 아이콘을 지정하거나 프로그래밍 방식으로 설정해야 하는 경우 레이아웃에서 metadata 내보내기를 사용할 수 있습니다. 이는 라우트별로 다른 아이콘이 있거나 Android용 maskable 아이콘을 추가하려는 경우 유용합니다.
다음은 app/layout.tsx의 예시입니다:
import type { Metadata } from 'next';
export const metadata: Metadata = {
icons: {
apple: [
{ url: '/apple-icon.png', sizes: '180x180', type: 'image/png' },
],
},
};이 방법을 사용하면 rel, sizes, type 속성을 완전히 제어할 수 있습니다. 또한 Android PWA용 maskable 아이콘을 추가하는 데 사용할 수도 있지만, 이는 별도의 주제입니다.
일반적인 문제
다음은 발생할 수 있는 몇 가지 문제입니다:
- 파일을 찾을 수 없음: 파일 이름을 다시 확인하세요.
apple-icon.png또는apple-icon.jpg여야 합니다. Next.js는apple-touch-icon.png를 인식하지 못합니다. - 캐시 문제: iOS는 아이콘을 적극적으로 캐시합니다. 아이콘을 변경했는데 업데이트가 보이지 않으면 Safari의 캐시를 지우거나 다른 기기를 사용해 보세요.
- 잘못된 크기: Apple은 180×180을 권장하지만, 다른 크기를 사용하면 iOS가 크기를 조정합니다. 크기 조정은 흐림을 유발할 수 있으므로 권장 크기를 사용하는 것이 좋습니다.
- 투명도: iOS는 Apple 터치 아이콘에서 투명도를 지원하지 않습니다. PNG에 투명한 영역이 있으면 검은색으로 표시됩니다. 아이콘의 배경이 불투명한지 확인하세요.
결론
Next.js에서 Apple 터치 아이콘을 설정하는 것은 파일 기반 규칙을 알면 간단합니다. 적절한 크기의 PNG를 app/ 폴더에 넣으면 Next.js가 나머지를 처리합니다. 더 고급 시나리오의 경우 metadata API를 통해 프로그래밍 방식으로 제어할 수 있습니다.
아이콘 자체를 생성해야 한다면 Mzu favicondl을 사용하여 로고에서 필요한 모든 크기를 만들어 보세요. Next.js에서 파비콘 설정에 대한 더 자세한 내용은 Next.js Favicon 가이드를 확인하세요.
문서화된 요구 사항 확인
Next.js는 메타데이터 파일 규칙에서 파비콘과 앱 아이콘을 문서화하고 있습니다.