diff --git a/docs/02-app/01-building-your-application/01-routing/11-middleware.mdx b/docs/02-app/01-building-your-application/01-routing/11-middleware.mdx index 03edf864d..48c039392 100644 --- a/docs/02-app/01-building-your-application/01-routing/11-middleware.mdx +++ b/docs/02-app/01-building-your-application/01-routing/11-middleware.mdx @@ -1,54 +1,54 @@ --- -title: Middleware -description: Learn how to use Middleware to run code before a request is completed. +title: 미들웨어 +description: 요청이 완료되기 전에 미들웨어를 사용하여 코드를 실행하는 방법을 알아보세요. --- -Middleware allows you to run code before a request is completed. Then, based on the incoming request, you can modify the response by rewriting, redirecting, modifying the request or response headers, or responding directly. +미들웨어를 사용하면 요청이 완료되기 전에 코드를 실행할 수 있습니다. 그런 다음 들어오는 요청에 따라 응답을 재작성하거나, 리다이렉트하거나, 요청 또는 응답 헤더를 수정하거나, 직접 응답함으로써 응답을 수정할 수 있습니다. -Middleware runs before cached content and routes are matched. See [Matching Paths](#matching-paths) for more details. +미들웨어는 캐시 된 컨텐츠와 경로가 일치되기 전에 실행됩니다. 자세한 내용은 [경로 일치](#matching-paths)를 참조하세요. -## Convention +## 규칙 -Use the file `middleware.ts` (or `.js`) in the root of your project to define Middleware. For example, at the same level as `pages` or `app`, or inside `src` if applicable. +프로젝트의 루트에서 `middleware.ts`(또는 `.js`) 파일을 사용하여 미들웨어를 정의합니다. 예를 들어, `pages` 또는 `app`과 같은 레벨에 있거나 해당하는 경우 `src` 내부에 정의합니다. -## Example +## 예시 ```ts filename="middleware.ts" import { NextResponse } from 'next/server' import type { NextRequest } from 'next/server' -// This function can be marked `async` if using `await` inside +// 만약 내부에서 `await`을 사용한다면, 이 함수는 `async`로 표시될 수 있습니다. export function middleware(request: NextRequest) { return NextResponse.redirect(new URL('/home', request.url)) } -// See "Matching Paths" below to learn more +// 아래의 "경로 일치"를 참조하여 더 자세히 알아보세요. export const config = { matcher: '/about/:path*', } ``` -## Matching Paths +## 경로 일치 -Middleware will be invoked for **every route in your project**. The following is the execution order: +프로젝트의 **모든 경로**에 대해 미들웨어가 호출됩니다. 실행 순서는 다음과 같습니다: -1. `headers` from `next.config.js` -2. `redirects` from `next.config.js` -3. Middleware (`rewrites`, `redirects`, etc.) -4. `beforeFiles` (`rewrites`) from `next.config.js` -5. Filesystem routes (`public/`, `_next/static/`, `pages/`, `app/`, etc.) -6. `afterFiles` (`rewrites`) from `next.config.js` -7. Dynamic Routes (`/blog/[slug]`) -8. `fallback` (`rewrites`) from `next.config.js` +1. `next.config.js`의 `headers` +2. `next.config.js`의 `redirects` +3. 미들웨어 (`rewrites`, `redirects` 등) +4. `next.config.js`의 `beforeFiles` (`rewrites`) +5. 파일 시스템 경로 (`public/`, `_next/static/`, `pages/`, `app/` 등) +6. `next.config.js`의 `afterFiles` (`rewrites`) +7. 동적 경로 (`/blog/[slug]`) +8. `next.config.js`의 `fallback` (`rewrites`) -There are two ways to define which paths Middleware will run on: +미들웨어가 실행될 경로를 정의하는 방법에는 두 가지가 있습니다: -1. [Custom matcher config](#matcher) -2. [Conditional statements](#conditional-statements) +1. [사용자 정의 matcher 구성](#matcher) +2. [조건문](#conditional-statements) ### Matcher -`matcher` allows you to filter Middleware to run on specific paths. +`matcher`를 사용하면 특정 경로에서 실행할 미들웨어를 필터링할 수 있습니다. ```js filename="middleware.js" export const config = { @@ -56,7 +56,7 @@ export const config = { } ``` -You can match a single path or multiple paths with an array syntax: +배열 문법을 사용하여 단일 경로 또는 여러 경로를 일치시킬 수 있습니다: ```js filename="middleware.js" export const config = { @@ -64,37 +64,37 @@ export const config = { } ``` -The `matcher` config allows full regex so matching like negative lookaheads or character matching is supported. An example of a negative lookahead to match all except specific paths can be seen here: +`matcher` 구성은 부정적 전방탐색(negative lookahead) 또는 문자 일치(character matching)와 같은 완전한 정규식을 지원합니다. 특정 경로를 제외한 모든 경로와 일치하는 부정적 전방탐색의 예는 다음과 같습니다: ```js filename="middleware.js" export const config = { matcher: [ - /* - * Match all request paths except for the ones starting with: - * - api (API routes) - * - _next/static (static files) - * - _next/image (image optimization files) - * - favicon.ico (favicon file) - */ + /* + * 다음과 같이 시작하는 경로를 제외한 모든 요청 경로와 일치시킵니다: + * - api (API 경로) + * - _next/static (정적 파일) + * - _next/image (이미지 최적화 파일) + * - favicon.ico (파비콘 파일) + */ '/((?!api|_next/static|_next/image|favicon.ico).*)', ], } ``` -> **Good to know**: The `matcher` values need to be constants so they can be statically analyzed at build-time. Dynamic values such as variables will be ignored. +> **참고**: `matcher` 값은 상수이어야 하므로 빌드 시 정적으로 분석될 수 있습니다. 변수와 같은 동적 값은 무시됩니다. -Configured matchers: +matcher 구성: -1. MUST start with `/` -2. Can include named parameters: `/about/:path` matches `/about/a` and `/about/b` but not `/about/a/c` -3. Can have modifiers on named parameters (starting with `:`): `/about/:path*` matches `/about/a/b/c` because `*` is _zero or more_. `?` is _zero or one_ and `+` _one or more_ -4. Can use regular expression enclosed in parenthesis: `/about/(.*)` is the same as `/about/:path*` +1. 반드시 `/`로 시작해야 합니다. +2. 이름 있는 매개변수를 포함할 수 있습니다: `/about/:path`는 `/about/a`와 `/about/b`와 일치하지만 `/about/a/c`와는 일치하지 않습니다. +3. 이름 있는 매개변수에는 수정자(콜론으로 시작함)를 사용할 수 있습니다: `/about/:path*`는 `*`가 _0개 이상_을 의미하기 때문에 `/about/a/b/c`와 일치합니다. `?`는 _0개 또는 1개_, `+`는 _1개 이상_을 의미합니다. +4. 괄호로 둘러싸인 정규식을 사용할 수 있습니다: `/about/(.*)`는 `/about/:path*`와 동일한 의미를 가집니다. -Read more details on [path-to-regexp](https://github.com/pillarjs/path-to-regexp#path-to-regexp-1) documentation. +자세한 내용은 [path-to-regexp](https://github.com/pillarjs/path-to-regexp#path-to-regexp-1) 문서를 참조하세요. -> **Good to know**: For backward compatibility, Next.js always considers `/public` as `/public/index`. Therefore, a matcher of `/public/:path` will match. +> **참고**: 이전 버전과의 호환성을 위해 Next.js는 항상 `/public`을 `/public/index`로 간주합니다. 따라서 `/public/:path`와 같은 matcher는 일치합니다. -### Conditional Statements +### 조건문 ```ts filename="middleware.ts" import { NextResponse } from 'next/server' @@ -113,33 +113,33 @@ export function middleware(request: NextRequest) { ## NextResponse -The `NextResponse` API allows you to: +`NextResponse` API를 사용하면 다음 작업을 수행할 수 있습니다: -- `redirect` the incoming request to a different URL -- `rewrite` the response by displaying a given URL -- Set request headers for API Routes, `getServerSideProps`, and `rewrite` destinations -- Set response cookies -- Set response headers +- 들어오는 요청을 다른 URL로 `리다이렉트` +- 주어진 URL을 표시하여 응답 `재작성` +- API 경로, `getServerSideProps`, 및 `재작성` 대상에 대한 요청 헤더 설정 +- 응답 쿠키 설정 +- 응답 헤더 설정 -To produce a response from Middleware, you can: +미들웨어에서 응답을 생성하려면 다음 중 하나를 수행할 수 있습니다: -1. `rewrite` to a route ([Page](/docs/pages/building-your-application/routing/pages-and-layouts) or [Edge API Route](/docs/pages/building-your-application/routing/api-routes)) that produces a response -2. return a `NextResponse` directly. See [Producing a Response](#producing-a-response) +1. 응답을 생성하는 경로([Page](/docs/pages/building-your-application/routing/pages-and-layouts) 또는 [Edge API Route](/docs/pages/building-your-application/routing/api-routes))로 `재작성`합니다. +2. 직접 `NextResponse`를 반환합니다. [응답 생성하기](#producing-a-response)를 참조하세요. -## Using Cookies +## 쿠키 사용하기 -Cookies are regular headers. On a `Request`, they are stored in the `Cookie` header. On a `Response` they are in the `Set-Cookie` header. Next.js provides a convenient way to access and manipulate these cookies through the `cookies` extension on `NextRequest` and `NextResponse`. +쿠키는 일반적인 헤더입니다. `Request`에서는 `Cookie` 헤더에 저장되고, `Response`에서는 `Set-Cookie` 헤더에 저장됩니다. Next.js는 `NextRequest`와 `NextResponse`의 `cookies` 확장자를 통해 이러한 쿠키에 쉽게 접근하고 조작할 수 있는 편리한 방법을 제공합니다. -1. For incoming requests, `cookies` comes with the following methods: `get`, `getAll`, `set`, and `delete` cookies. You can check for the existence of a cookie with `has` or remove all cookies with `clear`. -2. For outgoing responses, `cookies` have the following methods `get`, `getAll`, `set`, and `delete`. +1. 들어오는 요청의 경우 `cookies`에는 `get`, `getAll`, `set`, `delete` 쿠키 메서드가 제공됩니다. has`로 쿠키의 존재 여부를 확인하거나 `clear`로 모든 쿠키를 제거할 수 있습니다. +2. 나가는 응답의 경우 `cookies`에는 `get`, `getAll`, `set`, `delete` 메서드가 있습니다. ```ts filename="middleware.ts" import { NextResponse } from 'next/server' import type { NextRequest } from 'next/server' export function middleware(request: NextRequest) { - // Assume a "Cookie:nextjs=fast" header to be present on the incoming request - // Getting cookies from the request using the `RequestCookies` API + // 들어오는 요청에 "Cookie: nextjs=fast" 헤더가 있는 것으로 가정 + // `RequestCookies` API를 사용하여 요청에서 쿠키 가져오기 let cookie = request.cookies.get('nextjs') console.log(cookie) // => { name: 'nextjs', value: 'fast', Path: '/' } const allCookies = request.cookies.getAll() @@ -149,7 +149,7 @@ export function middleware(request: NextRequest) { request.cookies.delete('nextjs') request.cookies.has('nextjs') // => false - // Setting cookies on the response using the `ResponseCookies` API + // `ResponseCookies` API를 사용하여 응답에 쿠키 설정하기 const response = NextResponse.next() response.cookies.set('vercel', 'fast') response.cookies.set({ @@ -159,34 +159,35 @@ export function middleware(request: NextRequest) { }) cookie = response.cookies.get('vercel') console.log(cookie) // => { name: 'vercel', value: 'fast', Path: '/' } - // The outgoing response will have a `Set-Cookie:vercel=fast;path=/test` header. + // 나가는 응답에는 `Set-Cookie: vercel=fast; path=/test` 헤더가 포함됨 return response } ``` -## Setting Headers +## 헤더 설정하기 -You can set request and response headers using the `NextResponse` API (setting _request_ headers is available since Next.js v13.0.0). +`NextResponse` API를 사용하여 요청과 응답 헤더를 설정할 수 있습니다 (요청 헤더 설정은 Next.js v13.0.0 이상에서 사용 가능합니다). ```ts filename="middleware.ts" switcher import { NextResponse } from 'next/server' import type { NextRequest } from 'next/server' export function middleware(request: NextRequest) { - // Clone the request headers and set a new header `x-hello-from-middleware1` + + // 요청 헤더를 복제하고 새로운 헤더 `x-hello-from-middleware1`를 설정 const requestHeaders = new Headers(request.headers) requestHeaders.set('x-hello-from-middleware1', 'hello') - // You can also set request headers in NextResponse.rewrite + // NextResponse.rewrite에서도 요청 헤더를 설정할 수 있음 const response = NextResponse.next({ request: { - // New request headers + // 새 요청 헤더 headers: requestHeaders, }, }) - // Set a new response header `x-hello-from-middleware2` + // 새 응답 헤더 `x-hello-from-middleware2` 설정 response.headers.set('x-hello-from-middleware2', 'hello') return response } @@ -196,19 +197,19 @@ export function middleware(request: NextRequest) { import { NextResponse } from 'next/server' export function middleware(request) { - // Clone the request headers and set a new header `x-hello-from-middleware1` + // 요청 헤더를 복제하고 새로운 헤더 `x-hello-from-middleware1`를 설정 const requestHeaders = new Headers(request.headers) requestHeaders.set('x-hello-from-middleware1', 'hello') - // You can also set request headers in NextResponse.rewrite + // NextResponse.rewrite에서도 요청 헤더를 설정할 수 있음 const response = NextResponse.next({ request: { - // New request headers + // 새 요청 헤더 headers: requestHeaders, }, }) - // Set a new response header `x-hello-from-middleware2` + // 새 응답 헤더 `x-hello-from-middleware2` 설정 response.headers.set('x-hello-from-middleware2', 'hello') return response } @@ -216,23 +217,25 @@ export function middleware(request) { > **Good to know**: Avoid setting large headers as it might cause [431 Request Header Fields Too Large](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/431) error depending on your backend web server configuration. -## Producing a Response +> **참고**: 백엔드 웹 서버 구성에 따라 [431 Request Header Fields Too Large](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/431) 오류가 발생할 수 있으므로 큰 헤더를 설정하는 것을 피하십시오. -You can respond from Middleware directly by returning a `Response` or `NextResponse` instance. (This is available since [Next.js v13.1.0](https://nextjs.org/blog/next-13-1#nextjs-advanced-middleware)) +## 응답 생성하기 + +미들웨어에서는 `Response` 또는 `NextResponse` 인스턴스를 직접 반환하여 응답할 수 있습니다. (이 기능은 [Next.js v13.1.0](https://nextjs.org/blog/next-13-1#nextjs-advanced-middleware)부터 사용 가능합니다) ```ts filename="middleware.ts" switcher import { NextRequest, NextResponse } from 'next/server' import { isAuthenticated } from '@lib/auth' -// Limit the middleware to paths starting with `/api/` +// 미들웨어를 `/api/`로 시작하는 경로로 제한 export const config = { matcher: '/api/:function*', } export function middleware(request: NextRequest) { - // Call our authentication function to check the request + // 요청을 확인하기 위해 인증 함수를 호출 if (!isAuthenticated(request)) { - // Respond with JSON indicating an error message + // 오류 메시지를 나타내는 JSON으로 응답 return new NextResponse( JSON.stringify({ success: false, message: 'authentication failed' }), { status: 401, headers: { 'content-type': 'application/json' } } @@ -245,15 +248,15 @@ export function middleware(request: NextRequest) { import { NextResponse } from 'next/server' import { isAuthenticated } from '@lib/auth' -// Limit the middleware to paths starting with `/api/` +// 미들웨어를 `/api/`로 시작하는 경로로 제한 export const config = { matcher: '/api/:function*', } export function middleware(request) { - // Call our authentication function to check the request + // 요청을 확인하기 위해 인증 함수를 호출 if (!isAuthenticated(request)) { - // Respond with JSON indicating an error message + // 오류 메시지를 나타내는 JSON으로 응답 return new NextResponse( JSON.stringify({ success: false, message: 'authentication failed' }), { status: 401, headers: { 'content-type': 'application/json' } } @@ -268,6 +271,12 @@ In `v13.1` of Next.js two additional flags were introduced for middleware, `skip `skipTrailingSlashRedirect` allows disabling Next.js default redirects for adding or removing trailing slashes allowing custom handling inside middleware which can allow maintaining the trailing slash for some paths but not others allowing easier incremental migrations. +## 고급 미들웨어 플래그 + +skipTrailingSlashRedirect`를 사용하면 후행 슬래시를 추가하거나 제거하기 위한 Next.js 기본 리디렉션을 비활성화하여 미들웨어 내부에서 사용자 정의 처리를 통해 일부 경로에는 후행 슬래시를 유지하지만 다른 경로에는 유지하지 않을 수 있어 증분 마이그레이션이 더 쉬워질 수 있습니다. + +`skipTrailingSlashRedirect`는 Next.js의 기본 리다이렉션을 비활성화하여 미들웨어 내에서 사용자 정의 처리를 할 수 있게 해줍니다. 이를 통해 일부 경로에 대해 trailing slash를 유지하지만 다른 경로에서는 사용하지 않을 수 있어 점진적인 마이그레이션을 더 쉽게 수행할 수 있습니다. + ```js filename="next.config.js" module.exports = { skipTrailingSlashRedirect: true, @@ -284,7 +293,7 @@ export default async function middleware(req) { return NextResponse.next() } - // apply trailing slash handling + // trailing slash 처리 적용 if ( !pathname.endsWith('/') && !pathname.match(/((?!\.well-known(?:\/.*)?)(?:[^/]+\/)*[^/]+\.\w+)/) @@ -295,7 +304,7 @@ export default async function middleware(req) { } ``` -`skipMiddlewareUrlNormalize` allows disabling the URL normalizing Next.js does to make handling direct visits and client-transitions the same. There are some advanced cases where you need full control using the original URL which this unlocks. +`skipMiddlewareUrlNormalize`은 Next.js에서 직접 방문과 클라이언트 전환을 처리하기 위해 수행하는 URL 정규화를 비활성화하는 기능입니다. 이를 통해 원래의 URL을 사용하여 완전한 제어가 필요한 고급 상황이 있는 경우 이를 가능하게 합니다. ```js filename="next.config.js" module.exports = { @@ -310,17 +319,17 @@ export default async function middleware(req) { // GET /_next/data/build-id/hello.json console.log(pathname) - // with the flag this now /_next/data/build-id/hello.json - // without the flag this would be normalized to /hello + // 플래그가 있으면 /_next/data/build-id/hello.json + // 플래그가 없으면 /hello로 정규화됨 } ``` -## Version History +## 버전 기록 -| Version | Changes | +| 버전 | 변경 내용 | | --------- | --------------------------------------------------------------------------------------------- | -| `v13.1.0` | Advanced Middleware flags added | -| `v13.0.0` | Middleware can modify request headers, response headers, and send responses | -| `v12.2.0` | Middleware is stable, please see the [upgrade guide](/docs/messages/middleware-upgrade-guide) | -| `v12.0.9` | Enforce absolute URLs in Edge Runtime ([PR](https://github.com/vercel/next.js/pull/33410)) | -| `v12.0.0` | Middleware (Beta) added | +| `v13.1.0` | 고급 미들웨어 플래그 추가 | +| `v13.0.0` | 미들웨어에서 요청 헤더, 응답 헤더를 수정하고 응답을 전송할 수 있도록 함 | +| `v12.2.0` | 미들웨어가 안정화되었으며 [업그레이드 가이드](/docs/messages/middleware-upgrade-guide)를 참조하세요 | +| `v12.0.9` | Edge Runtime에서 절대 URL 강제 적용 ([PR](https://github.com/vercel/next.js/pull/33410)) | +| `v12.0.0` | 미들웨어 (Beta) 추가 | \ No newline at end of file