Ambiente de execução do Node.js

A função do Cloud Run é executada em um ambiente que consiste em uma versão do sistema operacional com pacotes complementares, suporte a linguagens e a biblioteca Node.js Functions Framework que dá suporte e invoca a função. Esse ambiente é identificado pela versão da linguagem e é conhecido como ID de execução.

Preparação de funções

É possível preparar uma função diretamente do console do Google Cloud ou gravá-la na máquina local e fazer upload dela. Para preparar a máquina local para o desenvolvimento do Node.js, consulte Configurar um ambiente de desenvolvimento do Node.js.

Ambientes de execução e imagens de base compatíveis com o Node.js

Ambiente de execução ID do ambiente de execução Pilhas Imagem de base do ambiente de execução
Node.js 22 nodejs22
  • google-22 (padrão)
  • google-22-full
    		•
  • google-22/nodejs22
  • google-22-full/nodejs22
    		•
    Node.js 20 nodejs20
  • google-22 (padrão)
  • google-22-full
    		•
  • google-22/nodejs20
  • google-22-full/nodejs20
    		•
    Node.js 18 nodejs18
  • google-22 (padrão)
  • google-22-full
    		•
  • google-22/nodejs18
  • google-22-full/nodejs18
    		•
    Node.js 16 nodejs16 google-18-full google-18-full/nodejs16
    Node.js 14 nodejs14 google-18-full google-18-full/nodejs14
    Node.js 12 nodejs12 google-18-full google-18-full/nodejs12
    Node.js 10 nodejs10 google-18-full google-18-full/nodejs10
    Node.js 8 nodejs8 Desativado Desativado
    Node.js 6 nodejs6 Desativado Desativado

    Selecionar o ambiente de execução

    É possível selecionar um dos ambientes de execução do Node.js com suporte para a função durante a implantação.

    É possível selecionar uma versão do ambiente de execução usando o console do Google Cloud ou a CLI gcloud. Clique na guia para conferir instruções sobre como usar a ferramenta de sua preferência:

    gcloud

    Especifique a imagem de base do Node.js para a função usando a flag --base-image durante a implantação. Exemplo:

    gcloud beta run deploy FUNCTION \
    --source . \
    --function FUNCTION_ENTRYPOINT \
    --base-image nodejs22

    Substitua:

    • FUNCTION pelo nome da função que você está implantando. É possível omitir esse parâmetro inteiramente, mas será solicitado o nome, se você omiti-lo.

    • FUNCTION_ENTRYPOINT: o ponto de entrada da função no código-fonte. Esse é o código que o Cloud Run executa quando é executada. O valor dessa sinalização precisa ser um nome de função ou de classe totalmente qualificada no código-fonte.

    Para instruções detalhadas sobre como implantar uma função usando a CLI gcloud, consulte Implantar funções no Cloud Run.

    Console

    É possível selecionar uma versão do ambiente de execução ao criar ou atualizar uma função do Cloud Run no console do Google Cloud. Para instruções detalhadas sobre como implantar uma função, consulte Implantar funções no Cloud Run.

    Para selecionar um ambiente de execução no console do Google Cloud ao criar uma função, siga estas etapas:

    1. No console do Google Cloud, acesse a página do Cloud Run:

      Acessar o Cloud Run

    2. Clique em Escrever uma função.

    3. Na lista Ambiente de execução, selecione uma versão do ambiente de execução do Node.js.

    4. Clique em Criar e aguarde o Cloud Run criar o serviço usando uma revisão do marcador de posição.

    5. O console vai redirecionar você para a guia Origem, em que você pode ver o código-fonte da sua função. Clique em Salvar e implantar novamente.

    Para instruções detalhadas sobre como atualizar a versão do ambiente de execução depois que a função for implantada, consulte Reimplantar o novo código-fonte.

    Estrutura do código-fonte

    Para que as funções do Cloud Run encontrem a definição da sua função, seu código-fonte precisa seguir uma estrutura específica. Consulte Escrever funções do Cloud Run para mais informações.

    Especificar as dependências

    É possível especificar dependências para suas funções listando-as em um arquivo package.json. Para mais informações, consulte Especificar dependências no Node.js.

    Script de build do NPM

    Por padrão, o ambiente de execução do Node.js executará npm run build se um script build for detectado em package.json. Se você precisar de mais controle sobre as etapas do build antes de iniciar o aplicativo, forneça uma etapa de build personalizada adicionando um script gcp-build ao arquivo package.json.

    Para evitar que sua build execute o script npm run build:

    • Adicione um script gcp-build com um valor vazio ao arquivo package.json: "gcp-build":"".

    • Definir a variável de ambiente de build GOOGLE_NODE_RUN_SCRIPTS como a string vazia para impedir que todos os scripts sejam executados.

    Conclusão de função assíncrona

    Ao trabalhar com tarefas assíncronas que envolvem callbacks ou objetos Promise, é necessário informar explicitamente o ambiente de execução que sua função encerrou a execução dessas tarefas. É possível fazer isso de várias maneiras diferentes, conforme mostrado nos exemplos abaixo. O segredo é que o código aguarde a conclusão da tarefa assíncrona ou da Promise antes de retornar. Caso contrário, o componente assíncrono da função pode ser encerrado antes da conclusão.

    Funções baseadas em eventos

    Retorno implícito

      exports.implicitlyReturning = async (event, context) => {
    return await asyncFunctionThatReturnsAPromise();
  };

    Retorno explícito

      exports.explicitlyReturning = function (event, context) {
    return asyncFunctionThatReturnsAPromise();
  };

    Funções HTTP

    // OK: await-ing a Promise before sending an HTTP response
await Promise.resolve();

// WRONG: HTTP functions should send an
// HTTP response instead of returning.
return Promise.resolve();

// HTTP functions should signal termination by returning an HTTP response.
// This should not be done until all background tasks are complete.
res.send(200);
res.end();

// WRONG: this may not execute since an
// HTTP response has already been sent.
return Promise.resolve();

    Usar o middleware para processar solicitações HTTP

    As funções HTTP do Node.js fornecem objetos request e response compatíveis com o ExpressJS para simplificar o consumo de solicitações HTTP. As funções do Cloud Run lêem automaticamente o corpo da solicitação. Dessa maneira, você sempre recebe o corpo de uma solicitação, independentemente do tipo de mídia. Isso significa que as solicitações HTTP precisam ser consideradas totalmente lidas no momento em que o código é executado. O aninhamento de apps ExpressJS precisa ser usado com a ressalva de que um middleware com corpo de solicitação não lido pode não ter o comportamento esperado.

    Usar módulos ES

    Os módulos do ECMAScript (módulos ES ou ESM) são um recurso padrão do TC39, sem sinalização, na versão 14 ou posterior do Node para carregar módulos JavaScript. Ao contrário do CommonJS, o ESM fornece uma API assíncrona para carregar módulos. Elas também fornecem uma melhoria de sintaxe popular com as instruções import e export, que podem ser usadas em uma função do Cloud Run (em vez das instruções require).

    Para usar o ESM em uma função do Cloud Run, é necessário declarar "type": "module" no package.json.

    {
  ...
  "type": "module",
  ...
}

    Em seguida, use as instruções import e export.

    Saiba mais sobre o uso de módulos ES.