Ambiente de execução do Node.js

O ambiente de execução do Node.js é a pilha de software responsável por instalar o código do serviço da Web e as dependências dele, além de executar o serviço.

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

runtime: nodejsVERSION

Em que VERSION é o número da versão MAJOR do Node.js. Por exemplo, para usar a versão mais recente do Node.js, Node.js 20, especifique 20.

Para outras versões do Node.js com suporte e a versão do Ubuntu correspondente à sua versão do Node.js, consulte a Programação de suporte do ambiente de execução.

Versão do Node.js

O ambiente de execução do Node.js usa a versão estável mais recente da versão especificada no arquivo app.yaml. O App Engine é atualizado automaticamente para novas versões menores de patch e de lançamento, mas isso não acontece no caso da versão principal.

Por exemplo, é possível implantar o aplicativo no Node.js 10.9.4 e depois atualizá-lo automaticamente para a versão 10.10.0. No entanto, não será feita a atualização automática para o Node.js 12.x.x.

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

Por exemplo, para 20:

20.x.x
^20.0.0
~20
>=6

Se você especificar uma versão incompatível do Node.js no arquivo package.json, a implantação falhará com uma mensagem de erro.

Dependências

Durante a implantação, o ambiente de execução instala as dependências usando o comando npm install. O ambiente de execução também é compatível com os gerenciadores de pacote Yarn (yarn.lock) e Pnpm (pnpm-lock.yaml). Para mais informações, consulte Como especificar dependências. Como o ambiente de execução executa uma nova instalação, não é necessário fazer upload da pasta node_modules.

Para aceitar pacotes do Node.js que exigem extensões nativas, o ambiente de execução inclui pacotes do sistema que possibilitam o uso de ferramentas como o ImageMagick, FFmpeg e Chrome sem comando (links em inglês). Veja a lista completa em Pacotes de sistema incluídos. Para solicitar um pacote, faça um registro no Issue Tracker.

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 versão execute o script npm run build, siga um destes procedimentos:

Adicione um script gcp-build com um valor vazio ao arquivo package.json: "gcp-build":"". Para detalhes sobre como configurar o package.json, consulte Configurações dos pacotes de criação do Node.js.
Adicione a variável de ambiente de build GOOGLE_NODE_RUN_SCRIPTS com um valor vazio no arquivo app.yaml.
```
build_env_variables:
  GOOGLE_NODE_RUN_SCRIPTS: ''
```

Para ver detalhes sobre como especificar variáveis de ambiente de build, consulte a seção build_env_variables no arquivo app.yaml.

Inicialização do aplicativo

Por padrão, o ambiente de execução inicia o aplicativo executando node server.js. Se você especificar um script start no arquivo package.json, o ambiente de execução executará o script inicial especificado. Por exemplo:

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

Para que seu aplicativo receba solicitações HTTP, o script start precisa iniciar um servidor da Web com listener no host 0.0.0.0 e na porta especificada pela variável de ambiente PORT, que pode ser acessada no Node.js como process.env.PORT.

Como o script start é executado sempre que uma nova instância do aplicativo é criada, ele precisa ser leve e excluir as etapas do build para garantir o melhor desempenho.

É possível substituir esse comportamento especificando um script no campo entrypoint em app.yaml. Em vez de executar node server.js ou um script de inicialização, o ambiente de execução inicia o aplicativo com o comando especificado em entrypoint.

Variáveis de ambiente

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

Variável de ambiente	Descrição
`GAE_APPLICATION`	O ID do aplicativo do App Engine. Esse ID tem o prefixo "`region code`~", como "e~" para aplicativos implantados na Europa.
`GAE_DEPLOYMENT_ID`	O ID da implantação atual.
`GAE_ENV`	O ambiente do App Engine. Defina como `standard`.
`GAE_INSTANCE`	O ID da instância em que o serviço é executado no momento.
`GAE_MEMORY_MB`	A quantidade de memória disponível para o processo do aplicativo em MB.
`GAE_RUNTIME`	O ambiente de execução especificado no seu arquivo `app.yaml`.
`GAE_SERVICE`	O nome do serviço especificado no seu arquivo `app.yaml`. Se nenhum nome de serviço for especificado, ele será definido como `default`.
`GAE_VERSION`	O rótulo da versão atual do serviço.
`GOOGLE_CLOUD_PROJECT`	O ID do projeto do Google Cloud associado ao aplicativo.
`PORT`	A porta que recebe solicitações HTTP.
`NODE_ENV` (disponível apenas no ambiente de execução do Node.js)	Definido como `production` quando o serviço for implantado.

É possível definir outras variáveis de ambiente no arquivo app.yaml, mas os valores acima não podem ser modificados, exceto para NODE_ENV.

HTTPS e proxies de encaminhamento

O App Engine encerra as conexões HTTPS no balanceador de carga e encaminha as solicitações para o aplicativo. Em alguns aplicativos, é necessário determinar o protocolo e o IP de solicitação originais. O endereço IP do usuário está disponível no cabeçalho X-Forwarded-For padrão. Os aplicativos que precisam dessa informação devem configurar o framework da Web para confiar no proxy.

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

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

Definir trust proxy como true pode abrir a propriedade req.ip para a vulnerabilidade de spoofing de IP.

Sistema de arquivos

O ambiente de execução inclui um sistema de arquivos completo. O sistema de arquivos é somente leitura, exceto pelo local /tmp, que é um disco virtual que armazena dados na RAM da instância do App Engine.

Servidor de metadados

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

É possível acessar o servidor de metadados por meio dos endpoints a seguir:

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

As solicitações enviadas ao servidor de metadados precisam incluir o cabeçalho da solicitação Metadata-Flavor: Google. Esse cabeçalho indica que a solicitação foi enviada para recuperar valores de metadados.

A tabela a seguir lista os endpoints em que é possível fazer solicitações HTTP para metadados específicos.

Endpoint de metadados	Descrição
`/computeMetadata/v1/project/numeric-project-id`	Número do projeto atribuído ao seu projeto.
`/computeMetadata/v1/project/project-id`	ID do projeto atribuído ao seu projeto.
`/computeMetadata/v1/instance/region`	A região em que a instância está em execução.
`/computeMetadata/v1/instance/service-accounts/default/aliases`
`/computeMetadata/v1/instance/service-accounts/default/email`	E-mail da conta de serviço padrão atribuído ao seu projeto.
`/computeMetadata/v1/instance/service-accounts/default/`	Lista todas as contas de serviço padrão do seu projeto.
`/computeMetadata/v1/instance/service-accounts/default/scopes`	Lista todos os escopos compatíveis com as contas de serviço padrão.
`/computeMetadata/v1/instance/service-accounts/default/token`	Retorna o token de autenticação que pode ser usado para autenticar o aplicativo em outras Google Cloud APIs.

Por exemplo, para recuperar o ID do projeto, envie uma solicitação para http://metadata.google.internal/computeMetadata/v1/project/project-id.