next/server
는 미들웨어 및 Edge API 라우트에서 사용할 수 있는 서버 전용 도우미를 제공합니다.
NextRequest
객체는 기존 Request
인터페이스를 확장하여 다음과 같은 추가 메서드와 속성을 가집니다.
cookies
- Request
에서 쿠키를 담은 RequestCookies
인스턴스입니다. 요청의 Cookie
헤더를 읽거나 수정합니다. 미들웨어에서 쿠키 사용하기를 참조하세요.
get
- 쿠키 이름을 인자로 받아 해당 쿠키의 이름과 값을 가진 객체를 반환합니다. 해당 이름의 쿠키를 찾을 수 없으면 undefined
를 반환합니다. 여러 개의 쿠키가 일치하는 경우 첫 번째 일치하는 것만 반환합니다.getAll
- get
과 비슷하지만, 모든 해당 이름의 쿠키 목록을 반환합니다. 이름을 지정하지 않으면 사용 가능한 모든 쿠키를 반환합니다.set
- W3C CookieStore API 명세의 CookieListItem
속성을 가진 객체를 인자로 받습니다.delete
- 쿠키 이름 또는 이름 목록을 인자로 받아 일치하는 쿠키를 제거합니다. 삭제된 쿠키는 true
, 삭제되지 않은 쿠키는 false
를 반환합니다.has
- 쿠키 이름을 인자로 받아 해당 쿠키가 존재하는지 여부에 따라 불리언 값을 반환합니다.clear
- 인자를 받지 않고 Cookie
헤더를 효과적으로 제거합니다.nextUrl
: Next.js 특정 속성인 pathname
, basePath
, trailingSlash
및 i18n
에 액세스할 수 있는 확장된 파싱된 URL 객체를 포함합니다. 다음과 같은 속성을 가집니다.
basePath
(string)buildId
(string || undefined)defaultLocale
(string || undefined)domainLocale
defaultLocale
: (string)domain
: (string)http
: (boolean || undefined)locales
: (string[] || undefined)locale
(string || undefined)url
(URL)ip
: (string || undefined) - 요청의 IP 주소를 가지고 있습니다. 이 정보는 호스팅 플랫폼에서 제공됩니다.
geo
- 요청의 지리적 위치를 가지고 있습니다. 이 정보는 호스팅 플랫폼에서 제공됩니다. 다음과 같은 속성을 가집니다.
city
(string || undefined)country
(string || undefined)region
(string || undefined)latitude
(string || undefined)longitude
(string || undefined)NextRequest
객체를 사용하여 요청을 조작하는 방법을 보다 세밀하게 제어할 수 있습니다.
NextRequest
는 다음과 같이 next/server
에서 가져올 수 있습니다.
import type { NextRequest } from 'next/server';
NextFetchEvent
객체는 기본 FetchEvent
객체를 확장하여 waitUntil()
메서드를 포함하고 있습니다.
waitUntil()
메서드는 기타 백그라운드 작업을 수행해야하는 경우 함수의 실행을 연장하는 데 사용할 수 있습니다.
import { NextResponse } from 'next/server';
import type { NextFetchEvent, NextRequest } from 'next/server';
export function middleware(req: NextRequest, event: NextFetchEvent) {
event.waitUntil(
fetch('https://my-analytics-platform.com', {
method: 'POST',
body: JSON.stringify({ pathname: req.nextUrl.pathname }),
})
);
return NextResponse.next();
}
NextFetchEvent
객체는 next/server
에서 가져올 수 있습니다.
import type { NextFetchEvent } from 'next/server';
NextResponse
클래스는 다음과 같은 기본 응답 인터페이스를 확장합니다.
공개 메서드는 NextResponse 클래스의 인스턴스에서 사용할 수 있습니다. 사용 사례에 따라 인스턴스를 만들고 변수에 할당한 다음 다음 공개 메서드에 액세스할 수 있습니다.
cookies
- 응답에서 가져온 쿠키를 포함하는 ResponseCookies 인스턴스입니다. 응답의 Set-Cookie 헤더를 읽거나 수정합니다. Middleware에서 쿠키 사용 방법도 참조하십시오.get
- 쿠키 이름을 인수로 사용하여 이름과 값이 포함된 객체를 반환하는 메서드입니다. 해당 이름의 쿠키가 없으면 undefined를 반환합니다. 여러 쿠키가 일치하는 경우 첫 번째 일치 항목만 반환됩니다.getAll
- get과 유사하지만 일치하는 이름의 모든 쿠키 목록을 반환합니다. 이름이 지정되지 않으면 사용 가능한 모든 쿠키를 반환합니다.set
- W3C CookieStore API 사양에서 정의된 CookieListItem 속성을 가진 객체를 인수로 사용하는 메서드입니다.delete
- 쿠키 이름 또는 이름 목록을 인수로 사용하며 해당 이름과 일치하는 쿠키를 제거합니다. 삭제된 경우 true를 반환하고 삭제되지 않은 경우 false를 반환합니다.다음 정적 메서드는 NextResponse
클래스에서 직접 사용할 수 있습니다.
redirect()
- 리디렉션을 설정한 NextResponse
를 반환합니다.rewrite()
- 리라이트를 설정한 NextResponse
를 반환합니다.next()
- 미들웨어 체인을 계속 진행하는 NextResponse
를 반환합니다.NextResponse
객체를 반환해야합니다. NextResponse
는 next/server에서 가져올 수 있습니다.import { NextResponse } from 'next/server';
userAgent
도우미는 요청의 user agent
객체와 상호 작용할 수 있게 해줍니다. 이는 네이티브 Request 객체에서 추상화되었으며, 선택적으로 사용할 수 있는 기능입니다. 다음과 같은 속성이 있습니다:
isBot
: (boolean) 요청이 알려진 봇에서 왔는지 여부browser
name
: (string || undefined) 브라우저의 이름version
: (string || undefined) 동적으로 결정된 브라우저 버전device
model
: (string || undefined) 동적으로 결정된 기기 모델type
: (string || undefined) 브라우저의 유형으로, 다음 값 중 하나일 수 있습니다: console, mobile, tablet, smarttv, wearable, embedded 또는 undefinedvendor
: (string || undefined) 동적으로 결정된 기기의 공급 업체engine
name
: (string || undefined) 브라우저 엔진의 이름으로, 다음 값 중 하나일 수 있습니다: Amaya, Blink, EdgeHTML, Flow, Gecko, Goanna, iCab, KHTML, Links, Lynx, NetFront, NetSurf, Presto, Tasman, Trident, w3m, WebKit 또는 undefinedversion
: (string || undefined) 동적으로 결정된 브라우저 엔진 버전 또는 undefinedos
name
: (string || undefined) 운영 체제의 이름으로 undefined일 수 있습니다.version
: (string || undefined) 동적으로 결정된 운영 체제의 버전 또는 undefinedcpu
architecture
: (string || undefined) CPU의 아키텍처로 다음 값 중 하나일 수 있습니다: 68k, amd64, arm, arm64, armhf, avr, ia32, ia64, irix, irix64, mips, mips64, pa-risc, ppc, sparc, sparc64 또는 undefineduserAgent는 다음을 통해 next/server에서 가져올 수 있습니다:
import { userAgent } from 'next/server';
import { NextRequest, NextResponse, userAgent } from 'next/server';
export function middleware(request: NextRequest) {
const url = request.nextUrl;
const { device } = userAgent(request);
const viewport = device.type === 'mobile' ? 'mobile' : 'desktop';
url.searchParams.set('viewport', viewport);
return NextResponse.rewrite(url);
}
redirect()
를 사용할 때 일시적인 리디렉션에는 307
을, 영구적인 리디렉션에는 308
을 사용한다는 것을 알 수 있습니다. 일반적으로 일시적인 리디렉션에는 302
가 사용되었고, 영구적인 리디렉션에는 301
이 사용되었습니다. 그러나 많은 브라우저들은 302
를 사용하는 경우 리디렉션이 POST
요청에서 GET
요청으로 변경되어버렸습니다.
/users
에서 /people
로 리디렉션하는 경우, 새로운 사용자를 만들기 위해 /users
로 POST
요청을 한 경우, 302
일시적인 리디렉션을 준수하는 경우, 요청 방법이 POST
에서 GET
요청으로 변경됩니다. 이것은 올바르지 않습니다. 새로운 사용자를 만들기 위해서는 POST
요청을 /people
로 해야 합니다.
307
상태 코드가 도입되면 요청 방법이 POST
로 보존됩니다.
302
- 일시적인 리디렉션, 요청 방법을 POST
에서 GET
으로 변경합니다.307
- 일시적인 리디렉션, 요청 방법을 POST
로 보존합니다.redirect()
메서드는 기본적으로 307
을 사용합니다. 따라서 요청이 항상 POST
요청으로 보존됩니다.POST
요청에 대한 GET
응답을 유도하려면 303
을 사용하면 됩니다.HTTP
리디렉션에 대해 더 알아보세요.
process.env
를 사용하여 Edge
미들웨어에서 환경 변수에 액세스할 수 있습니다. 이는 next
빌드 중에 평가됩니다.
작동 방식 | 작동하지 않는 방식 |
---|---|
console.log(process.env.MY_ENV_VARIABLE) | const getEnv = name => process.env[name] |
const { MY_ENV_VARIABLE } = process.env | |
const { "MY-ENV-VARIABLE": MY_ENV_VARIABLE } = process.env |