Firexport 로고

Firexport블로그

Cloud Functions for Firebase Node.js 20 종료: Node.js 24·22로 올리는 법

2026년 10월 30일에 Cloud Functions의 Node.js 20 런타임이 종료(decommission)됐습니다. 이제 Node.js 20으로는 함수를 새로 배포하거나 업데이트할 수 없어서 firebase deploy가 아래 에러로 멈춥니다. 고칠 곳은 functions/package.json의 한 줄입니다. 2세대 함수만 있다면 Node.js 24로, 1세대 함수가 있다면 Node.js 22로 올리세요.

Error: Runtime Node.js 20 was decommissioned on 2026-10-30. To deploy you must
first upgrade your runtime version.

요약

  • 배포만 막힌 게 아닙니다. 이미 배포한 함수는 아직 돌지만 보안 패치가 끊겼고, 정해진 날짜 없이 비활성화될 수 있습니다. 날짜와 뜻
  • 한 줄을 바꾸고 다시 배포합니다. engines.node를 "24"나 "22"로 바꿉니다. firebase.json에 runtime이 있으면 그쪽이 우선합니다. 바꾸는 법
  • 2세대는 24, 1세대는 22. 1세대 함수는 Node.js 22가 마지막이라, 22가 끝나는 2027년 10월 31일 전에 2세대로 옮겨야 합니다. 1세대 함수
  • SDK를 올린다면 두 가지를 봅니다. firebase-functions 7은 functions.config()를 없앴고, firebase-admin 14는 Node.js 22 이상에서만 동작합니다. SDK 버전

날짜와 뜻

Google Cloud의 런타임 지원 일정입니다. 지원 중단(deprecation) 기간에는 아직 배포할 수 있고, 종료(decommission) 뒤에는 새로 만들 수도 업데이트할 수도 없습니다.

런타임쓸 수 있는 함수지원 중단종료
Node.js 181세대, 2세대2025-04-302025-10-30
Node.js 201세대, 2세대2026-04-302026-10-30
Node.js 221세대, 2세대2027-04-302027-10-31
Node.js 242세대만2028-04-302028-10-31

종료되면 달라지는 것입니다.

지원 중단 기간종료 후
새로 배포하거나 업데이트됨안 됨
이미 배포된 함수실행됨실행되지만, 비활성화될 수 있음
Node.js·OS 보안 패치받음없음

비활성화 날짜는 정책에 없습니다. 지금 멀쩡히 도는 함수도 버그를 고치려는 순간 배포가 막히고, 언제 멈출지 알 수 없습니다. 우회로도 없습니다. CLI의 런타임 검사를 꺼도 서버가 따로 막습니다(CLI 소스).

Node.js 24나 22로 올리기

  1. 함수마다 세대와 런타임을 확인합니다. firebase functions:list를 실행하면 Version 열이 v1이면 1세대, v2면 2세대이고, Runtime 열이 지금 런타임입니다.
  2. 버전을 고릅니다. 런타임은 함수마다가 아니라 코드베이스(보통 functions 폴더)마다 하나입니다. 1세대 함수가 하나라도 있으면 22, 모두 2세대면 24를 고르세요. 24는 2028년 10월 31일까지 쓸 수 있지만 1세대는 지원하지 않습니다. Firebase 문서의 버전 목록에는 아직 24가 없지만, Cloud의 일정표에 2세대용으로 올라 있고 Firebase CLI는 14.26.0부터 지원합니다.
  3. package.json의 한 줄을 바꿉니다. 값은 주 버전 숫자 하나입니다. >=22나 22.x 같은 범위를 쓰면 CLI가 Detected node engine ... which is not a supported version 에러를 냅니다.
    {
  "engines": {
    "node": "24"
  }
}

    firebase.json에 runtime이 있으면 CLI는 그 값을 먼저 씁니다. 그때는 그쪽을 바꾸세요.

    {
  "functions": {
    "source": "functions",
    "runtime": "nodejs24"
  }
}
  4. 로컬과 CI의 Node.js도 같은 버전으로 맞춥니다. 에뮬레이터는 설치된 Node.js로 함수를 돌립니다. 버전이 다르면 Your requested "node" version "24" doesn't match your global version "20" 경고만 내고 20으로 그대로 돌리므로, 테스트가 프로덕션과 다른 버전에서 돌게 됩니다.
  5. 배포합니다. firebase deploy --only functions를 실행한 뒤 firebase functions:list의 Runtime 열이 nodejs24(또는 nodejs22)로 바뀌었는지 확인합니다.

SDK 버전

Node.js를 올리면서 SDK도 올린다면 아래를 확인하세요.

패키지확인할 것
firebase-tools (CLI)nodejs22는 13.11.0부터, nodejs24는 14.26.0부터 배포할 수 있습니다.
firebase-functions6.2.0 미만에서는 최상위 await가 있는 ESM 코드가 Node.js 22.12 이상에서 깨집니다. 7.0.0에서 functions.config()가 없어져, 호출하면 런타임 에러가 납니다.
firebase-admin14는 Node.js 22 이상에서만 돌고, firebase-functions 7.3.0 이상과 함께 써야 합니다(peer 의존성). 13은 Node.js 18 이상에서 동작합니다.

functions.config()를 아직 쓴다면 firebase-functions는 6.x에 두고 Node.js만 올리세요. functions.config()로 배포하는 것도 2027년 3월 이후에는 실패하니, 그 전에 환경 변수나 Secret Manager로 옮겨야 합니다.

1세대 함수

1세대 함수가 쓸 수 있는 마지막 런타임은 Node.js 22이고, 22는 2027년 10월 31일에 종료됩니다. 그 전에 2세대로 옮겨야 합니다. Firebase CLI 15.35.0은 경고에서 22의 종료일을 2028-10-31로 보여 주지만, 기준은 Google Cloud 일정표의 2027-10-31입니다(CLI 소스). 같은 이름으로는 바로 바꿀 수 없어서, Firebase는 2세대 함수를 새 이름으로 배포하고 트래픽을 옮긴 뒤 1세대 함수를 지우라고 안내합니다(업그레이드 가이드). 옮길 때 걸리는 것들입니다.

  • URL이 바뀝니다. HTTP·callable·태스크 큐 함수는 새 이름이 곧 새 URL입니다. 앱과 웹훅을 새 URL로 옮긴 뒤 firebase functions:delete로 옛 함수를 지웁니다.
  • 이벤트를 두 번 처리합니다. Firestore·Storage 같은 이벤트 트리거는 두 함수가 함께 있는 동안 같은 이벤트에 둘 다 실행됩니다. 두 번 실행돼도 결과가 같게 만드세요.
  • 없는 것이 있습니다. 2세대에는 functions.config()와 Analytics 이벤트 트리거가 없고, Authentication의 사용자 생성·삭제 트리거(onUserCreated, onUserDeleted)는 아직 Preview입니다.
  • 기본값이 다릅니다. 인스턴스 하나가 요청을 기본 80개까지 동시에 처리하고, 기본 서비스 계정이 Compute Engine 기본 서비스 계정으로 바뀝니다. 전역 변수에 요청마다 다른 값을 담거나 IAM 권한을 App Engine 기본 서비스 계정에 줬다면 고쳐야 합니다.

확장 프로그램(Extensions)

설치한 확장 프로그램도 Cloud Functions로 돌고, 런타임은 확장 프로그램 버전이 정합니다. Firebase는 확장 프로그램을 최신 버전으로 업데이트하라고 안내합니다.

firebase ext:update <instance-id>
firebase deploy --only extensions

확장 프로그램 서비스는 2027년 3월 31일에 종료됩니다. 설치된 확장 프로그램은 그 뒤에도 실행되지만 업데이트 같은 관리 기능은 쓸 수 없습니다. 대부분 1세대 함수로 만들어져 있어 런타임이 종료되면 멈추거나 비활성화될 수 있으니, 계속 쓸 기능이라면 직접 만든 함수로 옮길 계획도 세우세요.

출처

전체 글 →