Vercel에서 Node.js 20을 쓰고 있다면, 지금 점검하세요
Node.js 20은 2026년 4월 30일부로 공식 EOL(End of Life)에 들어갑니다. Vercel은 이에 맞춰 Builds와 Functions에서 Node.js 20을 2026년 10월 1일자로 deprecated 처리한다고 공지했어요.
여기서 중요한 포인트는 **"기존 배포는 멀쩡하고, 신규 배포만 막힌다"**는 점입니다. 이미 돌아가고 있는 서버리스 함수는 계속 정상 동작하지만, 10월 1일 이후 새로 배포를 시도하면 Project Settings에서 Node 20이 비활성화되어 에러를 뱉어냅니다.
실무에서 흔히 겪는 함정이 하나 있어요. "우리 프로젝트 Node 버전 뭐 쓰고 있더라?" 를 아무도 모른다는 겁니다. Vercel 프로젝트는 여러 개인데, 각각 언제 세팅했는지 기억도 안 나죠. 그래서 먼저 영향받는 프로젝트 목록을 뽑아내는 것부터 시작해야 합니다.
이 글의 근거자료는 Vercel 공식 Changelog이며, 국내에서 Vercel을 쓰는 사이드 프로젝트·스타트업·SI 환경 모두에 해당되는 내용이니 끝까지 읽어보시길 권합니다.
영향받는 프로젝트 찾기 & 업그레이드 방법
1단계: 어떤 프로젝트가 걸려있는지 확인
Vercel CLI 최신 버전으로 업데이트한 뒤, 아래 명령어를 실행하면 deprecated된 Node 버전을 쓰는 프로젝트만 필터링해서 보여줍니다.
# Vercel CLI 최신 버전으로 업데이트
npm i -g vercel@latest
# deprecated Node.js 버전을 사용하는 프로젝트만 조회
vercel project ls --update-required
이 명령어 하나면 "어디부터 손대야 하는지" 리스트가 바로 나옵니다. 팀 단위로 관리하는 계정이라면 꼭 한 번 돌려보세요.
2단계: Node 버전 업그레이드 (수동)
가장 확실한 방법은 package.json의 engines 필드를 수정하는 것입니다. Project Settings의 버전보다 engines 필드가 우선순위를 가집니다.
{
"engines": {
"node": "24.x"
}
}
추가로 아래 파일들에 Node 20이 박혀있는지도 확인해서 정리해주세요.
.nvmrc.node-version- CI 설정 파일 (GitHub Actions, CircleCI 등)
로컬 런타임도 Node 24로 바꾸고, node_modules를 재설치한 뒤 빌드/테스트를 돌려서 breaking change를 잡아내야 합니다.
3단계: 코딩 에이전트에게 위임하기
요즘은 이 작업 자체를 AI 코딩 에이전트에게 던질 수 있습니다. 아래 프롬프트를 그대로 복붙하면 됩니다.
Upgrade this Vercel project from Node.js 20 to 24.
Set the engines field in package.json to { "node": "24.x" },
which overrides the Project Settings version on the next deployment.
Update any Node 20 pins in .nvmrc, .node-version, or CI configs.
Switch the local runtime to Node 24, reinstall dependencies,
run the build and tests, and fix any breaking changes.
After deploying, confirm the version by logging process.version.
배포 후에는 console.log(process.version)을 찍어서 실제로 Node 24로 뜨는지 반드시 검증하세요. Project Settings만 바꾸고 배포했다고 착각하는 케이스가 은근히 많습니다.
10월 1일까지 못 끝내겠다면? 컨테이너 배포로 우회
현실적으로 레거시 프로젝트를 한 달 만에 Node 24로 올리는 건 쉽지 않습니다. 특히 의존성 지옥에 빠진 프로젝트라면 더더욱요. 이럴 때 Vercel이 제시하는 우회책은 컨테이너 이미지로 배포하는 것입니다.
프로젝트 루트에 Dockerfile.vercel을 추가하면, 매 커밋마다 이미지를 빌드해서 배포합니다.
FROM node:20-alpine
WORKDIR /app
COPY . .
RUN npm ci
# 서버는 반드시 $PORT를 리스닝해야 함
CMD ["node", "server.js"]
여기서 핵심은 컨테이너 배포에는 Project Settings의 Node 버전이 적용되지 않는다는 점입니다. 그래서 Node 20 deprecation 정책에 걸리지 않습니다.
비교: 어떤 방식이 나에게 맞을까?
| 항목 | engines 필드 업그레이드 | Dockerfile.vercel 컨테이너 배포 |
|---|---|---|
| 난이도 | 낮음 (설정 변경) | 중간 (Dockerfile 관리) |
| Node 20 유지 가능 | ❌ (강제 업그레이드) | ✅ (base image로 고정) |
| 보안 패치 | Vercel이 관리 | 직접 관리 필요 |
| 빌드 시간 | 빠름 | 이미지 빌드로 다소 느림 |
| 권장 상황 | 신규 프로젝트, 의존성 정리 가능 | 레거시, 마이그레이션 리스크 큼 |
⚠️ 이 기술의 한계와 주의사항
- 컨테이너는 "회피"일 뿐 "해결"이 아닙니다. Node 20 자체가 EOL이기 때문에, 보안 취약점 패치는 직접 챙겨야 합니다.
- 이미지 크기 관리를 소홀히 하면 콜드 스타트가 느려집니다.
alpine기반이라도 불필요한 devDependencies가 들어가지 않도록npm ci --omit=dev를 고려하세요. $PORT리스닝 누락은 가장 흔한 실수입니다. Vercel 컨테이너는 동적으로 포트를 주입하기 때문에 하드코딩하면 안 됩니다.- 국내 SI 환경에서는 고객사가 Node 20 고정을 요구하는 경우가 있습니다. 이 경우 컨테이너 배포가 유일한 현실적 선택지가 될 수 있습니다.
결론: 10월 1일은 마감일이 아니라 "체크포인트"입니다
정리하면 이렇습니다.
- 2026년 10월 1일부터 Vercel에서 Node.js 20 신규 배포가 차단됩니다.
- 기존 배포는 계속 돌아가지만, 언젠가는 반드시 업그레이드해야 합니다.
vercel project ls --update-required로 영향 범위를 먼저 파악하세요.engines필드 수정이 가장 깔끔하고, 여의치 않으면Dockerfile.vercel로 시간을 벌 수 있습니다.- 배포 후
process.version로그로 반드시 검증하세요.
다음 단계 학습 방향
- Node 24의 신규 기능을 미리 훑어보세요.
require(esm)지원,AsyncLocalStorage개선 등 마이그레이션하면서 활용할 수 있는 것들이 많습니다. - Vercel 컨테이너 배포에 익숙해지면, 다른 런타임(Python, Go 등)도 유연하게 다룰 수 있습니다.
- 팀 단위로 관리한다면 Node 버전 정책을 문서화하고, CI에서
engines필드를 검증하는 스크립트를 넣어두는 걸 추천합니다.
함께 보면 좋은 글
이번 deprecation은 "언젠가 하자"라고 미뤄둔 기술 부채를 청산하라는 신호입니다. 지금 프로젝트 리스트를 뽑아보는 것만으로도 절반은 끝난 셈이에요 😅