Node.js 애플리케이션 빌드

Node.js 버전 지정

빌드팩 프로젝트는 Node.js의 현재 출시 버전과 활성 LTS 출시 버전을 지원합니다. 이전 출시 버전의 Node.js를 사용할 수 있지만 프로젝트에서 적극적으로 유지보수되지 않을 수 있습니다.

package.json 사용

배포 중에 package.json의 engines.node 필드를 구성하여 애플리케이션의 Node.js 버전을 지정할 수 있습니다. 앱을 배포할 때 빌드팩에서 최신 버전의 Node.js v16을 사용하도록 구성하려면 package.json에서 다음 값을 사용하면 됩니다.

"engines": {
  "node": "16.x.x"
}

GOOGLE_NODEJS_VERSION 사용

GOOGLE_NODEJS_VERSION 환경 변수를 통해 Node.js 버전을 지정할 수도 있습니다. 두 구성이 모두 설정된 경우 GOOGLE_NODEJS_VERSION 값이 engines.node 속성보다 우선시됩니다. 값을 제공하지 않으면 최신 LTS 버전의 Node.js가 사용됩니다.

앱을 배포할 때 빌드팩에서 Node.js 16을 사용하도록 구성하려면 다음 명령어를 실행합니다.

pack build --builder=gcr.io/buildpacks/builder \
   sample-functions-framework-node \
   --env GOOGLE_NODEJS_VERSION=16.x.x

또한 project.toml 프로젝트 설명자를 사용하여 프로젝트 파일과 함께 환경 변수를 인코딩할 수 있습니다. 환경 변수로 애플리케이션 빌드에 대한 안내를 참조하세요.

팁

  • engines.node 필드에서 semver 제약조건을 사용할 수 있습니다. Node.js 빌드팩에 사용하는 특정 라이브러리는 Masterminds/semver입니다.
  • engines.node에서 초과 (>) 지정자를 사용하지 마세요.
  • 애플리케이션을 App Engine 표준 환경에 배포하는 경우 engines.node 속성이 app.yaml에 지정된 런타임과 호환되어야 합니다.
  • package.json의 engines.node 구성 옵션에 대한 추가 문서는 엔진 주제의 공식 NPM 문서에서 찾을 수 있습니다.
  • Cloud Functions에 함수를 배포할 때 engines.node 속성은 함수 배포에 사용되는 런타임과 호환되어야 합니다.

종속 항목 설치

NPM 사용

  • NPM이 기본 패키지 관리자입니다.
  • 가능하면 package-lock.json을 사용하여 캐시 성능을 향상시킵니다.
  • 기본적으로 프로덕션 종속 항목만 설치됩니다.
  • package.json 파일의 engines.npm 필드를 사용하여 npm 버전 섹션을 지정할 수 있습니다.

Yarn 사용

  • Yarn은 프로젝트에 yarn.lock 파일을 포함할 때 대신 사용됩니다.
  • package.json 파일의 engines.yarn 필드에 사용할 Yarn 버전을 지정할 수 있습니다.
  • 프로젝트에 .yarn/cache가 포함된 경우 Yarn2 PnP 모드를 지원합니다.

Pnpm 사용

  • Pnpm은 프로젝트에 pnpm-lock.yaml 파일을 포함할 때 대신 사용됩니다.
  • package.json 파일의 engines.pnpm 필드에 Pnpm 버전을 지정할 수 있습니다.
  • 작업 예시는 sample-node-pnpm 앱을 참조하세요.

비공개 모듈 사용

함수 디렉터리의 .npmrc 파일에서 레지스트리로 인증하기 위한 설정을 제공하여 비공개 npm 모듈을 사용할 수 있습니다. Yarn 버전 2 이상을 패키지 관리자로 사용하는 경우 파일의 이름은 .yarnrc.yml입니다.

Artifact Registry의 비공개 모듈

Artifact Registry Node.js 패키지 저장소에서 함수의 비공개 모듈을 호스팅할 수 있습니다. Buildpacks 함수를 배포하면 빌드 프로세스에서 Cloud Build 서비스 계정의 Artifact Registry 사용자 인증 정보가 자동으로 생성됩니다. NPM 또는 Yarn 버전 1을 사용할 때 .npmrc 파일에 Artifact Registry 저장소를 나열하기만 하면 됩니다. 예를 들어 NPM 또는 Yarn 버전 1을 사용하는 경우 다음과 같습니다.

@SCOPE:registry=https://REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME
//REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME:always-auth=true

Yarn 버전 2 이상을 사용하는 경우 추가 사용자 인증 정보 없이 .yarnrc.yml 파일에 Artifact Registry 저장소를 나열하기만 하면 됩니다. 예를 들면 다음과 같습니다.

npmScopes:
  SCOPE:
    npmRegistryServer: https://REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME
    npmAlwaysAuth: true

다른 저장소의 비공개 모듈

npm 문서에서는 커스텀 읽기 전용 액세스 토큰을 만드는 방법에 대해 설명합니다. 홈 디렉터리에서 생성된 .npmrc 파일에는 읽기/쓰기 토큰이 포함되어 있으므로 이 파일은 사용하지 않는 것이 좋습니다. 배포 중에는 쓰기 권한이 필요 없으며 보안 위험을 초래할 수 있습니다.

비공개 저장소를 사용하지 않는 경우 함수 배포 시간이 늘어날 수 있으므로 .npmrc 파일을 포함하지 마세요.

파일 형식

.npmrc 파일을 사용하여 커스텀 인증 토큰을 설정하는 경우 아래에 표시된 줄을 포함해야 합니다.

//REGISTRY_DOMAIN/:_authToken=AUTH_TOKEN

다음과 같이 바꿉니다.

  • REGISTRY_DOMAIN: 비공개 npm 레지스트리의 도메인 이름입니다. 예를 들어 저장소 호스트가 npmjs.org이면 이 필드를 registry.npmjs.org로 설정합니다.

  • AUTH_TOKEN: npm 레지스트리의 승인 토큰입니다. 토큰의 리터럴 텍스트 값 또는 npm 명령어가 환경의 실제 토큰 값으로 대체하는 텍스트 문자열 ${NPM_TOKEN}일 수 있습니다.

    gcloud functions deploy 명령어에 --set-build-env-vars 인수를 사용하여 $NPM_TOKEN 환경 변수를 설정할 수 있습니다. NPM 인증 토큰에 관한 자세한 내용은 비공개 모듈에 대한 NPM 튜토리얼을 참조하세요.

배포 중에 커스텀 빌드 단계 실행

package.json 파일에 스크립트가 지정되어 있으면 기본적으로 npm run build가 실행됩니다. 그러나 대신 커스텀 빌드 단계를 지정하여 기본 동작을 재정의하고 빌드 중에 원하는 스크립트만 실행할 수 있습니다. package.json 파일에서 GOOGLE_NODE_RUN_SCRIPTS 환경 변수 또는 gcp-build를 사용하여 빌드 단계를 제어할 수 있습니다.

한 가지 방법만 사용할 수 있습니다. GOOGLE_NODE_RUN_SCRIPTS 환경 변수가 우선 적용되며 package.json에서 gcp-build에 지정된 모든 항목을 재정의합니다.

기본적으로 커스텀 빌드 단계를 구성하면 스크립트 또는 명령어가 실행되기 전에 package.json 파일의 dependencies과 devDependencies이 먼저 설치됩니다. 기본 동작을 재정의하려면 NODE_ENV 환경 변수를 사용합니다.

GOOGLE_NODE_RUN_SCRIPTS 사용

빌드에 GOOGLE_NODE_RUN_SCRIPTS 환경 변수를 전달하여 실행할 스크립트를 제어할 수 있습니다. 스크립트를 한 개 이상 지정하거나 빈 환경 변수를 전달하여 GOOGLE_NODE_RUN_SCRIPTS= 등의 기본 동작이 실행되지 않도록 할 수 있습니다. 자세한 내용은 환경 변수를 참조하세요.

package.json 사용

package.json 파일에 gcp-build를 추가하면 npm run gcp-build만 실행됩니다. 즉, 기본 동작보다 우선 적용됩니다. 명령어를 한 개 이상 지정하거나 빈 문자열을 지정하여 "gcp-build":""와 같은 명령어가 실행되지 않도록 할 수 있습니다.

"scripts": {
  ...
  "gcp-build": "npm run lint && npm run build"
  ...
}

애플리케이션 진입점

Node.js 빌드팩은 package.json의 scripts.start 필드에 지정된 명령어를 실행합니다. scripts.start가 설정되지 않으면 빌드팩에서 npm start를 실행합니다.

경로에서 npm 또는 yarn을 사용하므로 Procfile을 사용하는 것이 좋습니다.

환경 변수

컨테이너 이미지의 빌드를 구성하는 환경 변수를 설정할 수 있습니다.

Node.js 빌드팩은 컨테이너를 맞춤설정하는 다음 환경 변수를 지원합니다.

NPM_CONFIG_<key>

문서 보기

예: NPM_CONFIG_FLAG=value는 -flag=value를 npm 명령어에 전달합니다.

NODE_ENV

빌드 중에 개발 환경 지정: npm install로 설정합니다.

예: NODE_ENV=development는 package.json에 지정된 dependencies 및 devDependencies를 모두 설치합니다.

GOOGLE_NODE_RUN_SCRIPTS

종속 항목을 설치한 후 실행할 package.json의 순서가 지정된 npm 스크립트 목록을 지정합니다. 목록은 쉼표로 구분되어야 하며 각 스크립트는 나열된 순서대로 실행됩니다.

GOOGLE_NODE_RUN_SCRIPTS를 지정하면 나열한 스크립트만 실행됩니다. 예를 들어 기본 npm run build가 실행되지 않도록 하려면 값 없이 환경 변수를 지정합니다.

예시:

  • GOOGLE_NODE_RUN_SCRIPTS=lint,build는 npm run lint를 실행한 다음 npm run build를 실행합니다.
  • GOOGLE_NODE_RUN_SCRIPTS=는 스크립트를 실행하지 않습니다.