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

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

João Rizzon · 2026-11-15 · Painéis

---

## 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](https://docs.plesk.com/en-US/obsidian/administrator-guide_sitemap.xml) 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 por `server.js` ou `index.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:

```javascript
// 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 `production` e 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:

```javascript
// 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](https://docs.plesk.com/en-US/obsidian/administrator-guide_sitemap.xml) é a referência.

