2025.3.31 월요일의 공부기록
이 글에서는 Next.js에서 제공하는 두 가지 런타임(Runtime)인 Node.js 런타임과 Edge 런타임의 차이점과 특성, 각 런타임이 적합한 상황, 그리고 미들웨어에서 사용하는 Edge 런타임의 제한 사항을 설명한다.
Next.js 런타임(Runtime)이란?
Next.js 애플리케이션은 서버 측에서 코드를 실행할 때, 두 가지의 런타임 환경 중 하나를 사용한다:
- Node.js 런타임 (기본값)
- Edge 런타임
이 두 가지 런타임은 사용할 수 있는 API와 특성이 다르며, 따라서 사용 목적과 환경에 맞게 선택해야 한다.
1. Node.js 런타임 (기본값)
Node.js 런타임은 Next.js의 기본 런타임이며, 가장 많이 사용된다. Node.js 런타임은 다음과 같은 장점을 가지고 있다:
- 모든 Node.js API 사용 가능 (파일 시스템 접근, 환경 변수, 스트림, 네트워크 등)
- 수많은 npm 패키지와의 높은 호환성 제공
- Express, Prisma와 같은 서버 전용 라이브러리 지원
사용 사례
- 데이터베이스 접근 및 파일 시스템 작업이 많은 애플리케이션
- 기존의 Node.js 생태계에 익숙한 개발자 및 프로젝트
- 복잡한 서버 측 연산이 필요한 경우
2. Edge 런타임
Next.js의 Edge 런타임은 주로 미들웨어에서 사용된다. Edge 런타임은 Vercel의 Edge Functions 기반으로 작동하며, 전 세계 CDN을 활용하여 지리적으로 사용자와 가까운 위치에서 매우 빠르게 실행된다.
하지만 Edge 런타임은 보안 및 성능 최적화를 위해 제한된 API만 지원하므로 주의가 필요하다.
Edge 런타임이 지원하는 API 목록
Edge 런타임의 제한 사항
- Node.js 전용 API (파일 시스템 접근 등)는 사용할 수 없다.
- 모든 npm 패키지를 사용할 수 없으며, Edge 호환 패키지만 사용 가능하다.
Edge 런타임과 Middleware
Next.js의 미들웨어는 기본적으로 Edge 런타임에서 실행된다. 따라서 미들웨어에서는 Node.js 전용 API나 일부 npm 패키지를 사용할 수 없다.
- 미들웨어는 매우 빠르게 응답해야 하므로, Edge 런타임에서 가볍고 빠르게 실행된다.
- 주로 인증 처리, 서버 사이드 리다이렉션, 라우트 재작성(Rewriting) 등 빠르게 처리해야 하는 작업에 적합하다.
Edge 런타임 설정 방법 (Middleware)
Next.js의 미들웨어는 기본적으로 Edge 런타임으로 설정되어 있으므로 별도의 설정 없이 사용할 수 있다. 명시적으로 설정할 수도 있다.
// middleware.ts (기본적으로 Edge 런타임으로 실행됨)
export const config = {
runtime: 'edge', // 명시적으로 지정 (기본값이므로 생략 가능)
};만약 Node.js 전용 API를 사용해야 하는 경우 미들웨어 대신 다른 방식을 고려하거나 API Routes를 활용해야 한다.
Runtime 사용 비교
| Runtime | Node.js Runtime | Edge Runtime |
|---|---|---|
| 지원 API | 모든 Node.js API 사용 가능 | 제한된 Web API 사용 가능 |
| 실행 환경 | 서버 환경(Node.js 서버) | Edge 네트워크(CDN)에서 실행 |
| 장점 | 강력한 기능과 넓은 호환성 | 빠른 응답 속도, 전 세계 사용자에게 낮은 지연시간 제공 |
| 단점 | Edge보다 느린 초기 응답 속도 | 제한된 API 및 패키지 호환성 |
| 적합한 상황 | 복잡한 로직, 데이터베이스 연동, 서버 측 연산 필요 | 빠른 응답, 간단한 인증, 리다이렉션, A/B 테스트 |
