O tempo de execução do Node.js

A sua função do Cloud Run é executada num ambiente que consiste numa versão do sistema operativo com pacotes suplementares, suporte de idiomas e a biblioteca Node.js Functions Framework que suporta e invoca a sua função. Este ambiente é identificado pela versão do idioma e é conhecido como o ID de tempo de execução.

Preparação da função

Pode preparar uma função diretamente a partir da Google Cloud consola ou escrevê-la no seu computador local e carregá-la. Para preparar o seu computador local para o desenvolvimento de Node.js, consulte o artigo Configure um ambiente de desenvolvimento de Node.js.

Imagens base e tempos de execução do Node.js suportados

Tempo de execução ID do ambiente de execução Camadas Imagem base do tempo de execução
Node.js 24
(apenas pré-visualização)		 nodejs24
  • google-24 (predefinição)
  • google-24-full
    		•
  • google-24/nodejs24
  • google-24-full/nodejs24
    		•
    Node.js 22 nodejs22
  • google-22 (predefinição)
  • google-22-full
    		•
  • google-22/nodejs22
  • google-22-full/nodejs22
    		•
    Node.js 20 nodejs20
  • google-22 (predefinição)
  • google-22-full
    		•
  • google-22/nodejs20
  • google-22-full/nodejs20
    		•
    Node.js 18 nodejs18
  • google-22 (predefiniçã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

    Selecione o tempo de execução

    Pode selecionar um dos tempos de execução do Node.js suportados para a sua função durante a implementação.

    Pode selecionar uma versão de tempo de execução através da Google Cloud consola ou da CLI gcloud. Clique no separador para ver instruções sobre como usar a ferramenta da sua escolha:

    gcloud

    Especifique a imagem base do Node.js para a sua função através da flag --base-image ao implementar a função. Por exemplo:

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

    Substituir:

    • FUNCTION com o nome da função que está a implementar. Pode omitir este parâmetro por completo, mas é-lhe pedido o nome se o omitir.

    • FUNCTION_ENTRYPOINT com o ponto de entrada da sua função no código-fonte. Este é o código que o Cloud Run executa quando a sua função é executada. O valor desta flag tem de ser um nome de função ou um nome de classe totalmente qualificado que exista no seu código-fonte.

    Para obter instruções detalhadas sobre a implementação de uma função através da CLI gcloud, consulte o artigo Implemente funções no Cloud Run.

    Consola

    Pode selecionar uma versão de tempo de execução quando cria ou atualiza uma função do Cloud Run na Google Cloud consola. Para ver instruções detalhadas sobre como implementar uma função, consulte o artigo Implemente funções no Cloud Run.

    Para selecionar um tempo de execução na Google Cloud consola quando cria uma função, siga estes passos:

    1. Na Google Cloud consola, aceda à página do Cloud Run:

      Aceda ao Cloud Run

    2. Clique em Escrever uma função.

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

    4. Clique em Criar e aguarde que o Cloud Run crie o serviço com uma revisão de marcador de posição.

    5. A consola redireciona para o separador Origem, onde pode ver o código-fonte da sua função. Clique em Guardar e voltar a implementar.

    Para obter instruções detalhadas sobre como atualizar a versão do tempo de execução após a implementação da função, consulte o artigo Volte a implementar um 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, o código fonte tem de seguir uma estrutura específica. Consulte o artigo Escreva funções do Cloud Run para mais informações.

    Especifique dependências

    Pode especificar dependências para as suas funções listando-as num ficheiro package.json. Para mais informações, consulte o artigo Especifique dependências no Node.js.

    Script de compilação do NPM

    Por predefinição, o tempo de execução do Node.js executa npm run build se for detetado um script build em package.json. Se precisar de controlo adicional sobre os passos de compilação antes de iniciar a aplicação, pode fornecer um passo de compilação personalizado adicionando um script gcp-build ao ficheiro package.json.

    Pode impedir que a compilação execute o script npm run build de uma das seguintes formas:

    • Adicionar um script gcp-build com um valor vazio no ficheiro package.json: "gcp-build":"".

    • Definir a variável de ambiente de compilação GOOGLE_NODE_RUN_SCRIPTS para a string vazia para impedir a execução de todos os scripts.

    Conclusão de funções assíncronas

    Quando trabalha com tarefas assíncronas que envolvem callbacks ou objetos Promise, tem de informar explicitamente o tempo de execução de que a sua função terminou de executar estas tarefas. Pode fazê-lo de várias formas diferentes, conforme mostrado nos exemplos seguintes. A chave é que o seu código tem de aguardar que a tarefa assíncrona ou Promise seja concluída antes de ser devolvida. Caso contrário, o componente assíncrono da sua função pode ser terminado antes de ser concluído.

    Funções orientadas por eventos

    Devolução implícita

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

    Devolução explícita

      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();

    Use software intermédio para processar pedidos HTTP

    As funções HTTP do Node.js fornecem objetos request e response compatíveis com o ExpressJS para simplificar o consumo de pedidos HTTP. As funções do Cloud Run leem automaticamente o corpo do pedido, pelo que recebe sempre o corpo de um pedido independentemente do tipo de suporte. Isto significa que os pedidos HTTP devem ser considerados como tendo sido totalmente lidos no momento em que o seu código é executado. A aninhagem de apps ExpressJS deve ser usada com esta ressalva. Especificamente, o middleware que espera que o corpo de um pedido não seja lido pode não funcionar como esperado.

    Use módulos ES

    Os módulos ECMAScript (módulos ES ou ESM) são uma funcionalidade padrão do TC39, sem indicação de flag, na versão 14 ou superior do Node para carregar módulos JavaScript. Ao contrário do CommonJS, o ESM oferece uma API assíncrona para carregar módulos. Também oferece uma melhoria popular da sintaxe com declarações import e export que podem ser usadas numa função do Cloud Run (em vez de declarações require).

    Para usar o ESM numa função do Cloud Run, tem de declarar "type": "module" no seu package.json.

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

    Em seguida, pode usar as declarações import e export.

    Saiba como usar os módulos ES.