[Next.js] Middleware와 matcher 옵션

Unable to optimize image and unable to fallback to upstream image.

Next.js App Router course로 만든 프로젝트에서 어느 순간부터 이미지에 엑박이 뜨기 시작했다.

콘솔이나 빌드 과정에서도 에러 메세지가 뜨지 않아서 원인을 찾을 수 없었는데 이미지 src 링크로 들어가 보니 에러 메세지를 발견할 수 있었다.

Unable to optimize image and unable to fallback to upstream image.

검색 결과 이 에러는 middleware의 matcher 옵션 때문에 발생한다고 한다. 일단 middleware의 matcher 옵션이 무엇인지 먼저 알아보자.

Next.js middleware란?

• 미들웨어를 사용하면 요청이 완료되기 전에 코드를 실행할 수 있다.
• 그 후 들어오는 요청에 따라 rewriting, redirecting, 요청 혹은 응답 헤더 수정, 직접 응답 등의 방법으로 응답을 수정할 수 있다.
• middleware.ts (혹은 .js) 파일을 루트 디렉토리에 생성하면 미들웨어를 사용할 수 있다.

Matching Paths

export const config = {
  matcher: '/about/:path*',
}

• 미들웨어는 기본적으로 애플리케이션의 모든 경로에서 호출된다.
• matcher 옵션을 사용하면 미들웨어를 특정 경로에서만 호출될 수 있도록 설정할 수 있다.
• 예를 들면 상단의 코드에서는 /about/:path* 경로에서만 미들웨어가 호출될 것이다.

export const config = {
  matcher: ['/about/:path*', '/dashboard/:path*'],
}

• matcher 옵션은 단일 경로뿐만 아니라 배열에 여러 개의 경로를 전달하는 형태로도 사용할 수 있다.

export const config = {
  matcher: [
    '/((?!api|_next/static|_next/image|favicon.ico).*)',
  ],
}

• 정규표현식을 사용해서 특정 경로에서는 미들웨어가 호출되지 않도록 설정할 수도 있다.
• 상단의 코드에서는 api, _next/static, _next/image, favicon.ico으로 시작하는 경로에서는 미들웨어를 호출하지 않는다.

에러 해결하기

export const config = {
  matcher: ['/((?!api|_next/static|_next/image|.png).*)'],
};

• 내가 기존에 설정했던 matcher 옵션이다.
• 이미지 경로가 http://localhost:3000/_next/image?url=...이고 경로가 _next/image로 시작하기 때문에 미들웨어가 호출되지 않아야 하는 거 같긴 한데.. 일단 에러가 발생했으니 수정을 해 본다.

export const config = {
  matcher: ['/((?!api|_next/static|_next/image|.*\\.png$).*)'],
};

• Next.js app router course 예시 코드를 보고 matcher 옵션을 수정했다.
• 경로가 .png로 끝나는 경우에도 미들웨어를 호출하지 않도록 설정을 추가하니 사진이 엑박으로 뜨던 문제가 해결되었다.
• 참고로 나와 동일한 문제를 겪은 PR 내역도 찾을 수 있었다.

Reference

[stackoverflow] NextJS ImageError: Unable to optimize image and unable to fallback to upstream image
Next.js docs > middleware