IT

Hosting web

Esegui il deploy di un'applicazione Node.js su Plesk

Pubblica un'applicazione Node.js da Plesk: struttura delle cartelle, file di avvio, dipendenze npm, variabili di ambiente, registri e risoluzione degli errori più comuni.

8 min di lettura, aggiornato il 18 novembre 2026

In questa pagina

I tuoi valori

Inseriscili una volta: i comandi della guida si aggiornano.

Questa guida spiega come pubblicare un'applicazione Node.js sul tuo dominio da Plesk, installarne le dipendenze, configurarla e verificare che risponda correttamente.

Prerequisiti

Questa guida usa httpdocs, la cartella abituale del dominio principale. Per un dominio aggiuntivo la cartella può essere diversa: controlla la Root del documento in Hosting e DNS > Hosting.

Come funziona

Su Plesk per Linux, la tua applicazione non viene avviata con npm start né con un gestore di processi come PM2. È l'application server Phusion Passenger ad avviare il file indicato in Plesk e a passargli le richieste ricevute dal server web.

Questo comporta tre conseguenze pratiche:

  • La porta viene gestita per te. Passenger ignora il numero passato a listen() e collega autonomamente il tuo server HTTP. Non devi aprire alcuna porta né aggiungerla all'indirizzo del sito.
  • Il file di avvio deve chiamare listen(), direttamente o caricando il file che lo fa.
  • Il processo può arrestarsi in caso di inattività e riavviarsi alla richiesta successiva. Non affidare quindi un'operazione ricorrente a un timer interno (setInterval): usa piuttosto le Attività pianificate di Plesk.

Occorre distinguere due cartelle:

Impostazione Plesk Ruolo Esempio
Directory principale applicazione (Application Root) Cartella che contiene l'intero progetto: package.json, codice, node_modules /httpdocs
Root del documento (Document Root) Sottocartella dei file pubblici, serviti direttamente dal server web /httpdocs/public

La root del documento deve trovarsi obbligatoriamente all'interno della cartella dell'applicazione. Solo il suo contenuto è accessibile direttamente dal web: i file .env, il codice e node_modules restano così fuori portata, a patto di non inserirli mai in public.

Passaggio 1: prepara l'applicazione

Ecco la struttura usata in questa guida:

Testo
httpdocs/
├── app.js
├── package.json
├── package-lock.json
└── public/
    └── logo.png

Se vuoi prima convalidare la configurazione, questo file app.js minimo non richiede alcuna dipendenza:

js
const http = require('node:http');

const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
  res.end('Applicazione Node.js online\n');
});

server.listen(process.env.PORT || 3000);

Con Express il principio non cambia:

js
const express = require('express');

const app = express();

app.get('/', (req, res) => {
  res.send('Applicazione Node.js online');
});

app.listen(process.env.PORT || 3000);

Mantenere process.env.PORT || 3000 consente allo stesso codice di funzionare anche sul tuo computer.

Controlla anche il file package.json: contiene l'elenco delle dipendenze, e gli script che eseguirai da Plesk devono comparire nella sezione scripts.

JSON
{
  "name": "mia-applicazione",
  "version": "1.0.0",
  "private": true,
  "main": "app.js",
  "scripts": {
    "build": "echo \"Nessuna compilazione necessaria\""
  },
  "dependencies": {
    "express": "^5.0.0"
  }
}

Passaggio 2: carica i file

Carica il progetto in httpdocs, senza la cartella node_modules: le dipendenze verranno installate sul server al passaggio 4.

Il metodo più semplice per un primo caricamento:

  1. Crea un archivio .zip del progetto sul tuo computer.
  2. In Plesk, apri File (il gestore di file), poi la cartella httpdocs.
  3. Carica l'archivio.
  4. Selezionalo, clicca su Estrai file, poi elimina l'archivio.
  5. Crea la cartella public se non esiste: Plesk ne ha bisogno come root del documento, anche se resta vuota.

Passaggio 3: configura Node.js in Plesk

  1. Vai su Siti web e domini e individua il tuo dominio.

  2. Clicca su Node.js. Se sul dominio non è ancora configurato un sito, passa da Crea sito web > Node.js.

  3. Compila le impostazioni:

    Impostazione Valore da indicare
    Versione di Node.js La versione richiesta dalla tua applicazione, o quella più vicina alla versione usata in sviluppo
    Gestione pacchetti npm o Yarn, in base al tuo progetto. In genere Plesk propone la scelta giusta
    Root del documento /httpdocs/public
    Modalità applicazione Produzione (production) quando il sito è pronto, Sviluppo (development) durante la messa a punto. Questo valore alimenta NODE_ENV
    Directory principale applicazione /httpdocs
    File di avvio applicazione app.js, o il file che avvia effettivamente il tuo server
  4. Conferma con OK se questo pulsante è presente.

Passaggio 4: attiva l'applicazione e installa le dipendenze

Sempre nella pagina Node.js del dominio:

  1. Clicca su Abilita Node.js.
  2. Clicca su Installa NPM (o Installa Yarn). Questo pulsante compare solo se package.json si trova nella cartella dell'applicazione.
  3. Se il tuo progetto deve essere compilato (TypeScript, front-end, ecc.), clicca su Esegui script, inserisci il nome dello script, ad esempio build, poi conferma.
  4. Clicca su Riavvia app per caricare l'ultima versione.

Passaggio 5: definisci le variabili di ambiente

Chiavi API, password e altre impostazioni sensibili non devono comparire nel codice.

  1. Nella pagina Node.js, individua Variabili di ambiente personalizzate.
  2. Clicca su specifica, poi su Aggiungi variabile.
  3. Inserisci il nome e il valore, ad esempio DATABASE_HOST e localhost.
  4. Conferma, poi clicca su Riavvia app.

Node.js non carica automaticamente un file .env. Se la tua applicazione ne usa uno, deve leggerlo da sé, ad esempio con il pacchetto dotenv.

Passaggio 6: verifica il risultato

Apri https://tuo-dominio.com/ nel browser. Con l'esempio di questa guida, la pagina mostra Applicazione Node.js online.

Puoi anche controllare la risposta dal tuo computer:

Terminale
curl -i https://tuo-dominio.com/

La prima riga deve indicare il codice 200. La prima richiesta può essere più lenta, il tempo necessario all'avvio dell'applicazione.

Per consultare i messaggi dell'applicazione, apri Registri dal tuo dominio, espandi Tutti i registri e lascia selezionata solo la voce Node.js.

Aggiorna l'applicazione

  1. Carica i file modificati.
  2. Se package.json è cambiato, clicca di nuovo su Installa NPM.
  3. Se necessario, esegui di nuovo lo script di compilazione.
  4. Clicca su Riavvia app.

Per automatizzare questi aggiornamenti, consulta Esegui il deploy da GitHub o GitLab con Plesk.

Risoluzione dei problemi

«Web application could not be started» o «We're sorry, but something went wrong»

L'applicazione si è bloccata all'avvio. Apri i Registri per leggere l'errore esatto, poi verifica:

  • che il File di avvio applicazione esista nella Directory principale applicazione;
  • che le dipendenze siano state installate;
  • che la versione di Node.js corrisponda a quella richiesta dal progetto;
  • che tutte le variabili di ambiente necessarie siano definite.

«The file does not exist» nella pagina Node.js

Plesk non trova il file di avvio. Controlla la Directory principale applicazione e il nome del file, rispettando maiuscole e minuscole.

Error: Cannot find module 'express'

Le dipendenze mancano. Clicca su Installa NPM, verifica che il modulo compaia in dependencies e non solo in devDependencies, poi riavvia l'applicazione.

ERR_REQUIRE_ESM o «require() of ES Module not supported»

Passenger carica il file di avvio con require(), operazione che può non riuscire quando il progetto usa i moduli ES ("type": "module" in package.json). Crea nella cartella dell'applicazione un piccolo file passenger.cjs:

js
import('./app.js').catch((error) => {
  console.error(error);
  process.exit(1);
});

Indica poi passenger.cjs come File di avvio applicazione e riavvia.

L'applicazione non si avvia e alla fine va in timeout

Probabilmente il file di avvio non chiama mai listen(). Succede spesso con i progetti creati da express-generator, in cui il server viene avviato da bin/www e non da app.js. Indica quindi il file corretto oppure sposta la chiamata a listen().

Errore relativo a più server HTTP

Passenger si collega al primo server che chiama listen() e segnala un errore se l'applicazione ne crea più di uno. Indica esplicitamente il server da usare:

js
if (typeof PhusionPassenger !== 'undefined') {
  PhusionPassenger.configure({ autoInstall: false });
}

const port = typeof PhusionPassenger !== 'undefined' ? 'passenger' : 3000;
server.listen(port);

Viene visualizzata la pagina predefinita di Plesk o un errore 403

Verifica che Node.js sia abilitato per questo dominio e che la Root del documento punti a /httpdocs/public. Un vecchio file index.html presente in questa cartella verrebbe servito al posto della tua applicazione: eliminalo o rinominalo.

Immagini o fogli di stile restituiscono un errore 404

I file statici devono trovarsi nella Root del documento. Un URL /logo.png corrisponde al file public/logo.png, senza public nell'indirizzo.

Le tue modifiche non vengono applicate

Node.js mantiene il codice in memoria. Clicca su Riavvia app dopo ogni caricamento di file o modifica di una variabile.

Installa NPM non riesce

Leggi il messaggio visualizzato: indica il pacchetto interessato. Verifica che la Versione di Node.js rispetti il campo engines delle tue dipendenze e che package-lock.json sia aggiornato. Se l'errore parla di memoria insufficiente o della compilazione di un modulo nativo, contatta il supporto dalla tua area clienti allegando il messaggio.