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 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_SCRIPTS
com 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. 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://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
.