사용 가이드
이미지 최적화
원본 이미지를 요청한 크기·형식으로 바꿔 서빙하도록 설정합니다.
이미지 최적화를 켜면 큰 원본 이미지를 방문자 화면에 맞는 크기와 가벼운 형식(예: WebP)으로 바꿔서 보내 줍니다. 바꾼 결과는 캐시되어 다음 요청부터 빠르게 나갑니다.
Next.js라면 설정할 것이 없습니다
Next.js의 기본 이미지 로더(next/image)는 자동으로 연결됩니다. 이미지 옵션은 평소처럼 next.config에서만 조정하고, nitroship.json에 images를 따로 적지 마세요.
다른 프레임워크·정적 사이트
배포 루트의 nitroship.json에 images를 추가합니다.
{
"images": {
"protocol": "astro",
"domains": ["images.example.com"],
"remotePatterns": [
{"protocol": "https", "hostname": "cdn.example.com", "pathname": "/**"}
]
}
}protocol: 어떤 URL 형식을 쓸지 (필수)
프레임워크가 만드는 이미지 URL 형식에 맞춰 고릅니다.
| 값 | 기본 경로 | URL 예시 | 주로 쓰는 곳 |
|---|---|---|---|
astro | /_image | /_image?href=/photo.png&w=640&f=webp | Astro |
ipx | /_ipx | /_ipx/w_640,f_webp/photo.png | Nuxt Image |
vercel | /_vercel/image | /_vercel/image?url=/photo.png&w=640&q=75 | Vercel 이미지 로더 |
next | /_next/image | /_next/image?url=/photo.png&w=640&q=75 | Next.js 형식 |
경로를 바꾸려면 path를 지정하세요.
어떤 원본 이미지를 허용할지
- 외부 이미지는 명시적으로 허용해야 합니다.
domains에 호스트 이름을 적거나,remotePatterns로 프로토콜·호스트·경로를 더 세밀하게 정하세요. - 내 사이트의 이미지는 기본으로 모두 허용됩니다.
localPatterns로 범위를 좁힐 수 있고, 빈 배열([])로 두면 모두 거부합니다. - 허용되지 않은 원본이나 지원하지 않는 변환 설정을 요청하면
400을 돌려줍니다.
보안 관련
- SVG는 기본으로 꺼져 있습니다. SVG 안에는 스크립트가 들어갈 수 있으므로, 믿을 수 있는 원본에만
dangerouslyAllowSVG를 켜세요. - 사설 IP의 원본을 허용하는
dangerouslyAllowLocalIP는 지원하지 않습니다. 설정해도 사설 네트워크 이미지는 차단됩니다.
캐시 동작
최적화된 응답에는 X-Nextjs-Cache: MISS|HIT|STALE 헤더가 붙습니다. MISS는 새로 변환, HIT은 캐시에서 응답, STALE은 만료된 캐시를 먼저 보내고 뒤에서 새로 변환하는 중이라는 뜻입니다.