Como publicar uma aplicação Node.js no Plesk
Do componente no servidor ao botão de reiniciar, seguindo a documentação oficial do Plesk Obsidian, com o que fazer quando a aplicação sobe e responde com erro.

Resposta curta: são 5 passos no painel: habilitar o suporte a Node.js no servidor, escolher a versão no domínio, apontar a raiz do aplicativo e o arquivo de entrada, rodar NPM install e reiniciar o aplicativo após cada mudança. Se der erro, use o modo development e o log da aplicação.
Neste artigo
- O que o Plesk faz quando você publica uma aplicação Node.js
- Faça backup e confira o que precisa existir na pasta antes de publicar
- Como publicar pelo painel em cinco passos
- Onde cadastrar variáveis e qual modo deixar no ar
- O que fazer quando a aplicação sobe mas devolve erro
- O que cada erro frequente indica e como corrigir
- Como desfazer se algo der errado
O que o Plesk faz quando você publica uma aplicação Node.js
No Plesk, uma aplicação Node.js não é um site PHP com um arquivo a mais. O painel entrega as requisições do domínio a um processo Node que fica rodando, e é o próprio painel que inicia, para e reinicia esse processo. Você não precisa deixar um terminal aberto com node app.js. A documentação oficial do Plesk Obsidian descreve esse suporte como um componente do servidor que, depois de instalado, aparece como um botão Node.js dentro de cada domínio.
Isso tem uma consequência prática que confunde muita gente: o processo Node carrega o código uma vez e continua com ele na memória. Se você edita um arquivo e não reinicia a aplicação, o site continua servindo a versão antiga. Guarde essa regra, ela aparece em todos os passos abaixo.
Este guia segue a documentação oficial do Plesk. A Napoleon não fez medição própria para ele. Os nomes de pasta e de arquivo usados como exemplo estão marcados como exemplo.
Faça backup e confira o que precisa existir na pasta antes de publicar
Publicar a aplicação muda a forma como o domínio responde. Se hoje existe um site WordPress ou uma página estática no mesmo domínio, ela deixa de ser servida quando o Node.js é ativado. Faça backup antes:
- No Plesk, entre em Sites e Domínios, clique no domínio e procure Backup Manager (Gerenciador de Backup). Gere um backup do site.
- Se preferir testar sem risco, crie um subdomínio (por exemplo
app.seudominio.com.br) e publique lá primeiro.
Depois, confira se a pasta da aplicação tem o mínimo que o painel espera:
| Item | Para que serve | Exemplo (fictício) |
|---|---|---|
package.json |
Lista as dependências que o painel vai instalar | /httpdocs/minha-app/package.json |
| Arquivo de entrada | O arquivo que o Node executa primeiro | app.js |
| Pasta pública | Arquivos estáticos (imagens, CSS) servidos direto pelo servidor web | /httpdocs/minha-app/public |
node_modules |
Não envie. O painel cria ao instalar as dependências | gerada pelo painel |
Envie os arquivos pelo Gerenciador de Arquivos do Plesk ou por FTP. Não envie a pasta node_modules do seu computador: ela pode conter módulos compilados para outro sistema operacional e quebrar no servidor.
Como publicar pelo painel em cinco passos
Como habilitar o suporte a Node.js no servidor
Este passo exige acesso de administrador do servidor. Se você está em uma hospedagem compartilhada e não vê o botão Node.js no domínio, peça ao suporte da hospedagem para habilitar o componente.
Com acesso de administrador:
- Entre em Ferramentas e Configurações.
- Em Atualizações do Plesk, clique em Adicionar/Remover Componentes.
- Procure o grupo de hospedagem web e marque Suporte a Node.js.
- Conclua a instalação e volte ao painel.
Ao terminar, o botão Node.js passa a aparecer na página de cada domínio, em Sites e Domínios.
Como escolher a versão do Node.js no domínio
- Em Sites e Domínios, clique no domínio.
- Clique em Node.js.
- No campo Versão do Node.js, escolha a versão que o seu projeto pede.
Para saber qual versão escolher, abra o package.json e procure o campo engines, se existir. Se não existir, use a mesma versão principal com que você desenvolveu. Trocar de versão depois é possível, mas exige reinstalar as dependências (passo 4) e reiniciar (passo 5).
Como apontar a raiz, a pasta pública e o arquivo de entrada
Na mesma tela há três campos que precisam concordar entre si:
- Raiz do aplicativo (Application Root): a pasta onde está o
package.json. Exemplo:/httpdocs/minha-app. - Raiz do documento (Document Root): a pasta pública, que precisa ficar dentro da raiz do aplicativo. Exemplo:
/httpdocs/minha-app/public. - Arquivo de inicialização do aplicativo (Application Startup File): o nome do arquivo de entrada, relativo à raiz do aplicativo. O padrão é
app.js. Se o seu projeto começa porserver.jsouindex.js, troque aqui.
Depois de preencher, clique em Ativar Node.js (Enable Node.js).
Uma prática comum em projetos Node é ler a porta de uma variável de ambiente e usar uma porta local só quando o código roda no seu computador. Assim o mesmo arquivo funciona nos dois lugares:
// exemplo: final do app.js
const porta = process.env.PORT || 3000;
app.listen(porta);
Como instalar as dependências pelo painel
Na tela do Node.js, clique em NPM install. O painel lê o package.json da raiz do aplicativo e cria a pasta node_modules no servidor. Se o seu projeto usa Yarn, o campo Gerenciador de pacotes permite escolher.
Quando o projeto tem uma etapa de build (comum em frameworks), use o botão Executar script (Run script) e digite o nome do script definido no package.json, por exemplo build.
O resultado aparece numa janela. Leia até o fim: um erro de instalação no meio da lista é a causa mais comum de a aplicação não subir depois.
Quando reiniciar a aplicação após uma alteração
Clique em Reiniciar aplicativo (Restart App). Faça isso sempre que:
- enviar ou editar qualquer arquivo de código;
- trocar a versão do Node.js;
- rodar o NPM install de novo;
- mudar variáveis de ambiente ou o modo da aplicação.
Abra o domínio no navegador. Se a página carregar, a publicação terminou.
Onde cadastrar variáveis e qual modo deixar no ar
Senhas de banco, chaves de API e URLs externas não devem ficar escritas no código. Na tela do Node.js, use Variáveis de ambiente personalizadas para cadastrá-las. No código, elas são lidas com process.env.NOME_DA_VARIAVEL.
O campo Modo do aplicativo tem duas opções:
| Modo | O que muda | Quando usar |
|---|---|---|
| production | Erros não são mostrados ao visitante | Site no ar |
| development | O erro detalhado aparece no navegador | Só durante o diagnóstico |
Deixar development ligado com o site público expõe caminhos de pasta e trechos de código para qualquer visitante. Use para encontrar o erro, depois volte para production e reinicie.
O que fazer quando a aplicação sobe mas devolve erro
Aqui há dois problemas diferentes. Se o domínio nem responde, o problema costuma estar no servidor web e o log de erro geral do site é o lugar certo. Se a aplicação inicia e responde com erro 500 ou uma página em branco, o erro está no seu código Node, e o log que interessa é o da própria aplicação.
O caminho mais rápido, sem acesso ao servidor:
- Mude o Modo do aplicativo para
development. - Clique em Reiniciar aplicativo.
- Abra a página com problema. O erro com o arquivo e a linha aparece no navegador.
- Corrija, volte para
productione reinicie.
Para erros que acontecem de vez em quando, ou que você não consegue reproduzir, faça a aplicação gravar o próprio log dentro da pasta dela. Um exemplo mínimo, no início do arquivo de entrada:
// exemplo: grava erros não tratados em app-erros.log
const fs = require('fs');
process.on('uncaughtException', (err) => {
fs.appendFileSync(__dirname + '/app-erros.log',
new Date().toISOString() + ' ' + err.stack + '\n');
process.exit(1);
});
Linha a linha: a primeira carrega o módulo de arquivos do Node; a segunda registra uma função que roda quando um erro não é tratado; a terceira acrescenta data e pilha do erro ao arquivo app-erros.log, na mesma pasta do código; a última encerra o processo, para que ele seja iniciado de novo limpo. Depois de reiniciar, abra o arquivo pelo Gerenciador de Arquivos do Plesk. Não coloque esse arquivo dentro da pasta pública, ou ele fica acessível pela URL.
O que cada erro frequente indica e como corrigir
| Sintoma | Causa provável | O que fazer |
|---|---|---|
Cannot find module |
Dependência não instalada ou instalada em outra versão do Node | Rode NPM install de novo e reinicie |
| Alteração não aparece no site | Aplicação não foi reiniciada | Clique em Reiniciar aplicativo |
| Página padrão do Plesk no lugar da app | Node.js não ativado ou raiz do documento errada | Confira os campos do passo 3 e ative |
| Arquivos estáticos dão 404 | Raiz do documento fora da pasta public real |
Aponte a raiz do documento para a pasta pública |
| App sobe e cai | Erro na inicialização ou variável de ambiente ausente | Use o modo development e o log da aplicação |
Como desfazer se algo der errado
Na tela do Node.js do domínio, clique em Desativar Node.js (Disable Node.js). O domínio volta a servir os arquivos da raiz do documento como site comum. Se você mudou a raiz do documento do domínio no processo, confira em Configurações de Hospedagem se ela voltou ao valor anterior, normalmente httpdocs. Se o site antigo foi sobrescrito, restaure pelo Backup Manager o backup feito antes de começar.
Os nomes de menus podem variar entre versões e traduções do painel. Quando um rótulo não bater, a documentação oficial do Plesk Obsidian é a referência.
Referências
- Documentação oficial (plesk) — Plesk Obsidian Administrator Guide. Consultado em 2026-11-14.