# 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.

> 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.

João Rizzon · 2026-10-21 · Painéis

---

## 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](https://docs.cpanel.net/knowledge-base/general-server-administration/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 `engines` do `package.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):

```bash
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 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:

```bash
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 (`engines` no `package.json` ou `.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 node` e `npm 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](https://docs.cpanel.net/knowledge-base/general-server-administration/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.

