Esta página foi traduzida pela API Cloud Translation.

Ambiente de tempo de execução do Node.js

O tempo de execução do Node.js é a pilha de software responsável por instalar o código do seu serviço Web e as respetivas dependências, bem como executar o seu serviço.

O tempo de execução do Node.js para o App Engine no ambiente padrão é declarado no ficheiro app.yaml:

runtime: nodejsVERSION

Em que VERSION é o número da versão do MAJOR Node.js. Por exemplo, para usar a versão mais recente do Node.js, o Node.js 24 (pré-visualização), especifique 24.

Para outras versões suportadas do Node.js e a versão correspondente do Ubuntu para a sua versão do Node.js, consulte a Programação de apoio técnico de tempo de execução.

Versão do Node.js

A versão mais recente do Node.js suportada é a 24 (pré-visualização). O tempo de execução do Node.js usa a versão estável mais recente da versão especificada no ficheiro app.yaml. O App Engine é atualizado automaticamente para novas versões de patch e lançamentos secundários, mas não atualiza automaticamente a versão principal.

Por exemplo, a sua aplicação pode ser implementada no Node.js 10.9.4 e atualizada automaticamente para a versão 10.10.0, mas não é atualizada automaticamente para o Node.js 12.x.x.

Uma vez que as versões secundárias e de patch são atualizadas automaticamente, se estiver presente, a propriedade engines.node no ficheiro package.json só pode especificar a versão principal e ser compatível com a versão do Node.js especificada no ficheiro app.yaml.

Por exemplo, para 24 (pré-visualização):

24.x.x
^24.0.0
~24
>=6

Se especificar uma versão do Node.js incompatível no ficheiro package.json, a implementação falha com uma mensagem de erro.

Dependências

Durante a implementação, o tempo de execução instala as dependências através do comando npm install. O tempo de execução também suporta os gestores de pacotes Yarn (yarn.lock) e Pnpm (pnpm-lock.yaml). Para mais informações, consulte o artigo Especificar dependências. Uma vez que o tempo de execução faz uma nova instalação, não precisa de carregar a pasta node_modules.

Para suportar pacotes Node.js que requerem extensões nativas, o tempo de execução inclui pacotes do sistema que lhe permitem usar ferramentas como ImageMagick, FFmpeg e Chrome sem interface. Consulte a lista completa de pacotes em Pacotes do sistema incluídos. Para pedir um pacote, apresente um problema no Issue Tracker.

Script de compilação do NPM

Por predefinição, quando implementa a app no App Engine, 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.

Para impedir que a compilação execute o script npm run build, tem de:

Adicione um script gcp-build com um valor vazio no seu ficheiro package.json: "gcp-build":"". Para ver detalhes sobre a configuração do package.json, consulte as configurações dos buildpacks do Node.js.
Adicione a variável de ambiente GOOGLE_NODE_RUN_SCRIPTS com um valor vazio no seu ficheiro app.yaml.
```
build_env_variables:
  GOOGLE_NODE_RUN_SCRIPTS: ''
```

Para ver detalhes sobre a especificação de variáveis do ambiente de compilação, consulte a secção build_env_variables no ficheiro app.yaml.

Arranque da aplicação

Por predefinição, o tempo de execução inicia a sua aplicação executando node server.js. Se especificar um script start no ficheiro package.json, o tempo de execução executa o script de início especificado. Por exemplo:

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

Para que a sua app receba pedidos HTTP, o script start deve iniciar um servidor Web que escute no anfitrião 0.0.0.0 e na porta especificada pela PORT variável de ambiente, que é acessível no Node.js como process.env.PORT.

Para conseguir o melhor desempenho, o script start deve ser simples e excluir os passos de compilação, uma vez que é executado sempre que é criada uma nova instância da sua aplicação.

Pode substituir este comportamento especificando um script no campo entrypoint em app.yaml. Em vez de executar node server.js ou um script de início, o tempo de execução inicia a aplicação com o comando especificado em entrypoint.

Variáveis de ambiente

As seguintes variáveis de ambiente são definidas pelo tempo de execução:

Variável de ambiente	Descrição
`GAE_APPLICATION`	O ID da sua aplicação do App Engine. Este ID tem o prefixo "`region code`~", como "e~" para aplicações implementadas na Europa.
`GAE_DEPLOYMENT_ID`	O ID da implementação atual.
`GAE_ENV`	O ambiente do App Engine. Definido como `standard`.
`GAE_INSTANCE`	O ID da instância na qual o seu serviço está atualmente em execução.
`GAE_MEMORY_MB`	A quantidade de memória disponível para o processo da aplicação, em MB.
`GAE_RUNTIME`	O tempo de execução especificado no ficheiro `app.yaml`.
`GAE_SERVICE`	O nome do serviço especificado no ficheiro `app.yaml`. Se não for especificado nenhum nome de serviço, este é definido como `default`.
`GAE_VERSION`	A etiqueta da versão atual do seu serviço.
`GOOGLE_CLOUD_PROJECT`	O Google Cloud ID do projeto associado à sua aplicação.
`PORT`	A porta que recebe pedidos HTTP.
`NODE_ENV` (disponível apenas no tempo de execução do Node.js)	Definido como `production` quando o serviço é implementado.

Pode definir variáveis de ambiente adicionais no ficheiro app.yaml, mas os valores acima não podem ser substituídos, exceto o NODE_ENV.

HTTPS e proxies de encaminhamento

O App Engine termina as ligações HTTPS no equilibrador de carga e encaminha os pedidos para a sua aplicação. Algumas aplicações precisam de determinar o IP e o protocolo do pedido original. O endereço IP do utilizador está disponível no cabeçalho X-Forwarded-For padrão. As aplicações que requerem estas informações devem configurar a respetiva framework Web para confiar no proxy.

Com o Express.js, use a definição trust proxy:

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

Tenha em atenção que definir trust proxy como true pode expor a propriedade req.ip a vulnerabilidades de roubo de IP.

Sistema de ficheiros

O tempo de execução inclui um sistema de ficheiros completo. O sistema de ficheiros é apenas de leitura, exceto para a localização /tmp, que é um disco virtual que armazena dados na RAM da instância do App Engine.

Servidor de metadados

Cada instância da sua aplicação pode usar o servidor de metadados do App Engine para consultar informações sobre a instância e o seu projeto.

Pode aceder ao servidor de metadados através dos seguintes pontos finais:

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

Os pedidos enviados para o servidor de metadados têm de incluir o cabeçalho do pedido Metadata-Flavor: Google. Este cabeçalho indica que o pedido foi enviado com a intenção de obter valores de metadados.

A tabela seguinte lista os pontos finais onde pode fazer pedidos HTTP para metadados específicos:

Ponto final de metadados	Descrição
`/computeMetadata/v1/project/numeric-project-id`	O número do projeto atribuído ao seu projeto.
`/computeMetadata/v1/project/project-id`	O ID do projeto atribuído ao seu projeto.
`/computeMetadata/v1/instance/region`	A região em que a instância está a ser executada.
`/computeMetadata/v1/instance/service-accounts/default/aliases`
`/computeMetadata/v1/instance/service-accounts/default/email`	O email da conta de serviço predefinido atribuído ao seu projeto.
`/computeMetadata/v1/instance/service-accounts/default/`	Apresenta todas as contas de serviço predefinidas do seu projeto.
`/computeMetadata/v1/instance/service-accounts/default/scopes`	Lista todos os âmbitos suportados para as contas de serviço predefinidas.
`/computeMetadata/v1/instance/service-accounts/default/token`	Devolve o token de autorização que pode ser usado para autenticar a sua aplicação noutras APIs Google Cloud.

Por exemplo, para obter o ID do projeto, envie um pedido para http://metadata.google.internal/computeMetadata/v1/project/project-id.