middleware.js

middleware.js|ts 파일은 미들웨어를 작성하고 요청이 완료되기 전에 서버에서 코드를 실행하는 데 사용됩니다. 그런 다음 들어오는 요청을 기반으로 재작성, 리다이렉트, 요청 또는 응답 헤더 수정, 또는 직접 응답함으로써 응답을 수정할 수 있습니다.

미들웨어는 라우트가 렌더링되기 전에 실행됩니다. 인증, 로깅 또는 리다이렉트 처리와 같은 사용자 정의 서버 측 로직을 구현하는 데 특히 유용합니다.

프로젝트의 루트에 middleware.ts (또는 .js) 파일을 사용하여 미들웨어를 정의합니다. 예를 들어, app 또는 pages와 같은 수준에 있거나, 해당되는 경우 src 내부에 있습니다.

import { NextResponse, NextRequest } from "next/server";
 
// 이 함수는 내부에서 `await`를 사용하는 경우 `async`로 표시될 수 있습니다
export function middleware(request: NextRequest) {
  return NextResponse.redirect(new URL("/home", request.url));
}
 
export const config = {
  matcher: "/about/:path*",
};

import { NextResponse } from "next/server";
 
// 이 함수는 내부에서 `await`를 사용하는 경우 `async`로 표시될 수 있습니다
export function middleware(request) {
  return NextResponse.redirect(new URL("/home", request.url));
}
 
export const config = {
  matcher: "/about/:path*",
};

내보내기

미들웨어 함수

파일은 기본 내보내기 또는 middleware라는 이름으로 단일 함수를 내보내야 합니다. 동일한 파일에서 여러 미들웨어는 지원되지 않습니다.

// 기본 내보내기의 예
export default function middleware(request) {
  // 미들웨어 로직
}

설정 객체 (선택사항)

선택적으로 미들웨어 함수와 함께 설정 객체를 내보낼 수 있습니다. 이 객체에는 미들웨어가 적용되는 경로를 지정하는 matcher가 포함됩니다.

Matcher

matcher 옵션을 사용하면 미들웨어가 실행될 특정 경로를 대상으로 지정할 수 있습니다. 이러한 경로를 여러 가지 방법으로 지정할 수 있습니다:

• 단일 경로의 경우: 경로를 정의하기 위해 직접 문자열을 사용합니다. 예: '/about'.
• 여러 경로의 경우: 배열을 사용하여 여러 경로를 나열합니다. 예: matcher: ['/about', '/contact']. 이는 미들웨어를 /about과 /contact 모두에 적용합니다.

또한 matcher는 matcher: ['/((?!api|_next/static|_next/image|.*\\.png$).*)']와 같은 정규 표현식을 통한 복잡한 경로 지정을 지원하여 포함하거나 제외할 경로를 정확하게 제어할 수 있습니다.

matcher 옵션은 다음 키를 가진 객체 배열도 허용합니다:

• source: 요청 경로와 일치시킬 경로 또는 패턴. 직접 경로 일치를 위한 문자열이거나 더 복잡한 일치를 위한 패턴일 수 있습니다.
• regexp (선택사항): 소스를 기반으로 일치를 세부 조정하는 정규 표현식 문자열. 어떤 경로를 포함하거나 제외할지에 대한 추가적인 제어를 제공합니다.
• locale (선택사항): false로 설정하면 경로 일치에서 로케일 기반 라우팅을 무시합니다.
• has (선택사항): 헤더, 쿼리 매개변수 또는 쿠키와 같은 특정 요청 요소의 존재를 기반으로 조건을 지정합니다.
• missing (선택사항): 누락된 헤더나 쿠키와 같이 특정 요청 요소가 없는 조건에 초점을 맞춥니다.

export const config = {
  matcher: [
    {
      source: "/api/*",
      regexp: "^/api/(.*)",
      locale: false,
      has: [
        { type: "header", key: "Authorization", value: "Bearer Token" },
        { type: "query", key: "userId", value: "123" },
      ],
      missing: [{ type: "cookie", key: "session", value: "active" }],
    },
  ],
};

매개변수

request

미들웨어를 정의할 때 기본 내보내기 함수는 단일 매개변수인 request를 받습니다. 이 매개변수는 들어오는 HTTP 요청을 나타내는 NextRequest의 인스턴스입니다.

import type { NextRequest } from "next/server";
 
export function middleware(request: NextRequest) {
  // 여기에 미들웨어 로직이 들어갑니다
}

export function middleware(request) {
  // 여기에 미들웨어 로직이 들어갑니다
}

알아두면 좋은 점:

• NextRequest는 Next.js 미들웨어에서 들어오는 HTTP 요청을 나타내는 타입이며, NextResponse는 HTTP 응답을 조작하고 다시 보내는 데 사용되는 클래스입니다.

NextResponse

미들웨어는 Web Response API를 확장하는 NextResponse 객체를 사용할 수 있습니다. NextResponse 객체를 반환함으로써 쿠키를 직접 조작하고, 헤더를 설정하며, 리다이렉트를 구현하고, 경로를 재작성할 수 있습니다.

알아두면 좋은 점: 리다이렉트의 경우 NextResponse.redirect 대신 Response.redirect를 사용할 수도 있습니다.

런타임

미들웨어는 Edge 런타임만 지원합니다. Node.js 런타임은 사용할 수 없습니다.

버전 기록