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

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

App Router API ReferenceEdge Runtime

Edge Runtime

최종 업데이트 2026년 2월 20일

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

모든 Node.js API에 접근할 수 있고 애플리케이션 렌더링에 사용되는 Node.js 런타임(기본값)
더 제한적인 API 집합을 포함하며 Proxy에서 사용되는 Edge Runtime

주의 사항

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 형식으로 변환하거나 JSON을 JavaScript 값으로 변환하는 기능을 제공합니다
`Map`	각 값이 한 번만 나타날 수 있는 값 모음을 나타냅니다
`Math`	수학 함수와 상수에 접근합니다
`Number`	숫자 값을 나타냅니다
`Object`	모든 JavaScript 객체의 기반이 되는 객체를 나타냅니다
`parseFloat`	문자열 인수를 파싱해 부동소수점 숫자를 반환합니다
`parseInt`	문자열 인수를 파싱해 지정된 기수의 정수를 반환합니다
`Promise`	비동기 작업의 최종 완료(또는 실패)와 그 결과 값을 나타냅니다
`Proxy`	속성 조회, 할당, 열거, 함수 호출 등 기본 연산에 대한 커스텀 동작을 정의하는 객체를 나타냅니다
`queueMicrotask`	실행할 마이크로태스크를 큐에 추가합니다
`RangeError`	값이 허용 범위에 없을 때 발생하는 오류를 나타냅니다
`ReferenceError`	존재하지 않는 변수를 참조할 때 발생하는 오류를 나타냅니다
`Reflect`	가로챌 수 있는 JavaScript 연산을 위한 메서드를 제공합니다
`RegExp`	문자 조합을 매칭할 수 있도록 정규식을 나타냅니다

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	Description
`eval`	문자열로 표현된 JavaScript 코드를 평가합니다
`new Function(evalString)`	인수로 제공된 코드로 새 함수를 생성합니다
`WebAssembly.compile`	버퍼 소스에서 WebAssembly 모듈을 컴파일합니다
`WebAssembly.instantiate`	버퍼 소스에서 WebAssembly 모듈을 컴파일하고 인스턴스화합니다

드물게, 코드가 런타임에 도달할 수 없고 트리 셰이킹으로 제거할 수 없는 동적 코드 평가 문을 포함(또는 가져오기)할 수 있습니다. 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에서 실행되면 런타임 오류를 발생 시키고 중단된다는 점에 유의하세요.

보내기