Node.js의 종속 항목 지정

함수에서 외부 Node.js 모듈 및 로컬 데이터를 사용할 수 있습니다. Node.js의 종속 항목은 npm으로 관리되며 package.json이라는 메타데이터 파일로 표현됩니다. Cloud Run 함수 Node.js 런타임은 npm, yarn, pnpm을 사용한 설치를 지원합니다.

함수의 종속 항목을 지정하려면 이를 package.json 파일에 추가합니다.

참고: 프로젝트에 package-lock.json, yarn.lock, pnpm-lock.yaml 파일이 있는 경우 npm ci, yarn install, pnpm install을 사용하여 종속 항목을 설치할 때 해당 잠금 파일이 유지됩니다.

이 예시에서 종속 항목은 package.json 파일에 나열됩니다.

{
  "dependencies": {
    "escape-html": "^1.0.3"
  }
}

그런 다음 함수에서 종속 항목을 가져옵니다.

const functions = require('@google-cloud/functions-framework');
const escapeHtml = require('escape-html');

/**
 * Responds to an HTTP request using data from the request body parsed according
 * to the "content-type" header.
 *
 * @param {Object} req Cloud Function request context.
 * @param {Object} res Cloud Function response context.
 */
functions.http('helloHttp', (req, res) => {
  res.send(`Hello ${escapeHtml(req.query.name || req.body.name || 'World')}!`);
});

함수 프레임워크는 모든 함수에 필요한 종속 항목입니다. Cloud Run Functions는 함수 생성 시 이를 자동으로 설치하지만 명시적 종속 항목으로 명확하게 포함하는 것이 좋습니다.

함수에서 비공개 종속 항목을 사용하는 경우 functions-framework를 비공개 레지스트리에 미러링하는 것이 좋습니다. 공개 인터넷에서 패키지를 설치하지 않으려면 미러링된 functions-framework를 함수에 대한 종속 항목으로 포함합니다.

npm을 사용하여 로컬에 Node.js 모듈 설치

로컬에 Node.js 모듈을 설치하는 가장 쉬운 방법은 함수가 포함된 폴더에서 npm install 명령어를 사용하는 것입니다. 예를 들어 uuid 모듈을 추가하려면 다음 명령어를 실행합니다.

npm install uuid

이렇게 하면 두 단계가 실행됩니다.

1. 모듈의 최신 버전을 package.json 파일의 종속 항목으로 표시합니다. 이 단계는 매우 중요합니다. Cloud Run 함수는 package.json 파일에 선언된 모듈만 설치합니다.
2. 모듈을 node_modules 디렉터리로 다운로드합니다. 이렇게 하면 로컬에서 개발 시 모듈을 사용할 수 있습니다.

npm이 설치되어 있지 않으면 npm을 다운로드합니다.

참고: npm 패키지는 다양한 Google Cloud 제품에서 사용할 수 있습니다. 여기에서 목록을 확인하세요.

배포 종속 항목 구성

NPM, Yarn 또는 Pnpm의 프로덕션 종속 항목을 설치할 수 있습니다.

NPM

함수를 배포하면 Cloud Run 함수가 npm install 명령어를 사용하여 package.json 파일에 선언된 종속 항목을 설치합니다.

npm install --production

Yarn

Node.js 8 런타임 이상에 yarn.lock 파일이 있으면 Cloud Run 함수는 yarn install 명령어를 대신 사용합니다.

yarn install --production

Pnpm

Node.js 8 런타임 이상에 pnpm-lock.yaml 파일이 있으면 Cloud Run 함수는 pnpm install 명령어를 대신 사용합니다.

pnpm install

참고: 하위 디렉터리에 선언된 종속 항목은 설치되지 않습니다. monorepo를 사용하는 경우 배포 중에 커스텀 빌드 스크립트를 실행하여 이러한 종속 항목을 설치할 수 있습니다.

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

배포 후 package.json 파일에 gcp-build 스크립트를 추가하여 기능 빌드 프로세스 중 커스텀 빌드 단계를 수행할 수 있습니다.

이 스크립트가 실행되면 package.json 파일의 dependencies 필드와 devDependencies 필드에서 종속 항목을 사용할 수 있습니다. 커스텀 빌드 단계를 실행하면 Cloud Run 함수는 선언된 프로덕션 종속 항목만 package.json 파일의 dependencies 필드에 설치하여 node_modules 폴더를 삭제한 후 다시 생성합니다.

package.json에 gcp-build 스크립트가 없으면 Cloud Run 함수는 프로덕션 종속 항목을 설치하기만 합니다.

시스템 패키지 사용

또한 Node.js 런타임 실행 환경에는 여러 시스템 패키지가 포함되어 있습니다. 나열되지 않은 패키지가 필요한 종속 항목이 함수에 사용되는 경우 패키지를 요청할 수 있습니다.

참고: Functions Framework를 사용하여 Cloud Run으로 Node.js Cloud Run Functions의 컨테이너화된 버전을 배포할 수도 있습니다.

로컬 Node.js 모듈 포함

로컬 Node.js 모듈을 함수의 일부분으로 포함할 수도 있습니다. file: 프리픽스를 사용하여 package.json에서 모듈을 선언하면 됩니다. 다음 예시에서 mymodule은 모듈 이름을 나타내고 mymoduledir은 모듈이 포함된 디렉터리입니다.

{
  "dependencies": {
    "mymodule": "file:mymoduledir"
  }
}

이 로컬 모듈의 코드는 함수의 루트 디렉터리에 있는 node_modules 폴더가 아닌 다른 위치에 저장해야 합니다.

참고: gcloud 명령줄 도구를 사용하여 배포할 경우 gcloud는 함수의 디렉터리에서 .gcloudignore 파일을 자동으로 만듭니다. 기본적으로 node_modules 폴더는 .gcloudignore에 추가되며 배포 중에 업로드되지 않습니다. 코드를 .zip 파일로 직접 업로드하는 경우 node_modules 폴더를 포함할 필요가 없습니다. node_modules 폴더 없이 함수를 배포할 수 있습니다.

Node.js 모듈 로드

Node.js require() 함수를 사용하여 이전에 설치한 Node.js 모듈을 로드합니다. 또한 require() 함수를 사용하면 함수와 함께 배포하는 로컬 파일을 가져올 수 있습니다.

비공개 모듈 사용

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

Artifact Registry의 비공개 모듈

Artifact Registry Node.js 패키지 저장소에서 함수의 비공개 모듈을 호스팅할 수 있습니다. Cloud Run Functions를 배포하면 빌드 프로세스에서 Cloud Build 서비스 계정의 Artifact Registry 사용자 인증 정보가 자동으로 생성됩니다. 추가 사용자 인증 정보를 생성하지 않고 .npmrc에 Artifact Registry 저장소를 나열하기만 하면 됩니다. 예를 들면 다음과 같습니다.

@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 v1 패키지 관리자에도 적용됩니다. Yarn v2 이상을 사용하는 경우 추가 사용자 인증 정보 없이 .yarnrc.yml에 Artifact Registry 저장소를 나열하기만 하면 됩니다. 예를 들면 다음과 같습니다.

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

다른 저장소의 비공개 모듈

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

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

참고: 커스텀 권한(예: VPC에 필요한 권한)을 사용하는 경우 함수가 대상 비공개 저장소에 액세스하도록 명시적으로 허용합니다.

파일 형식

.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 튜토리얼을 참조하세요.

벤더링된 종속 항목으로 함수 빌드

벤더링된 종속 항목은 소스가 소스 코드 패키지에 직접 포함되어 있고 자체 코드와 함께 다시 빌드되는 종속 항목입니다. 벤더링된 Node.js 종속 항목을 만들고 GOOGLE_VENDOR_NPM_DEPENDENCIES 빌드 환경 변수를 사용하여 배포 중에 이 설치를 건너뜁니다.

벤더링된 종속 항목의 기본 요건

1. 공급업체가 package.json 파일에 정의한 모든 종속 항목이 포함된 작동 함수가 있는지 확인합니다.

2. 다음을 실행하여 이러한 종속 항목을 로컬에 설치합니다.

       npm install
   

3. 작업 디렉터리의 .gcloudignore 파일에서 node_modules를 삭제합니다.

4. 로컬 Node.js 버전이 배포 중에 지정한 것과 동일한지 확인하여 함수를 배포합니다.

5. 다음 명령어를 사용하여 함수와 벤더링된 종속 항목을 배포합니다.

     gcloud functions deploy FUNCTION_NAME \
       --runtime RUNTIME_NAME \
       --set-build-env-vars GOOGLE_VENDOR_NPM_DEPENDENCIES=true
   

   다음과 같이 바꿉니다.

   • FUNCTION_NAME: 배포 중인 Cloud Run 함수의 이름
   • RUNTIME_NAME: 배포된 함수를 실행할 Node.js 런타임의 이름. 로컬 개발 환경에서 사용한 것과 동일한 Node.js 버전이어야 합니다.

Functions 프레임워크 패키지는 함수에 필요한 종속 항목입니다. 더 빠른 빌드를 위해 이 패키지를 벤더링하는 것이 좋습니다. 그렇지 않으면 함수가 빌드될 때 다운로드 및 설치됩니다.

package.json 파일에 npm 엔진을 지정하면 빌드 시 지정된 npm 버전이 다운로드됩니다. 이 동작을 숨기려면 package.json 파일에서 삭제합니다.