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 22 (prévia), especifique 22.
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 a versão 22 (prévia):
22.x.x^22.0.0~22>=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-buildcom um valor vazio ao arquivopackage.json:"gcp-build":"". Para detalhes sobre como configurar opackage.json, consulte Configurações dos pacotes de criação do Node.js. Adicione a variável de ambiente de build
GOOGLE_NODE_RUN_SCRIPTScom um valor vazio no arquivoapp.yaml.build_env_variables: GOOGLE_NODE_RUN_SCRIPTS: ''
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);
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://metadatahttp://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.