blog
Painéis

Node.js no cPanel: escolher a versão e ativar o ambiente

Quais versões o servidor oferece, como apontar aplicação, Terminal e cron para o mesmo interpretador e os três comandos que confirmam que deu certo.

JR · · 7 min de leitura · 3 tabelas · 2 blocos de código

Resposta curta: a lista de versões disponíveis aparece no cPanel em Software > Setup Node.js App > Create Application, no seletor Node.js version. Depois de criar a aplicação, copie o comando de ativação que o painel gera e cole no Terminal e no cron, conferindo com node -v e which node.

Neste artigo
  1. O erro quase nunca começa no erro
  2. Onde o cPanel lista as versões de Node que o servidor tem
  3. Criando a aplicação na versão certa
  4. Por que copiar o comando de ativação em vez de digitá-lo
  5. node -v, which node e npm ls: o que cada um revela
  6. Erros comuns e o que cada um significa
  7. Ordem de trabalho que evita o retrabalho

O erro quase nunca começa no erro

O sintoma clássico é um 500 no navegador e uma linha de stderr.log reclamando de sintaxe, de um pacote ausente ou de uma API que "não existe". O que costuma estar por trás é mais simples: a aplicação roda num interpretador Node, o cron roda em outro e o Terminal, quando você abre, cai num terceiro.

Em hospedagem cPanel com Node.js, isso é esperado por design. A interface Setup Node.js App cria para cada aplicação um ambiente virtual próprio, com sua versão de Node e sua pasta de node_modules. Quem não entra nesse ambiente antes de rodar npm install está instalando pacote em um lugar que a aplicação nunca vai ler.

Este guia resolve a etapa anterior ao erro: ver quais versões o servidor oferece, criar a aplicação na versão certa, usar o comando de ativação que o próprio cPanel gera e confirmar, com três comandos, que o caminho carregado é mesmo o esperado. Da documentação oficial do cPanel, o Guide to Node.js Installations, vem o essencial: a instalação do Node.js é tarefa de administração do servidor e cada aplicação criada pelo painel ganha um ambiente virtual próprio. O restante do que está aqui, ler engines e .nvmrc, interpretar a saída do npm ls, montar a linha de cron com a ativação dentro dela, é procedimento de campo, não consta no documento.

Onde o cPanel lista as versões de Node que o servidor tem

A lista de versões não é algo que você escolhe livremente: é o que o administrador do servidor instalou. Para consultar:

  1. Entre no cPanel.
  2. Procure a seção Software.
  3. Clique em Setup Node.js App.
  4. Clique em Create Application.
  5. Abra o seletor Node.js version.

O que aparece ali é o conjunto de interpretadores que aquele servidor disponibiliza. Se a versão que seu projeto exige não está na lista, não existe ajuste no painel que a invente: ou o projeto roda em uma das versões ofertadas, ou é caso de abrir chamado com o provedor perguntando se aquela versão pode ser disponibilizada.

Se a entrada Setup Node.js App não existir no seu cPanel, o servidor não tem o recurso habilitado. A documentação do cPanel trata a instalação do Node.js como tarefa de administração do servidor, não do usuário final.

Como o package.json e o .nvmrc dizem qual versão escolher

Antes de abrir o painel, olhe o próprio projeto. Dois lugares costumam responder:

Na ausência dos dois, a regra prática é escolher a versão LTS mais recente que a lista oferecer e testar. Subir uma major a mais do que o framework suporta costuma quebrar em dependência nativa compilada, não no seu código.

Criando a aplicação na versão certa

Na tela Create Application, os campos relevantes são estes:

Campo O que preencher Efeito
Node.js version A versão escolhida na lista Define o interpretador do ambiente virtual da aplicação
Application mode Development ou Production Altera o comportamento esperado da aplicação
Application root Caminho da pasta do projeto dentro da home Onde o código vive
Application URL Domínio ou subpasta que serve a aplicação Endereço público
Application startup file Arquivo de entrada, por exemplo app.js O que o Passenger executa

Depois de salvar, a aplicação aparece na lista do Setup Node.js App com os botões de parar, reiniciar, editar e remover.

Backup antes de trocar a versão e como reverter

Trocar a versão de Node de uma aplicação que já está no ar muda o interpretador sob os pés dela. Faça backup antes: pelo menos uma cópia do Application root e do package.json, e um package-lock.json versionado se você usa.

Se algo quebrar depois da troca, o caminho de volta é editar a aplicação, selecionar a versão anterior, salvar e rodar o Run NPM Install de novo. Reinstalar as dependências importa: módulos nativos compilados para uma versão de Node não necessariamente carregam em outra.

Por que copiar o comando de ativação em vez de digitá-lo

Esta é a parte que a maioria pula. Na tela de detalhes da aplicação, o cPanel exibe um comando para entrar no ambiente virtual dela. É um source apontando para o activate daquele ambiente, geralmente seguido de um cd para a pasta do projeto. O formato é parecido com este (exemplo ilustrativo, use sempre o comando que o seu painel mostra):

source /home/usuario/nodevenv/minhaapp/18/bin/activate && cd /home/usuario/minhaapp

Copie esse comando do painel. Não digite de memória, não adapte um comando de outro tutorial: o caminho contém o nome da conta, o nome da aplicação e o número da versão, e qualquer um dos três errado te leva para um ambiente que não é o seu.

Com o comando copiado, há dois lugares onde ele precisa ser colado.

Ativar o ambiente antes de rodar npm install no Terminal

  1. Volte ao cPanel e abra Terminal, na seção Advanced.
  2. Cole o comando de ativação e pressione Enter.
  3. Só depois disso rode npm install, npm run build ou o que o projeto precisar.

Sem o source, o npm install usa o Node padrão do shell, cria node_modules com binários de outra versão e a aplicação continua lendo a pasta antiga. É o cenário em que o painel diz que tudo está certo e o navegador insiste em erro de módulo.

Por que o cron precisa do source dentro da própria linha

A tarefa agendada abre um shell novo, sem nada do que você fez no Terminal. O comando de ativação precisa estar dentro da própria linha do cron:

source /home/usuario/nodevenv/minhaapp/18/bin/activate && cd /home/usuario/minhaapp && node scripts/limpeza.js

Para agendar: cPanel, seção Advanced, Cron Jobs, escolha a frequência e cole a linha no campo de comando. Mantenha o && entre as partes: assim, se a ativação falhar, o script não roda com o interpretador errado, ele simplesmente não roda, e isso aparece no e-mail de saída do cron em vez de produzir um estrago silencioso.

Onde colar o comando de ativação do cPanelCopie o comando do painelTela da aplicação, não de memóriaCole no TerminalAntes de qualquer npm installCole na linha do cronCom && antes do nodeConfirme com which nodeCaminho deve conter nodevenv
Os dois lugares onde o comando de ativação precisa ser colado, e a checagem que confirma o ambiente.

node -v, which node e npm ls: o que cada um revela

Depois de ativar, verifique antes de instalar qualquer coisa. São três comandos e cada um responde a uma pergunta diferente.

Comando Pergunta que responde O que você espera ver
node -v Qual versão está ativa agora A mesma major selecionada no painel
which node De onde esse binário vem Um caminho dentro de nodevenv, com o nome da sua aplicação
npm ls --depth=0 Quais pacotes esse ambiente enxerga As dependências do seu package.json

O which node é o mais revelador dos três. Se ele devolver algo como /usr/bin/node ou /usr/local/bin/node, você não está no ambiente virtual: a ativação não rodou, rodou em outra janela ou o caminho foi digitado errado. Repita o source e teste de novo.

No npm ls --depth=0, linhas marcadas como UNMET DEPENDENCY indicam pacote declarado no package.json e ausente em node_modules. É o momento de rodar npm install com o ambiente já ativado, ou usar o botão Run NPM Install na tela da aplicação, que executa a instalação dentro do ambiente correto sem depender de você lembrar do source.

Erros comuns e o que cada um significa

Sintoma Causa provável O que fazer
Cannot find module em um pacote que você instalou npm install rodou fora do ambiente virtual Ativar com o comando do painel e reinstalar
Sintaxe moderna falhando (??, ?., import) Interpretador em versão anterior à que o código exige Editar a aplicação e subir a versão de Node
Funciona no Terminal, falha no cron Linha do cron sem o source do ambiente Colar o comando de ativação antes do node na própria linha
Erro de módulo nativo após trocar a versão Binário compilado para outra major Apagar node_modules e reinstalar no ambiente novo
which node aponta para /usr/bin/node Ambiente virtual não ativado Repetir o source copiado da tela da aplicação

Ordem de trabalho que evita o retrabalho

A sequência que mantém as três pontas, aplicação, Terminal e cron, no mesmo interpretador:

  1. Descobrir a versão exigida pelo projeto (engines no package.json ou .nvmrc).
  2. Conferir se ela aparece no seletor de Setup Node.js App.
  3. Fazer backup da pasta do projeto antes de criar ou alterar a aplicação.
  4. Criar a aplicação com versão, Application root, Application URL e startup file preenchidos.
  5. Copiar o comando de ativação exibido na tela da aplicação.
  6. Colar no Terminal, rodar node -v, which node e npm ls --depth=0.
  7. Instalar dependências com o ambiente ativo ou pelo Run NPM Install.
  8. Colar o mesmo comando de ativação no início de cada linha de cron do projeto.
  9. Reiniciar a aplicação pela tela do Setup Node.js App.

Se depois disso o erro persistir, aí sim o problema é outro, e o lugar de olhar é o stderr.log da aplicação. Mas vale checar o interpretador primeiro: a verificação leva menos de um minuto e elimina a classe inteira de falhas em que o ambiente, e não o código, está errado.

Nada neste guia foi medido por nós. O que é documental: o Guide to Node.js Installations do cPanel, consultado em outubro de 2026, trata a instalação do Node.js como tarefa de administração do servidor e descreve que cada aplicação criada pelo painel recebe um ambiente virtual próprio, com versão e node_modules separados. A ordem de trabalho, a insistência no source dentro da linha de cron, a leitura de node -v, which node e npm ls --depth=0 e a tabela de erros comuns são experiência de operação, não têm respaldo naquele documento e podem variar conforme a configuração do servidor. Os caminhos usados nos exemplos de comando são ilustrativos: o comando válido é sempre o que aparece na tela da sua aplicação.

Ordem de trabalho do Node.js no cPanelDescobrir versãoengines no package.json ou .nvmrcBackupPasta do projeto e package.jsonCriar aplicaçãoVersão, root, URL, startup fileAtivar e verificarnode -v, which node, npm lsInstalar e reiniciarRun NPM Install e restart
Sequência que mantém aplicação, Terminal e cron no mesmo interpretador.

Referências

  1. Documentação oficial (cpanel) — Guide to Node.js Installations. Consultado em 2026-10-20.
Leia também