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.

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
- O erro quase nunca começa no erro
- Onde o cPanel lista as versões de Node que o servidor tem
- Criando a aplicação na versão certa
- Por que copiar o comando de ativação em vez de digitá-lo
- node -v, which node e npm ls: o que cada um revela
- Erros comuns e o que cada um significa
- 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:
- Entre no cPanel.
- Procure a seção Software.
- Clique em Setup Node.js App.
- Clique em Create Application.
- 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:
- O campo
enginesdopackage.json, quando o projeto declara algo como"node": ">=18". - O arquivo
.nvmrc, se o projeto veio de um ambiente local que usa nvm.
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
- Volte ao cPanel e abra Terminal, na seção Advanced.
- Cole o comando de ativação e pressione Enter.
- Só depois disso rode
npm install,npm run buildou 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.
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:
- Descobrir a versão exigida pelo projeto (
enginesnopackage.jsonou.nvmrc). - Conferir se ela aparece no seletor de Setup Node.js App.
- Fazer backup da pasta do projeto antes de criar ou alterar a aplicação.
- Criar a aplicação com versão, Application root, Application URL e startup file preenchidos.
- Copiar o comando de ativação exibido na tela da aplicação.
- Colar no Terminal, rodar
node -v,which nodeenpm ls --depth=0. - Instalar dependências com o ambiente ativo ou pelo Run NPM Install.
- Colar o mesmo comando de ativação no início de cada linha de cron do projeto.
- 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.
Referências
- Documentação oficial (cpanel) — Guide to Node.js Installations. Consultado em 2026-10-20.