---
title: "Comment déployer une application Node.js sur Plesk ?"
description: "Déployez votre application Node.js ou Next.js sur votre hébergement web Plesk Winheberg, configuration automatique, protection des sources, version LTS, dépendances, build, variables et secrets."
category: cloud
subcategory: hebergement-web
icon: tabler:brand-nodejs
date: 2026-11-01
author: Winheberg
slug: "deployer-application-nodejs-plesk"
order: 91
image: /statics/images/docs/fr/hebergement-web/deployer-application-nodejs-plesk.webp
tags: [Node.js, Plesk, Hébergement Web, Next.js, Déploiement]
keywords: [déployer node.js plesk, hébergement node.js, next.js plesk, passenger plesk, node.js lts, variables d'environnement plesk]
link_en: "/en/docs/hebergement-web/deploy-nodejs-application-plesk"
---

## Contexte

L'[hébergement web Winheberg](https://winheberg.com/cloud/hebergement-web) fonctionne sous Plesk et prend en charge les applications Node.js, qu'il s'agisse d'une API, d'un backend ou d'un projet Next.js. Le déploiement diffère de celui d'un site PHP classique, car l'application tourne dans son propre processus géré par Phusion Passenger, et non comme un ensemble de fichiers servis directement par le serveur web.

Dès que vos fichiers sont en place, Plesk lit votre `package.json`, reconnaît le type d'application et propose une configuration automatique. Elle génère le fichier de démarrage attendu par Passenger et vous montre la liste des changements avant de les appliquer.

Ce guide suit ce parcours automatique, puis détaille la configuration manuelle pour les cas où la détection n'aboutit pas.

## Prérequis

- Un hébergement web Winheberg actif
- Un accès à votre interface Plesk
- Les sources de votre application, avec son fichier `package.json`
- Un domaine ou sous-domaine déjà rattaché à l'hébergement, par exemple en suivant notre guide [Comment relier un domaine externe à votre hébergement Plesk ?](https://winheberg.com/docs/hebergement-web/relier-domaine-externe-plesk)

> [!NOTE]
> L'accès SSH n'est pas disponible sur les hébergements web. Toutes les opérations décrites ici se font depuis l'interface Plesk, y compris les commandes npm.

## 1. Tester le projet en local

Avant tout envoi, vérifiez que votre application se construit et démarre sur votre machine.

```bash
npm install
npm run build
npm run start
```

Si l'une de ces commandes échoue en local, elle échouera également sur le serveur. Corrigez avant de continuer, le diagnostic est bien plus simple sur votre poste. Si votre projet n'a pas d'étape de build, seules la première et la dernière commande vous concernent.

## 2. Envoyer les fichiers de l'application

Compressez vos sources dans une archive `.zip`, **sans** les dossiers `node_modules` et `.next`. Ces dossiers seront régénérés sur le serveur, et leur envoi provoque des incompatibilités de plateforme en plus d'un transfert inutilement long.

Ouvrez **Fichiers** dans le menu latéral, placez-vous dans `httpdocs`, cliquez sur **+** puis **Téléverser le fichier**. Une fois l'archive envoyée, sélectionnez-la et extrayez-la sur place depuis le menu **Archive**.

<img src="/statics/images/docs/fr/hebergement-web/deployer-application-nodejs-plesk-1793567752517-d3b915bdb70876652230ae4f.webp" alt="Menu Téléverser le fichier du gestionnaire de fichiers Plesk dans httpdocs" width="786" />

Vérifiez qu'à la fin de l'extraction, le fichier `package.json` se trouve bien directement dans `httpdocs` et non dans un sous-dossier intermédiaire.

> [!IMPORTANT]
> L'ordre de ces étapes compte. Plesk ne détecte le type d'application et ne propose la configuration automatique que si `package.json` est déjà en place. Sur un domaine vide, vous devrez tout renseigner à la main.

## 3. Lancer la configuration automatique

Depuis **Sites Web & Domaines**, ouvrez votre domaine, l'onglet **Démarrer**, puis **Node.js**. Plesk affiche le **Type d'application** détecté depuis `package.json` et le bouton **Configurer automatiquement**.

<img src="/statics/images/docs/fr/hebergement-web/deployer-application-nodejs-plesk-1793567752868-6ed0f9bf397ff93272281a22.webp" alt="Type d'application détecté et bouton Configurer automatiquement dans Node.js" width="640" />

Cliquez sur **Configurer automatiquement**. Plesk liste ce qu'il va modifier avant de rien appliquer, par exemple la création du fichier de démarrage `.plesk.startup.cjs` qui charge votre point d'entrée, et la mise de côté d'un `index.html` statique qui serait servi à la place de votre application.

<img src="/statics/images/docs/fr/hebergement-web/deployer-application-nodejs-plesk-1793567753248-16d579d3767720561053c8f5.webp" alt="Fenêtre Configurer automatiquement l'hébergement avec le bouton Appliquer et redémarrer" width="766" />

Relisez cette liste, puis cliquez sur **Appliquer et redémarrer**. Le fichier `index.html` d'origine est conservé sous le nom `index.html.autoconfig-bak`.

> [!TIP]
> Inutile de changer le port écrit dans votre code. Passenger intercepte l'appel `listen()` de votre application et la branche sur son propre canal, quel que soit le port indiqué. Le fichier `.plesk.startup.cjs` le précise en commentaire, ne le modifiez pas et ne le supprimez pas.

## 4. Protéger vos fichiers source

Avec la configuration automatique, la **Racine du document** reste souvent la même que la **Root d'application**, c'est-à-dire `/httpdocs`. Le serveur web sert alors directement tout fichier présent dans ce dossier, y compris `package.json` et le code de votre application, que n'importe qui peut télécharger en connaissant son nom.

Plesk le rappelle d'ailleurs sur le tableau de bord tant que Node.js n'est pas activé, il recommande de définir la racine du document dans un sous-répertoire de la racine de l'application, par exemple `public/`.

Créez un dossier `public` dans `httpdocs` depuis le gestionnaire de fichiers. Sur le tableau de bord Node.js, cliquez ensuite sur l'icône de dossier à côté de **Racine du document**, sélectionnez `public` sous `httpdocs` dans l'arborescence, puis **Enregistrer**. Placez dans ce dossier uniquement les fichiers destinés à être servis tels quels, comme les images ou les feuilles de style.

> [!CAUTION]
> N'écrivez jamais un mot de passe ou une clé d'API en dur dans votre code. Utilisez les **Secrets** de l'onglet **Environnement**, décrits à l'étape 8.

## 5. Vérifier la version et le mode d'application

Une fois la configuration appliquée, le tableau de bord affiche les boutons **Redémarrer l'app**, **Arrêter l'app** et **Désactiver Node.js**. Si le bouton **Activer Node.js** est encore présent, cliquez dessus.

Cliquez ensuite sur le crayon à côté de **Version de Node.js**, choisissez la version que réclame votre projet, puis **Enregistrer**. Contrôlez au passage que **Mode d'application** est bien sur `production`, c'est ce réglage qui fixe les variables `NODE_ENV` et `PASSENGER_APP_ENV` de votre application.

<img src="/statics/images/docs/fr/hebergement-web/deployer-application-nodejs-plesk-1793567753972-c29a08e8073c740be466999a.webp" alt="Sélecteur de version de Node.js et mode d'application production" width="640" />

### Quelle version choisir

Les versions proposées ne se valent pas. Une version LTS reçoit des correctifs de sécurité pendant plusieurs années, alors que les versions impaires comme 23.x ou 21.x ne sont jamais passées en LTS et ne sont plus maintenues.

::MdTable{caption="Versions de Node.js proposées par Plesk, statut au 1er novembre 2026" variant="info" striped footer="Dates issues du calendrier officiel de publication de Node.js."}
| Version | Statut | Fin de support |
|---|---|---|
| 26.x | LTS actif depuis le 28 octobre 2026 | 30 avril 2029 |
| 24.x | LTS en maintenance depuis le 20 octobre 2026 | 30 avril 2028 |
| 23.x | Plus maintenue | 1er juin 2025 |
| 22.x | LTS en maintenance | 30 avril 2027 |
| 21.x | Plus maintenue | 1er juin 2024 |
| 20.x | Plus maintenue | 30 avril 2026 |
| 18.x | Plus maintenue | 30 avril 2025 |
::

Retenez une version **26.x** pour un nouveau projet, c'est la branche LTS active. Gardez **24.x** si l'une de vos dépendances n'est pas encore compatible, elle reste corrigée jusqu'en avril 2028.

> [!WARNING]
> Les branches 23.x, 21.x, 20.x et 18.x ne reçoivent plus de correctifs de sécurité. Évitez-les pour une application exposée sur Internet, même si votre code fonctionne avec.

Une version trop ancienne fait par ailleurs échouer le build de la plupart des frameworks récents, avec un message qui ne mentionne pas toujours la version en cause. Next.js 16 réclame par exemple Node.js 20.9 au minimum.

## 6. Installer les dépendances

Cliquez sur **Installer NPM**, ou ouvrez l'onglet **Exécuter les commandes Node.js** et choisissez **install** dans la liste. Plesk lit votre `package.json` et reconstruit le dossier `node_modules` sur le serveur.

<img src="/statics/images/docs/fr/hebergement-web/deployer-application-nodejs-plesk-1793567754418-32ecb747ef8491fc0880d61a.webp" alt="Onglet Exécuter les commandes Node.js avec la liste des scripts et commandes npm" width="780" />

La **Sortie de la commande** affiche le résultat. Attendez la fin de l'opération avant de passer à la suite, sur un projet volumineux l'installation prend plusieurs minutes.

<img src="/statics/images/docs/fr/hebergement-web/deployer-application-nodejs-plesk-1793567754802-86b937346ee765d47b410cd2.webp" alt="Sortie de la commande npm install dans Plesk" width="770" />

> [!NOTE]
> Plesk prend aussi en charge Yarn et pnpm. Cliquez sur le crayon à côté de **Gestionnaire de packages** sur le tableau de bord pour choisir `npm`, `yarn` ou `pnpm`.

## 7. Lancer le build

Cliquez sur **Démarrer le script**. Plesk ouvre l'onglet **Exécuter les commandes Node.js**, dont la liste **Scripts du package.json** reprend les scripts de votre projet. Choisissez `run build`.

Pour un projet Next.js, cette étape génère le dossier `.next`, celui que vous n'avez volontairement pas envoyé. Construire sur le serveur plutôt que d'envoyer un build fait sur votre machine évite les incompatibilités d'architecture.

> [!WARNING]
> Pour Next.js, cette étape est obligatoire. Démarrer l'application sans build produit l'erreur `Could not find a production build in the '.next' directory`.

## 8. Déclarer les variables d'environnement

Ouvrez l'onglet **Environnement**. Il distingue deux types de valeurs transmises à votre application.

<img src="/statics/images/docs/fr/hebergement-web/deployer-application-nodejs-plesk-1793567755282-9f3f0e61172ea6ed55e5df5d.webp" alt="Onglet Environnement de Node.js avec les variables d'environnement et les secrets" width="786" />

::MdTable{caption="Variables de l'onglet Environnement" variant="info" striped}
| Section | Usage |
|---|---|
| Variables d'environnement | Les réglages sans caractère sensible, visibles par toute personne qui ouvre cette page |
| Secrets | Les mots de passe, clés d'API et jetons, stockés chiffrés et en écriture seule, leur valeur n'est plus jamais affichée après l'enregistrement |
| Variables prédéfinies | `NODE_ENV`, `PASSENGER_APP_ENV`, `NODE_PATH` et `IN_PASSENGER`, définies par Passenger, une variable du même nom déclarée plus haut prend le dessus |
::

Ajoutez vos valeurs avec **Ajouter un champ**, cliquez sur **Enregistrer**, puis sur **Redémarrer l'app** depuis le tableau de bord pour que l'application les prenne en compte.

> [!IMPORTANT]
> Avec Next.js, les variables préfixées `NEXT_PUBLIC_` sont intégrées au code au moment du build. Placez-les dans un fichier `.env.production` à la racine de l'application avant de lancer l'étape 7, et réservez-y uniquement des valeurs que vous acceptez de rendre publiques.

## 9. Démarrer l'application

Cliquez sur **Redémarrer l'app**, puis ouvrez votre domaine dans un navigateur. Tant que personne ne l'a visitée, le **Statut** indique **Inactif**, l'application démarre à la première requête. Il passe ensuite à **En cours d'exécution**, avec le nombre de processus et l'heure de démarrage.

<img src="/statics/images/docs/fr/hebergement-web/deployer-application-nodejs-plesk-1793567753630-3a3796035b299634b19315e3.webp" alt="Tableau de bord Node.js actif avec les boutons Redémarrer l'app, Installer NPM et Démarrer le script" width="786" />

## Configurer manuellement

Si votre `package.json` n'était pas en place au moment de l'activation, ou si la détection n'a pas reconnu votre projet, renseignez les champs vous-même depuis le tableau de bord Node.js.

::MdTable{caption="Champs à renseigner" variant="info" striped}
| Champ | Valeur | Rôle |
|---|---|---|
| **Root d'application** | `/httpdocs` | Le dossier qui contient le `package.json` |
| **Racine du document** | `/httpdocs/public` | Le dossier des fichiers servis tels quels, distinct de vos sources |
| **Fichier de démarrage d'application** | Le fichier que Passenger exécute, `app.js` par défaut | Le point d'entrée de votre application |
::

Passenger démarre un fichier JavaScript, il ne lance pas `npm start`. Lorsqu'une application se lance habituellement par une commande npm, ouvrez le `package.json` et repérez le fichier passé à `node`, c'est celui-là qu'il faut déclarer. Pour une application Express ou tout code Node.js écrit à la main, ce fichier existe déjà, souvent `app.js`, `server.js` ou `index.js`.

Pour Next.js, il n'existe pas. La commande `next start` appelle un binaire du framework et non un fichier de votre projet. Créez donc un fichier `start.js` à la racine de votre application, avec ce contenu.

```javascript
process.env.NODE_ENV = 'production';

const app = require('next/dist/cli/next-start');

app.nextStart({
  port: process.env.PORT || 3000,
});
```

Déclarez ensuite `start.js` dans **Fichier de démarrage d'application**, puis cliquez sur **Redémarrer l'app**.

> [!WARNING]
> Si votre `package.json` contient `"type": "module"`, l'instruction `require` ci-dessus échoue. Nommez alors votre fichier `start.cjs` au lieu de `start.js`, l'extension `.cjs` force l'interprétation en CommonJS, puis déclarez ce nom dans le champ du fichier de démarrage.

## En cas de problème

### ❌ Could not find a production build in the '.next' directory

Le build n'a pas été exécuté, ou il a échoué sans que vous l'ayez remarqué.

- Relancez `run build` depuis **Démarrer le script** et lisez la **Sortie de la commande** jusqu'au bout
- Vérifiez que le dossier `.next` existe dans la racine de l'application
- Contrôlez que **Root d'application** pointe bien sur le dossier contenant le `package.json`

### ❌ require() of ES Module is not supported

Votre projet est déclaré en module ES, ce qui rend l'instruction `require` inutilisable dans un fichier de démarrage en `.js`.

- Renommez votre fichier de démarrage avec l'extension `.cjs`
- Reportez ce nouveau nom dans **Fichier de démarrage d'application**
- Redémarrez l'application avec **Redémarrer l'app**

### ❌ The application process exited prematurely

Le processus n'a pas réussi à démarrer.

- Vérifiez que le fichier de démarrage existe réellement à la racine de l'application
- Assurez-vous que les dépendances ont bien été installées, la **Sortie de la commande** de `install` ne doit afficher aucune erreur
- Recherchez une variable d'environnement ou un secret manquant dans l'onglet **Environnement**
- Confirmez que **Mode d'application** est bien réglé sur `production`

### ❌ Vos fichiers source s'affichent dans le navigateur

La **Racine du document** est la même que la **Root d'application**, le serveur web sert donc vos sources directement.

- Créez un dossier `public` dans la racine de l'application
- Définissez `/httpdocs/public` comme **Racine du document** depuis le tableau de bord Node.js
- Redémarrez l'application, puis ouvrez votre site en ajoutant `/package.json` à la fin de son adresse, le fichier ne doit plus s'afficher

## Bonnes pratiques

- Envoyez vos fichiers avant d'ouvrir la page Node.js, c'est ce qui permet la détection et la configuration automatique
- Validez toujours `npm run build` en local avant d'envoyer quoi que ce soit
- Gardez `node_modules` et `.next` hors de vos envois, ils se régénèrent côté serveur
- Relancez le build puis **Redémarrer l'app** après chaque mise à jour de votre code
- Restez sur une version LTS de Node.js et changez de branche avant sa fin de support
- Rangez les mots de passe et clés d'API dans les **Secrets**, jamais dans le code ni dans un fichier servi par le site
- Si vous changez de framework, relancez **Configurer automatiquement** pour que Plesk régénère le fichier de démarrage
- Servez votre application en HTTPS avec le certificat gratuit décrit dans notre guide [Comment générer un certificat SSL Let's Encrypt pour votre site web ?](https://winheberg.com/docs/hebergement-web/certificat-ssl-lets-encrypt-plesk)
- Pour confier le déploiement à un développeur sans lui ouvrir tout votre compte, créez-lui un accès dédié avec notre guide [Comment créer un utilisateur dans Plesk ?](https://winheberg.com/docs/hebergement-web/creer-utilisateur-plesk)

## Besoin d'aide ?

Si votre application ne démarre toujours pas après ces vérifications, ouvrez un ticket auprès de notre support depuis votre [espace client](https://billing.winheberg.com), département **Technique**, en renseignant le champ **Produit lié** avec l'hébergement concerné.

Joignez le message d'erreur complet ainsi que la sortie du build. Notre équipe peut également consulter le journal de Passenger côté serveur, qui contient souvent la cause exacte d'un démarrage avorté.

Votre application est en ligne 🚀

