Toda aplicação Node.js executa dentro de um processo do sistema operacional. O objeto global process no Node.js fornece informações e controles sobre esse processo: argumentos de linha de comando, variáveis de ambiente, diretório atual, uso de memória, sinais, códigos de saída e eventos relacionados a erros.
Como process está disponível globalmente, não é obrigatório importá-lo. Mesmo assim, compreender suas APIs é importante para criar CLIs, configurar servidores, implementar shutdown seguro e diagnosticar consumo de recursos.
Neste guia, você aprenderá a usar process.argv, process.env, stdin, stdout, stderr, sinais, exitCode, cwd, memória, uptime, nextTick e eventos de exceção, com cuidados para produção.
O que é o objeto process?
process é uma instância de EventEmitter que representa o processo Node.js atual. Ele expõe propriedades do runtime, do sistema operacional e do ambiente de execução.
A documentação oficial de process apresenta todas as propriedades e eventos. Para conceitos fundamentais, consulte o que é Node.js e EventEmitter no Node.js.
Informações da versão
console.log(process.version);
console.log(process.versions);process.version informa a versão do Node.js. process.versions mostra versões de componentes como V8, OpenSSL, libuv e módulos ABI. Essas informações são úteis em relatórios de diagnóstico.
Plataforma e arquitetura
console.log({
platform: process.platform,
arch: process.arch
});A plataforma pode ser linux, win32, darwin e outros valores. Evite espalhar condicionais pelo projeto; encapsule diferenças de sistema em um módulo específico.
Argumentos com process.argv
Ao executar:
node cli.js --port 3000 --verboseOs argumentos ficam em:
console.log(process.argv);O primeiro item normalmente é o executável do Node.js e o segundo é o caminho do script. Os demais foram fornecidos pelo usuário.
const args = process.argv.slice(2);Para CLIs complexas, use um parser que valide opções, tipos, valores obrigatórios e mensagens de ajuda. O artigo de Readline no Node.js mostra interfaces interativas.
Variáveis de ambiente
const port = Number(process.env.PORT || 3000);
const environment = process.env.NODE_ENV || 'development';Todos os valores de process.env devem ser tratados como strings ou ausentes. Converta e valide antes do uso. Veja Variáveis de Ambiente no Node.js para configuração segura.
Diretório de trabalho
console.log(process.cwd());cwd() retorna o diretório de trabalho atual, que pode ser diferente do diretório do arquivo. Serviços iniciados por systemd, containers e gerenciadores de processos podem definir outro caminho.
Para localizar arquivos próximos ao módulo, use __dirname em CommonJS ou import.meta.url em ES Modules, em vez de assumir o cwd.
Alterando o diretório
process.chdir('/srv/application');Alterar o diretório afeta todo o processo e pode surpreender outras partes da aplicação. Prefira caminhos absolutos e evite chdir() em bibliotecas.
Entrada padrão
process.stdin é uma Readable Stream:
process.stdin.setEncoding('utf8');
process.stdin.on('data', chunk => {
console.log('Recebido:', chunk.trim());
});Para arquivos grandes ou pipelines Unix, processe chunks e respeite o fluxo. Não acumule entrada ilimitada em memória.
Saída padrão
process.stdout.write('Resultado\n');
process.stderr.write('Aviso\n');Use stdout para saída normal e stderr para erros ou diagnósticos. Essa separação permite redirecionar resultados sem misturar mensagens.
Backpressure em stdout
write() pode retornar false:
if (!process.stdout.write(largeOutput)) {
await new Promise(resolve => {
process.stdout.once('drain', resolve);
});
}Ignorar backpressure pode aumentar memória ao produzir saída mais rapidamente do que o destino consegue consumir.
Códigos de saída
Por convenção, zero representa sucesso:
process.exitCode = 1;Definir exitCode permite que o event loop conclua operações pendentes. É preferível a chamar process.exit() imediatamente.
Cuidados com process.exit()
process.stdout.write('Finalizando');
process.exit(1);A chamada pode encerrar antes que a saída seja gravada. Ela também interrompe operações assíncronas e limpeza. Use apenas quando o encerramento imediato for realmente necessário.
Sinais do sistema operacional
process.on('SIGTERM', async () => {
await shutdown();
});
process.on('SIGINT', async () => {
await shutdown();
});SIGTERM é comum em orquestradores e SIGINT ocorre ao pressionar Ctrl+C. Implemente idempotência para impedir duas rotinas de encerramento simultâneas.
Veja Graceful Shutdown no Node.js para servidores, bancos e filas.
Uptime
console.log(process.uptime());O valor representa segundos desde a inicialização. Ele é útil em health checks e diagnósticos, mas não substitui um identificador da instância.
Uso de memória
console.log(process.memoryUsage());O resultado inclui:
rss: memória residente do processo;heapTotal: heap alocado pelo V8;heapUsed: heap efetivamente utilizado;external: memória de objetos externos;arrayBuffers: memória associada a ArrayBuffers.
Observe tendências e compare com carga. Um valor isolado não confirma vazamento.
Uso de CPU
const start = process.cpuUsage();
performTask();
console.log(process.cpuUsage(start));O resultado apresenta tempo de CPU em microssegundos no espaço de usuário e sistema. Ele não representa tempo de parede; uma operação pode esperar rede por muito tempo e consumir pouca CPU.
Identificador do processo
console.log(process.pid);
console.log(process.ppid);PID e PID do processo pai ajudam em logs e diagnósticos. PIDs podem ser reutilizados pelo sistema, portanto não servem como identificador global permanente.
process.nextTick()
process.nextTick(() => {
console.log('Executado depois da pilha atual');
});NextTick executa antes de o event loop avançar. Uma recursão contínua pode causar starvation e impedir timers ou I/O. Use para pequenas continuações e consistência de APIs.
Eventos de exceção
uncaughtException é emitido quando uma exceção chega ao topo:
process.on('uncaughtException', error => {
emergencyLogger.error(error);
process.exitCode = 1;
});Depois de uma exceção não tratada, o estado da aplicação pode estar inconsistente. Registre o mínimo necessário, encerre de forma controlada e deixe um supervisor reiniciar.
Rejeições não tratadas
process.on('unhandledRejection', reason => {
emergencyLogger.error('Promise rejeitada', { reason });
});Corrija a origem em vez de usar o evento como tratamento normal. Toda Promise deve ser aguardada ou ter catch apropriado.
warning
process.on('warning', warning => {
console.warn({
name: warning.name,
message: warning.message,
stack: warning.stack
});
});Warnings podem indicar listeners em excesso, APIs depreciadas ou condições do runtime. Monitore sem transformar todo warning em falha automática.
beforeExit e exit
beforeExit ocorre quando o event loop fica sem trabalho. Novo trabalho assíncrono pode prolongar o processo. exit acontece durante o encerramento e aceita apenas operações síncronas.
process.on('exit', code => {
fs.writeSync(2, `Saída: ${code}\n`);
});Não tente aguardar Promises no evento exit.
Recursos ativos
APIs de diagnóstico podem ajudar a identificar handles ou requisições que mantêm o processo vivo. Algumas são internas ou possuem estabilidade limitada. Prefira ferramentas suportadas, Async Hooks e relatórios de diagnóstico.
Relatórios de diagnóstico
Dependendo da configuração, o Node.js pode gerar relatórios com stacks, heap, versões e informações do sistema. Esses arquivos podem conter caminhos, argumentos e variáveis. Proteja acesso e remova segredos.
Segurança
Não registre process.env inteiro. Ambientes frequentemente contêm credenciais. Também valide argumentos e caminhos de entrada antes de usá-los em arquivos ou comandos.
Erros comuns
- Usar process.exit cedo: logs e limpeza são interrompidos.
- Confiar no cwd: o serviço pode iniciar em outro diretório.
- Tratar env como número: valores são strings.
- Registrar todas as variáveis: segredos aparecem nos logs.
- Continuar após uncaughtException: o estado pode estar corrompido.
- Criar loop de nextTick: I/O sofre starvation.
- Ignorar backpressure: a memória cresce.
Boas práticas para produção
- Valide argumentos e variáveis de ambiente.
- Use exitCode em vez de exit quando possível.
- Trate SIGTERM e SIGINT de forma idempotente.
- Separe stdout e stderr.
- Respeite backpressure.
- Monitore memória, CPU e uptime.
- Encerre depois de erros fatais.
- Evite dados sensíveis em diagnósticos.
- Use caminhos absolutos.
- Teste o processo em containers e supervisores.
Conclusão
O objeto process no Node.js conecta o código JavaScript ao ambiente de execução. Ele oferece argumentos, configuração, streams, métricas, sinais e eventos fundamentais para scripts e servidores.
O uso correto exige atenção ao ciclo de vida. Validar entradas, evitar encerramento abrupto, tratar sinais e proteger segredos torna o processo mais previsível. Com essas práticas, a aplicação se integra melhor a terminais, containers, orquestradores e sistemas de monitoramento.
