« Could not load the sharp module » : le binaire Linux n’a jamais été installé.

sharp affiche l’environnement d’exécution qu’il a cherché, puis une liste de pistes. Sur un serveur Linux x64, ça donne :

Error: Could not load the "sharp" module using the linux-x64 runtime
Possible solutions:
- Ensure optional dependencies can be installed:
    npm install --include=optional sharp
- Ensure your package manager supports multi-platform installation:
    See https://sharp.pixelplumbing.com/install#cross-platform
- Add platform-specific dependencies:
    npm install --os=linux --cpu=x64 sharp
- Consult the installation documentation:
    See https://sharp.pixelplumbing.com/install

Le paquet sharp lui-même ne contient aucun binaire précompilé. Ses optionalDependencies comptent un paquet par plateforme : @img/sharp-darwin-arm64, @img/sharp-win32-x64, @img/sharp-linux-x64, @img/sharp-libvips-linux-x64, etc. Chacun déclare le système et le processeur visés, et le gestionnaire de paquets n’installe que ceux qui correspondent à la machine qui fait l’installation.

L’installation sur le serveur doit donc trouver les entrées Linux dans votre fichier de verrouillage, et avoir le droit d’installer les dépendances facultatives. Si l’une des deux conditions manque, l’installation réussit quand même. L’erreur n’apparaît qu’au premier require('sharp') : pendant la compilation si elle traite des images, sinon dans les journaux de l’appli au premier redimensionnement.

C’est le correctif dans la plupart des cas avec npm. Les paquets Linux figurent dans package-lock.json sous node_modules/@img/sharp-linux-x64 et node_modules/@img/sharp-libvips-linux-x64. Si un npm install ultérieur sur votre poste les fait disparaître, refaites la vérification : certaines versions de npm 11 ont, semble-t-il, ramené le bogue.

# 1. Does the lockfile list sharp's Linux packages?
grep -c '"node_modules/@img/sharp-linux-x64"' package-lock.json
grep -c '"node_modules/@img/sharp-libvips-linux-x64"' package-lock.json

# 2. If either prints 0, regenerate the lockfile from scratch
rm -rf node_modules package-lock.json
npm install
grep -c '"node_modules/@img/sharp-linux-x64"' package-lock.json   # should be 1 now

# 3. Commit it
git add package-lock.json
git commit -m "lockfile: include sharp's Linux binaries"

pnpm et Yarn 3+ lisent un réglage supportedArchitectures qui installe aussi les dépendances facultatives d’autres plateformes. Il ne sert que lorsqu’une même arborescence doit fonctionner sur deux plateformes, comme une image Docker construite à partir du magasin d’un Mac. Une installation normale sur le serveur choisit Linux d’elle-même.

# pnpm-workspace.yaml: also install the Linux binaries on a Mac or Windows machine
supportedArchitectures:
  os:
    - current
    - linux
  cpu:
    - current
    - x64

• L’installation se fait sous Linux, à la compilation. Canner lance l’installation figée de votre gestionnaire de paquets (npm ci, pnpm install --frozen-lockfile, etc.) avec --ignore-scripts. Il ne passe pas --omit=optional : les paquets Linux s’installent dès que votre fichier de verrouillage les mentionne.
• `--ignore-scripts` n’est pas en cause pour sharp 0.33 et plus. Ces versions tirent leur binaire des paquets facultatifs, pas d’un script d’installation (sharp 0.35 n’en a plus du tout).
• L’avertissement du journal de compilation. Quand sharp figure dans dependencies ou devDependencies, le journal affiche [canner] ⚠ Native modules need a postinstall allowlist (sharp). Avec un sharp récent, vous pouvez ajouter "canner": { "allowedBuildScripts": ["sharp"] } à package.json pour le faire taire, sans effet néfaste. Avec pnpm, "pnpm": { "onlyBuiltDependencies": ["sharp"] } fonctionne aussi. Avec Yarn, la liste n’a aucun effet : Yarn n’a pas de commande de recompilation.
• Un vieux sharp ne fonctionnera pas. Canner relance les scripts autorisés sans accès au réseau : le script de sharp 0.32 ne peut pas télécharger ce qu’il lui faut. Mettez-le à jour.
• Next.js. Next 16 déclare sharp comme dépendance facultative de next : inutile de l’ajouter vous-même. Les règles sur le fichier de verrouillage s’appliquent quand même.
• Où le voir. Si votre compilation charge sharp, l’erreur est dans le journal de compilation. Sinon, elle est dans les journaux de l’appli, sur la page Journaux, à la première requête d’image. Voir journaux et erreurs.

Un conteneur Linux propre installe exactement ce que dit votre fichier de verrouillage. Si sharp ok ne s’affiche pas ici, ça ne marchera sur aucun hôte Linux :

# Install the way a Linux server does, from a copy so your own node_modules is untouched
docker run --rm -v "$PWD":/src:ro node:22 sh -c \
  "cp -r /src /app && cd /app && rm -rf node_modules \
   && npm ci --ignore-scripts && node -e \"require('sharp'); console.log('sharp ok')\""