Vercel deploy bloqué sans message : .vercelignore manquant

Le déploiement CLI qui ne démarre jamais

Un vercel deploy --prod bloqué sans jamais passer à l’état “Building”, sans message d’erreur, vient dans la grande majorité des cas d’un fichier .vercelignore manquant : la CLI tente d’envoyer tout le répertoire de travail, y compris node_modules, et se heurte aux limites d’upload de Vercel. Créer un .vercelignore minimal règle le problème en quelques minutes.

Le 15 mai 2026, sur un projet Astro, on a lancé trois vercel deploy --prod de suite sans obtenir la moindre sortie sur le terminal. Pas d’erreur, pas de logs, rien : la commande restait suspendue comme si elle attendait indéfiniment. En creusant, le CLI tentait d’envoyer environ 200 Mo de node_modules à chaque tentative. Un .vercelignore a réglé le problème dès le quatrième essai.

Ce symptôme est trompeur parce qu’il ne ressemble pas à une erreur classique. Pas de code HTTP, pas de stack trace, juste un blocage silencieux avant même que le build ne démarre côté serveur. C’est normal : le problème se situe avant la construction du projet, au moment de l’upload des fichiers.

Pourquoi ça arrive

Le CLI Vercel est l’outil en ligne de commande qui permet de déployer un projet directement depuis un terminal, sans passer par une intégration Git. Contrairement à un déploiement déclenché par un push Git, le CLI compresse et envoie tout ce qui se trouve dans le répertoire courant, sauf ce qui est explicitement exclu.

Les causes les plus fréquentes de ce blocage :

• Absence de .vercelignore : sans ce fichier, la CLI n’exclut que quelques éléments par défaut (.git, .next, .vercel, node_modules compris dans certains cas mais pas toujours de façon fiable selon la version utilisée), et peut tenter d’embarquer des dossiers volumineux non prévus.
• node_modules non exclu : ce dossier contient souvent plusieurs dizaines de milliers de petits fichiers. C’est la cause numéro un des blocages observés.
• Dépassement du plafond de fichiers : Vercel limite un déploiement CLI à 15 000 fichiers sources maximum source : Vercel, Limits. Un node_modules moyen dépasse largement ce chiffre à lui seul.
• Dépassement du plafond de taille : la taille maximale des fichiers sources uploadables via CLI est de 100 Mo sur le plan Hobby et 1 Go sur le plan Pro source : Vercel, Limits.
• Dossiers de build ou de cache non exclus : .astro/, dist/, .cache/ peuvent gonfler l’upload inutilement selon le framework utilisé.
• Version de CLI incohérente avec le comportement attendu : l’application du .vercelignore aux fichiers prébuilts a évolué entre les versions 56 et 59 de la CLI en 2026, avec parfois des effets inattendus sur les fichiers réellement exclus source : GitHub, Jovie PR #18384.

Un cas documenté publiquement illustre l’ampleur du problème : un .vercelignore absent a conduit à l’upload de 202 843 fichiers et à un blocage de compte Vercel de 24 heures, le temps que la plateforme traite la charge anormale source : GitHub, fderuiter/portfolio #854.

1. Reconnaître le symptôme avant de chercher plus loin

Avant toute correction, confirme que tu es bien face à ce cas précis. Les signes typiques :

• La commande vercel deploy --prod ne renvoie aucune sortie pendant plusieurs minutes.
• Le déploiement n’apparaît jamais avec le statut “Building” dans le dashboard Vercel.
• Aucun message d’erreur explicite n’est renvoyé dans le terminal.
• Le projet contient un node_modules volumineux et pas de .vercelignore à la racine.

Si ces quatre points correspondent, tu es très probablement dans ce cas de figure plutôt que face à un problème de build ou de configuration serveur.

2. Vérifier ce que la CLI s’apprête réellement à envoyer

Avant de corriger à l’aveugle, utilise vercel deploy --dry pour voir la liste des fichiers que la CLI compte inclure dans l’upload, sans réellement déclencher le déploiement source : dev.to, Vercel CLI dry-run. Cette commande transforme un déploiement à l’aveugle en inspection préalable : tu vois immédiatement si node_modules, un .env égaré ou un dossier de build s’y trouvent.

Si la liste affichée compte plusieurs milliers de fichiers alors que ton projet source en contient une centaine, le diagnostic est confirmé.

3. Créer un .vercelignore minimal à la racine

Un fichier .vercelignore est un fichier texte placé à la racine du projet qui indique à la CLI Vercel quels fichiers et dossiers exclure du processus de déploiement, avec une syntaxe identique à celle d’un .gitignore source : Vercel, Exclude Files from Deployments.

Pour un projet Astro classique, un .vercelignore minimal suffit :

node_modules/
.git/
.vercel/
dist/
.astro/

C’est exactement la combinaison qui a réglé le blocage du 15 mai 2026 sur le projet cité plus haut. Place ce fichier à la racine, au même niveau que package.json, puis relance vercel deploy --prod.

Vercel exclut déjà par défaut une liste de fichiers sans configuration supplémentaire : .git, .svn, .cache, .next, .now, .vercel, .npmignore, .dockerignore, .gitignore, .env.local, node_modules, __pycache__, entre autres source : Vercel, Build Features. Mais cette liste par défaut n’est pas toujours suffisante ni appliquée de façon homogène selon le mode de déploiement, d’où l’intérêt d’un fichier explicite plutôt que de compter sur le comportement implicite.

4. Vérifier l’effet avec un nouveau dry-run

Relance vercel deploy --dry après avoir ajouté le .vercelignore. Le nombre de fichiers listés doit chuter drastiquement, de plusieurs dizaines de milliers à quelques centaines dans la plupart des projets Astro ou Next.js standards. Si le nombre reste anormalement élevé, vérifie que le .vercelignore est bien à la racine du projet déployé et non dans un sous-dossier, un piège fréquent dans les monorepos où Vercel applique en priorité le .vercelignore du répertoire racine du projet plutôt que celui du dépôt entier source : Vercel, Exclude Files from Deployments.

5. Comprendre pourquoi les déploiements Git ne sont pas concernés

C’est le point qui surprend le plus : si ce même projet est connecté à Vercel via l’intégration Git et déployé par un git push, ce blocage n’apparaît pas. Vercel ne clone alors que les fichiers commités dans le dépôt, et le .gitignore du projet filtre déjà node_modules en amont, avant même que Vercel n’intervienne source : GitHub, Extending .vercelignore.

Un exemple chiffré documenté illustre bien l’écart entre les deux chemins de déploiement : sur un même projet, un déploiement CLI prébuilt comptait 30 305 fichiers à traiter, contre seulement 2 087 fichiers lors d’un déploiement déclenché directement par Git source : GitHub, vercel/vercel #10613. La différence tient uniquement à la source des fichiers envoyés : le disque local complet dans un cas, le contenu du dépôt Git filtré dans l’autre.

Concrètement, si ton workflow permet de basculer vers un déploiement automatique par push Git plutôt que par CLI manuelle, tu élimines la classe entière de ce problème. C’est aussi ce qui rend les pipelines CI/CD plus fiables sur la durée qu’un déploiement manuel répété.

Cause → solution : tableau récapitulatif

FAQ

Quand passer la main à un pro

Si le .vercelignore minimal ne résout rien, si tu es sur un monorepo avec plusieurs projets Vercel imbriqués, ou si un déploiement prébuilt continue d’exclure des fichiers nécessaires malgré tes réglages, le problème touche à la configuration du pipeline de build plutôt qu’à une simple liste d’exclusion. C’est le moment de faire auditer la configuration de déploiement plutôt que de multiplier les tentatives à l’aveugle. Ce type de réglage fait partie de ce qu’une maintenance par abonnement couvre normalement en amont, avant que le blocage n’arrive en production. Pour comparer les plateformes de déploiement disponibles selon ton projet, l’article sur Netlify ou Vercel détaille les différences concrètes. Et si le problème touche un déploiement post-migration vers Astro, la checklist de migration WordPress vers Astro sans casser le SEO couvre les autres pièges fréquents de ce type de projet.