Mettre à jour Node.js en production sans casser les autres applications

Une mise à jour de runtime n'est pas une simple commande système

Sur un VPS qui héberge plusieurs applications, remplacer le binaire node global peut produire une panne en cascade. Un service ancien peut dépendre d'une version précise, un gestionnaire de processus peut conserver un chemin obsolète et une application Next.js peut avoir été compilée avec un runtime différent de celui utilisé au démarrage. La politique officielle des versions Node.js recommande d'ailleurs de réserver la production aux lignes Active LTS ou Maintenance LTS.

La méthode la plus sûre consiste à traiter Node.js comme une dépendance de chaque application. On installe une nouvelle version dans un répertoire dédié, on reconstruit uniquement le projet concerné, puis on modifie son service systemd. Les autres applications continuent d'utiliser leur runtime actuel.

Cartographier l'existant avant de modifier quoi que ce soit

Une mise à jour maîtrisée commence par un inventaire. Pour chaque service Node.js, relevez :

• le fichier d'unité systemd et son utilisateur d'exécution
• le chemin absolu du binaire Node.js réellement lancé
• le répertoire de travail, le port et les variables d'environnement
• la version utilisée au build et au runtime
• l'URL de santé ou, à défaut, une page représentative

Les commandes suivantes sont en lecture seule :

systemctl list-units --type=service --state=running
systemctl cat mon-application.service
systemctl show mon-application.service \
  -p ExecStart -p Environment -p EnvironmentFiles -p WorkingDirectory
readlink -f /proc/$(systemctl show -p MainPID --value mon-application.service)/exe

Cette dernière vérification est importante. node --version dans une session SSH décrit le shell courant, pas nécessairement le processus lancé par systemd. Un service peut très bien utiliser /opt/node-v22.23.1-linux-x64/bin/node alors que l'administrateur obtient une autre version dans son terminal.

Pour comprendre le rôle du runtime dans la pile, consultez aussi Node.js côté serveur. L'objectif n'est pas seulement de changer une version, mais de conserver une architecture explicite et maintenable.

Installer un runtime isolé et vérifié

Prenons Node.js v22.23.1 comme exemple concret pour un projet qui impose Node.js 22. Cette version, publiée le 22 juin 2026, appartient à la ligne LTS « Jod ». L'archive Linux x64 officielle possède le SHA-256 suivant :

9749e988f437343b7fa832c69ded82a312e41a03116d766797ac14f6f9eee578

Après téléchargement depuis nodejs.org, vérifiez l'archive avant de l'extraire :

printf '%s  %s\n' \
  '9749e988f437343b7fa832c69ded82a312e41a03116d766797ac14f6f9eee578' \
  'node-v22.23.1-linux-x64.tar.xz' | sha256sum --check

sudo tar -xJf node-v22.23.1-linux-x64.tar.xz -C /opt
/opt/node-v22.23.1-linux-x64/bin/node --version
/opt/node-v22.23.1-linux-x64/bin/npm --version

Un répertoire versionné sous /opt présente deux avantages : le chemin utilisé par systemd ne change pas sans action explicite et le retour arrière ne dépend pas d'une réinstallation réseau. Évitez de faire pointer immédiatement un lien symbolique partagé comme /opt/node-current vers la nouvelle version. Ce lien recréerait un couplage entre les applications si plusieurs services l'utilisent.

Valider la compatibilité au niveau du projet

Le champ engines de package.json documente la plage attendue :

{
  "engines": {
    "node": ">=22 <23"
  }
}

npm peut signaler une incompatibilité sans nécessairement interrompre l'installation. Ce champ est donc un garde-fou documentaire, pas une preuve suffisante. La validation réelle doit utiliser le nouveau binaire :

export PATH="/opt/node-v22.23.1-linux-x64/bin:$PATH"
node --version
npm ci
npm run lint
npm test
npm run build

Les dépendances contenant du code natif méritent une attention particulière. Elles peuvent devoir être recompilées pour l'ABI du nouveau runtime. C'est une raison de préférer npm ci dans une release propre plutôt que de réutiliser un ancien répertoire node_modules.

Cette discipline rejoint les principes détaillés dans Architecture web durable : livrer vite sans dette : une livraison reproductible réduit le nombre de variables changées en même temps.

Distinguer compatibilité déclarée et compatibilité démontrée

Une plage de versions dans package.json exprime l'intention des mainteneurs, mais elle ne couvre pas votre combinaison exacte de dépendances, de configuration et de données. À l'inverse, un avertissement npm ne signifie pas nécessairement que l'application est inutilisable. La décision doit reposer sur les résultats du projet : installation déterministe, analyse statique, tests, compilation puis démarrage réel de l'artefact.

Conservez ces résultats avec la version exacte de Node.js, npm et du lockfile. Si une anomalie apparaît après la mise en production, cette trace permet de savoir ce qui a réellement été qualifié. Elle évite aussi qu'un second déploiement reconstruise implicitement avec une autre version mineure et rende le diagnostic confus.

Les modules natifs, les outils de génération et les bibliothèques qui lancent des sous-processus sont les candidats prioritaires pour un test ciblé. Vérifiez leurs notes de version lorsque vous franchissez une version majeure de Node.js. Pour une mise à jour mineure au sein d'une même ligne LTS, gardez malgré tout la même chaîne de validation : le coût est faible une fois automatisé et le résultat reste comparable d'une intervention à l'autre.

Cas Next.js : construire un artefact autonome

Avec output: "standalone", Next.js produit .next/standalone et un serveur minimal server.js. Ce mode limite la quantité de dépendances transférées en production. Il ne copie cependant pas automatiquement public ni .next/static.

Une préparation courante ressemble à ceci :

npm run build
cp -a public .next/standalone/
mkdir -p .next/standalone/.next
cp -a .next/static .next/standalone/.next/

Le service doit ensuite lancer le serveur généré avec le runtime ciblé :

[Service]
User=mon-application
WorkingDirectory=/var/www/mon-application/current
EnvironmentFile=/etc/mon-application.env
ExecStart=/opt/node-v22.23.1-linux-x64/bin/node .next/standalone/server.js
Restart=on-failure
RestartSec=5

Utiliser un chemin absolu évite qu'une modification du PATH système affecte le prochain redémarrage. L'unité ne doit contenir ni secret ni jeton. Ceux-ci restent dans un fichier d'environnement lisible uniquement par le compte approprié.

Basculer un seul service

Avant la modification, sauvegardez l'unité et notez la release active. Préparez la nouvelle release dans un autre répertoire, testez-la sur un port temporaire lié à 127.0.0.1, puis changez uniquement le service concerné.

sudo systemd-analyze verify /etc/systemd/system/mon-application.service
sudo systemctl daemon-reload
sudo systemctl restart mon-application.service
sudo systemctl status mon-application.service --no-pager
sudo journalctl -u mon-application.service --since '-5 minutes' --no-pager

Ne redémarrez pas tous les services « par précaution ». Cela élargit inutilement l'incident potentiel et efface la preuve que les autres applications étaient stables pendant l'opération.

Pour industrialiser ce type de livraison, DevPush et le déploiement continu présente les contrôles utiles autour d'un pipeline. L'automatisation reste bénéfique lorsqu'elle conserve une cible étroite et un retour arrière explicite.

Contrôler après la bascule

Un processus actif n'est pas encore une application saine. Vérifiez successivement :

1. Le processus : PID stable, absence de boucle de redémarrage et bon chemin dans /proc.
2. Le port local : réponse HTTP sur 127.0.0.1 avec le code attendu.
3. Le reverse proxy : réponse via le domaine public, certificat TLS valide et absence de 502.
4. Le fonctionnel : page principale, ressource statique, action métier en lecture et, si possible, test synthétique.
5. Les voisins : état systemd et URL de santé des autres applications du VPS.
6. Les ressources : mémoire, CPU, espace disque et journaux pendant quelques minutes.

Comparez ces mesures à l'état relevé avant l'intervention. Sans référence, une hausse de mémoire ou une latence inhabituelle peut passer inaperçue.

Observer assez longtemps pour détecter les défauts différés

Tous les problèmes ne se manifestent pas au premier appel HTTP. Une tâche planifiée peut charger un module rarement utilisé, un traitement d'image peut solliciter une dépendance native et une connexion longue peut révéler un changement de comportement sous charge. Gardez donc les journaux et les métriques sous surveillance pendant une fenêtre représentative du trafic.

Le contrôle doit rester proportionné au service. Pour un site vitrine, quelques parcours synthétiques, le taux d'erreur et la consommation mémoire peuvent suffire. Pour une application métier, ajoutez les files de travaux, les tâches cron, les connexions à la base et les intégrations externes. Surveillez aussi la tendance, pas uniquement une valeur instantanée : une mémoire qui progresse lentement après chaque requête est plus inquiétante qu'un pic bref et expliqué au démarrage.

L'article Monitoring applicatif avec Sentry et OpenTelemetry détaille les signaux utiles pour transformer cette période d'observation en validation mesurable.

Préparer un retour arrière réellement exécutable

Le rollback doit être possible sans reconstruire dans l'urgence. Conservez :

• l'ancienne release complète
• l'ancien runtime sous son chemin versionné
• une copie de l'unité systemd précédente
• les commandes exactes de restauration

Si le nouveau service échoue, restaurez l'ancien ExecStart ou le lien current, rechargez systemd, redémarrez uniquement l'application et répétez les contrôles. Ne supprimez l'ancien runtime qu'après une période d'observation adaptée au trafic et après avoir confirmé qu'aucun autre service ne le référence.

La stratégie en une phrase

Une mise à jour Node.js sûre sur un VPS partagé ne remplace pas « Node.js sur le serveur ». Elle installe un runtime supplémentaire, qualifie un artefact avec ce runtime, puis migre une application à la fois avec des preuves avant, pendant et après la bascule.

Sources

• Node.js, calendrier et statut des versions
• Node.js v22.23.1, sommes de contrôle officielles
• Next.js, configuration output: "standalone"
• npm, champ engines de package.json
• systemd, documentation des unités de service

La meilleure mise à jour est celle dont les autres applications ne remarquent jamais le passage.