이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Node.js 런타임 환경

Node.js 런타임은 웹 서비스의 코드 및 종속 항목을 설치하고 서비스를 실행하는 소프트웨어 스택입니다.

표준 환경에서 App Engine용 Node.js 런타임은 app.yaml 파일에서 선언됩니다.

runtime: nodejsVERSION

여기서 VERSION는 Node.js MAJOR 버전 번호입니다. 예를 들어 최신 Node.js 버전인 Node.js 22를 사용하려면 22을 지정합니다.

지원되는 다른 Node.js 버전과 Node.js 버전의 해당 Ubuntu 버전은 런타임 지원 일정을 참조하세요.

Node.js 버전

Node.js 런타임은 app.yaml 파일에 지정된 최신 안정화 버전을 사용합니다. App Engine은 새로운 패치와 부 출시 버전으로 자동 업데이트되지만 주 버전으로는 자동 업데이트되지 않습니다.

예를 들어 애플리케이션은 Node.js 10.9.4에 배포된 후 자동으로 버전 10.10.0으로 업데이트될 수 있으나 Node.js 12.x.x로는 자동으로 업데이트되지 않습니다.

부 버전과 패치 버전이 자동으로 업데이트되므로, package.json 파일의 engines.node 속성은 주 버전만 지정할 수 있으며 app.yaml 파일에 지정된 Node.js 버전과 호환될 수 있습니다.

예를 들어 22의 경우 다음과 같습니다.

22.x.x
^22.0.0
~22
>=6

package.json 파일에 호환되지 않는 Node.js 버전을 지정하면 배포가 실패하고 오류 메시지가 표시됩니다.

종속 항목

배포하는 동안 런타임은 npm install 명령어를 사용하여 종속 항목을 설치합니다. 또한 런타임에서 Yarn(yarn.lock) 및 Pnpm(pnpm-lock.yaml) 패키지 관리자를 지원합니다. 자세한 내용은 종속 항목 지정을 참조하세요. 런타임은 새로 설치를 수행하므로 node_modules 폴더를 업로드할 필요가 없습니다.

네이티브 확장 프로그램이 필요한 Node.js 패키지를 지원하도록 ImageMagick, FFmpeg, Chrome headless와 같은 도구를 사용할 수 있는 시스템 패키지가 런타임에 포함되어 있습니다. 포함된 시스템 패키지에서 패키지의 전체 목록을 참조하세요. 패키지를 요청하려면 Issue Tracker에서 문제를 제출하세요.

NPM 빌드 스크립트

기본적으로 build 스크립트가 package.json에서 감지되면 Node.js 런타임이 npm run build를 실행합니다. 애플리케이션을 시작하기 전에 빌드 단계를 추가로 제어해야 하면 gcp-build 스크립트를 package.json 파일에 추가하여 커스텀 빌드 단계를 제공하면 됩니다.

빌드가 npm run build 스크립트를 실행하지 않도록 하려면 다음 중 하나를 수행해야 합니다.

값이 비어 있는 gcp-build 스크립트를 package.json 파일에 추가합니다. "gcp-build":"" package.json 구성에 대한 자세한 내용은 Node.js 빌드팩 구성을 참조하세요.
값이 비어 있는 GOOGLE_NODE_RUN_SCRIPTS 빌드 환경 변수를 app.yaml 파일에 추가합니다.
```
build_env_variables:
  GOOGLE_NODE_RUN_SCRIPTS: ''
```

빌드 환경 변수 지정에 대한 자세한 내용은 app.yaml 파일의 build_env_variables 섹션을 참조하세요.

애플리케이션 시작

기본적으로 런타임은 node server.js를 실행하여 애플리케이션을 시작합니다. start 스크립트를 package.json 파일에 지정하면 대신 런타임에 지정된 시작 스크립트가 실행됩니다. 예를 들면 다음과 같습니다.

"scripts": {
  "start": "node app.js"
}

앱에서 HTTP 요청을 수신하려면 start 스크립트가 호스트 0.0.0.0와 Node.js에서 process.env.PORT로 액세스할 수 있는 PORT 환경 변수로 지정된 포트에서 리슨하는 웹 서버를 시작해야 합니다.

최상의 성능을 얻으려면 start 스크립트가 가벼워야 하고 빌드 단계를 배제해야 합니다. 애플리케이션의 새 인스턴스가 생성될 때마다 실행되기 때문입니다.

app.yaml의 entrypoint 필드 스크립트를 지정하여 이 동작을 재정의할 수 있습니다. node server.js 또는 시작 스크립트를 실행하는 대신 런타임은 entrypoint에 지정한 명령어로 애플리케이션을 시작합니다.

환경 변수

다음 환경 변수는 런타임에서 설정됩니다.

환경 변수	설명
`GAE_APPLICATION`	App Engine 애플리케이션 ID입니다. 이 ID는 유럽에 배포된 애플리케이션의 'e~'와 같이 '`region code`~'로 시작됩니다.
`GAE_DEPLOYMENT_ID`	현재 배포 ID입니다.
`GAE_ENV`	App Engine 환경입니다. `standard`로 설정합니다.
`GAE_INSTANCE`	서비스가 현재 실행되고 있는 인스턴스 ID입니다.
`GAE_MEMORY_MB`	애플리케이션 프로세스에 제공되는 메모리 양(MB)입니다.
`GAE_RUNTIME`	`app.yaml` 파일에 지정된 런타임입니다.
`GAE_SERVICE`	`app.yaml` 파일에 지정된 서비스 이름입니다. 서비스 이름을 지정하지 않으면 `default`로 설정됩니다.
`GAE_VERSION`	서비스의 현재 버전 라벨입니다.
`GOOGLE_CLOUD_PROJECT`	애플리케이션과 연결된 Google Cloud 프로젝트 ID입니다.
`PORT`	HTTP 요청을 수신하는 포트입니다.
`NODE_ENV`(Node.js 런타임에서만 사용 가능)	서비스가 배포되면 `production`으로 설정하세요.

app.yaml 파일에 추가 환경 변수를 정의할 수 있지만 NODE_ENV 외에는 위 값을 재정의할 수 없습니다.

HTTPS 및 전달 프록시

App Engine은 부하 분산기에서 HTTPS 연결을 종료하고 애플리케이션에 요청을 전달합니다. 일부 애플리케이션에서는 원본 요청 IP와 프로토콜을 확인해야 합니다. 사용자의 IP 주소는 표준 X-Forwarded-For 헤더에서 제공됩니다. 이 정보가 필요한 애플리케이션은 프록시를 신뢰하도록 웹 프레임워크를 구성해야 합니다.

Express.js의 경우 다음과 같은 trust proxy 설정을 사용합니다.

app.set('trust proxy', true);

trust proxy를 true로 설정하면 req.ip 속성이 IP 스푸핑 취약점에 노출될 수 있습니다.

파일 시스템

런타임은 전체 파일 시스템을 포함합니다. 파일 시스템은 App Engine 인스턴스의 RAM에 데이터를 저장하는 가상 디스크인 /tmp 위치를 제외하고 읽기 전용입니다.

메타데이터 서버

애플리케이션의 각 인스턴스는 App Engine 메타데이터 서버를 사용하여 인스턴스와 프로젝트에 대한 정보를 쿼리할 수 있습니다.

다음 엔드포인트를 통해 메타데이터 서버에 액세스할 수 있습니다.

http://metadata
http://metadata.google.internal

메타데이터 서버로 전송되는 요청에는 요청 헤더 Metadata-Flavor: Google이 포함되어야 합니다. 이 헤더는 요청이 메타데이터 값을 검색하기 위해 전송되었음을 나타냅니다.

다음 표에는 특정 메타데이터에 대해 HTTP 요청을 수행할 수 있는 엔드포인트가 나열되어 있습니다.

메타데이터 엔드포인트	설명
`/computeMetadata/v1/project/numeric-project-id`	프로젝트에 할당된 프로젝트 번호입니다.
`/computeMetadata/v1/project/project-id`	프로젝트에 할당된 프로젝트 ID입니다.
`/computeMetadata/v1/instance/region`	인스턴스가 실행 중인 리전입니다.
`/computeMetadata/v1/instance/service-accounts/default/aliases`
`/computeMetadata/v1/instance/service-accounts/default/email`	프로젝트에 할당된 기본 서비스 계정 이메일입니다.
`/computeMetadata/v1/instance/service-accounts/default/`	프로젝트의 모든 기본 서비스 계정이 나열됩니다.
`/computeMetadata/v1/instance/service-accounts/default/scopes`	기본 서비스 계정에 지원되는 모든 범위가 나열됩니다.
`/computeMetadata/v1/instance/service-accounts/default/token`	다른 Google Cloud API에 애플리케이션을 인증하기 위해 사용할 수 있는 인증 토큰을 반환합니다.

예를 들어 프로젝트 ID를 검색하려면 http://metadata.google.internal/computeMetadata/v1/project/project-id에 요청을 보냅니다.