API 레퍼런스: Edge Runtime | Next.js

출처 URL: https://nextjs.org/docs/pages/api-reference/edge

Pages Router API 레퍼런스Edge Runtime

엣지 런타임

마지막 업데이트: 2026년 2월 20일

Next.js 애플리케이션에서는 두 가지 서버 런타임을 사용할 수 있습니다.

Node.js 런타임(기본값): 모든 Node.js API에 접근할 수 있으며 애플리케이션을 렌더링할 때 사용됩니다.
Edge Runtime: 제한된 API 집합을 제공하며 Proxy에서 사용됩니다.

주의 사항

Edge Runtime은 모든 Node.js API를 지원하지 않으므로 일부 패키지가 예상대로 동작하지 않을 수 있습니다.
Edge Runtime은 Incremental Static Regeneration(ISR)을 지원하지 않습니다.
두 런타임 모두 배포 어댑터에 따라 스트리밍을 지원할 수 있습니다.

참조

Edge Runtime은 다음 API를 지원합니다.

네트워크 API

API	설명
`Blob`	Blob을 나타냅니다
`fetch`	리소스를 가져옵니다
`FetchEvent`	fetch 이벤트를 나타냅니다
`File`	파일을 나타냅니다
`FormData`	폼 데이터를 나타냅니다
`Headers`	HTTP 헤더를 나타냅니다
`Request`	HTTP 요청을 나타냅니다
`Response`	HTTP 응답을 나타냅니다
`URLSearchParams`	URL 검색 매개변수를 나타냅니다
`WebSocket`	웹소켓 연결을 나타냅니다

인코딩 API

API	설명
`atob`	base-64로 인코딩된 문자열을 디코딩합니다
`btoa`	문자열을 base-64로 인코딩합니다
`TextDecoder`	Uint8Array를 문자열로 디코딩합니다
`TextDecoderStream`	스트림을 위한 체이닝 가능한 디코더입니다
`TextEncoder`	문자열을 Uint8Array로 인코딩합니다
`TextEncoderStream`	스트림을 위한 체이닝 가능한 인코더입니다

스트림 API

API	설명
`ReadableStream`	읽기 가능한 스트림을 나타냅니다
`ReadableStreamBYOBReader`	ReadableStream의 리더를 나타냅니다
`ReadableStreamDefaultReader`	ReadableStream의 리더를 나타냅니다
`TransformStream`	변환 스트림을 나타냅니다
`WritableStream`	쓰기 가능한 스트림을 나타냅니다
`WritableStreamDefaultWriter`	WritableStream의 라이터를 나타냅니다

암호화 API

API	설명
`crypto`	플랫폼의 암호화 기능에 접근합니다
`CryptoKey`	암호화 키를 나타냅니다
`SubtleCrypto`	해시, 서명, 암호화 또는 복호화와 같은 일반적인 암호화 프리미티브에 접근합니다

웹 표준 API

API	설명
`AbortController`	원하는 시점에 하나 이상의 DOM 요청을 중단할 수 있습니다
`Array`	값의 배열을 나타냅니다
`ArrayBuffer`	고정 길이 원시 이진 데이터 버퍼를 나타냅니다
`Atomics`	정적 메서드로 원자적 연산을 제공합니다
`BigInt`	임의 정밀도의 정수를 나타냅니다
`BigInt64Array`	64비트 부호 있는 정수의 타입 배열을 나타냅니다
`BigUint64Array`	64비트 부호 없는 정수의 타입 배열을 나타냅니다
`Boolean`	논리 값을 나타내며 `true` 또는 `false` 값을 가질 수 있습니다
`clearInterval`	`setInterval()`로 설정된 반복 동작을 취소합니다
`clearTimeout`	`setTimeout()`으로 설정된 반복 동작을 취소합니다
`console`	브라우저 디버깅 콘솔에 접근합니다
`DataView`	`ArrayBuffer`의 일반적인 뷰를 나타냅니다
`Date`	플랫폼에 독립적인 형식의 특정 시점을 나타냅니다
`decodeURI`	`encodeURI` 또는 유사한 루틴으로 생성된 URI를 디코딩합니다
`decodeURIComponent`	`encodeURIComponent` 또는 유사한 루틴으로 생성된 URI 구성 요소를 디코딩합니다
`DOMException`	DOM에서 발생하는 오류를 나타냅니다
`encodeURI`	특정 문자를 UTF-8 이스케이프 시퀀스로 치환하여 URI를 인코딩합니다
`encodeURIComponent`	특정 문자를 UTF-8 이스케이프 시퀀스로 치환하여 URI 구성 요소를 인코딩합니다
`Error`	구문 실행이나 속성 접근 중 발생하는 오류를 나타냅니다
`EvalError`	전역 함수 `eval()`과 관련된 오류를 나타냅니다
`Float32Array`	32비트 부동소수점 수의 타입 배열을 나타냅니다
`Float64Array`	64비트 부동소수점 수의 타입 배열을 나타냅니다
`Function`	함수를 나타냅니다
`Infinity`	수학적 무한대를 나타냅니다
`Int8Array`	8비트 부호 있는 정수의 타입 배열을 나타냅니다
`Int16Array`	16비트 부호 있는 정수의 타입 배열을 나타냅니다
`Int32Array`	32비트 부호 있는 정수의 타입 배열을 나타냅니다
`Intl`	국제화 및 현지화 기능에 접근합니다
`isFinite`	값이 유한한 숫자인지 판별합니다
`isNaN`	값이 `NaN`인지 여부를 판별합니다
`JSON`	JavaScript 값을 JSON 형식으로 변환하거나 그 반대로 변환하는 기능을 제공합니다
`Map`	각 값이 한 번만 나타나는 값의 컬렉션을 나타냅니다
`Math`	수학 함수와 상수에 접근합니다
`Number`	숫자 값을 나타냅니다
`Object`	모든 JavaScript 객체의 기반이 되는 객체를 나타냅니다
`parseFloat`	문자열 인수를 파싱하여 부동소수점 숫자를 반환합니다
`parseInt`	문자열 인수를 파싱하여 지정된 기수의 정수를 반환합니다
`Promise`	비동기 작업의 최종 완료(또는 실패)와 그 결과 값을 나타냅니다
`Proxy`	속성 조회, 할당, 열거, 함수 호출 등 기본 연산의 동작을 사용자 정의하는 객체를 나타냅니다
`queueMicrotask`	실행할 마이크로태스크를 큐에 추가합니다
`RangeError`	값이 허용된 집합 또는 범위를 벗어났을 때의 오류를 나타냅니다
`ReferenceError`	존재하지 않는 변수를 참조했을 때의 오류를 나타냅니다
`Reflect`	가로챌 수 있는 JavaScript 연산을 위한 메서드를 제공합니다

Next.js 전용 폴리필

AsyncLocalStorage

환경 변수

next dev와 next build 모두에서 Environment Variables에 접근하려면 process.env를 사용할 수 있습니다.

지원되지 않는 API

Edge Runtime에는 다음과 같은 제한이 있습니다.

네이티브 Node.js API는 지원되지 않습니다. 예를 들어 파일 시스템을 읽거나 쓸 수 없습니다.
node_modules 는 ES Modules를 구현하고 네이티브 Node.js API를 사용하지 않는 한 사용할 수 있습니다.
require를 직접 호출하는 것은 허용되지 않습니다. 대신 ES Modules를 사용하세요.

다음 JavaScript 언어 기능은 비활성화되어 있으며, 작동하지 않습니다.

API	설명
`eval`	문자열로 표현된 JavaScript 코드를 평가합니다.
`new Function(evalString)`	인자로 제공한 코드로 새 함수를 생성합니다.
`WebAssembly.compile`	버퍼 소스에서 WebAssembly 모듈을 컴파일합니다.
`WebAssembly.instantiate`	버퍼 소스에서 WebAssembly 모듈을 컴파일하고 인스턴스화합니다.

드물게 코드가 (또는 import된 코드가) 런타임에 도달할 수 없고 treeshaking으로 제거할 수 없는 동적 코드 평가 구문을 포함할 수 있습니다. Proxy 구성을 사용해 특정 파일을 허용하도록 검사를 완화할 수 있습니다.

proxy.ts

    export const config = {
      unstable_allowDynamic: [
        // allows a single file
        '/lib/utilities.js',
        // use a glob to allow anything in the function-bind 3rd party module
        '**/node_modules/function-bind/**',
      ],
    }

unstable_allowDynamic은 특정 파일에 대해 동적 코드 평가를 무시하는 glob이거나 glob 배열입니다. glob은 애플리케이션 루트 폴더를 기준으로 합니다.

이 구문이 Edge에서 실행되면 예외가 발생하여 런타임 오류를 일으킨다는 점에 유의하세요.