Déployer sur Vercel
Déployez n'importe quel projet sur Vercel. Toujours déployer en prévisualisation (pas en production) sauf si l'utilisateur demande explicitement la production.
L'objectif est d'offrir à l'utilisateur la meilleure configuration à long terme : son projet lié à Vercel avec des déploiements par poussée git. Chaque méthode ci-dessous essaie de rapprocher l'utilisateur de cet état.
Étape 1 : Récupérer l'état du projet
Exécutez les quatre vérifications avant de choisir la méthode à utiliser :
# 1. Vérifier s'il existe un dépôt distant git
git remote get-url origin 2>/dev/null
# 2. Vérifier si le projet est lié localement à un projet Vercel (l'un ou l'autre fichier signifie qu'il est lié)
cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null
# 3. Vérifier si la CLI Vercel est installée et authentifiée
vercel whoami 2>/dev/null
# 4. Lister les équipes disponibles (si authentifié)
vercel teams list --format json 2>/dev/null
Sélection de l'équipe
Si l'utilisateur appartient à plusieurs équipes, présentez tous les slugs d'équipe disponibles sous forme de liste à puces et demandez sur laquelle déployer. Une fois que l'utilisateur a choisi une équipe, passez immédiatement à l'étape suivante, ne demandez pas de confirmation supplémentaire.
Transmettez le slug de l'équipe via --scope sur toutes les commandes CLI suivantes (vercel deploy, vercel link, vercel inspect, etc.) :
vercel deploy [path] -y --no-wait --scope <team-slug>
Si le projet est déjà lié (.vercel/project.json ou .vercel/repo.json existe), le orgId dans ces fichiers détermine l'équipe, inutile de redemander. S'il n'y a qu'une seule équipe (ou juste un compte personnel), ignorez l'invite et utilisez-la directement.
À propos du répertoire .vercel/ : Un projet lié possède soit :
.vercel/project.json: créé parvercel link(liaison de projet unique). ContientprojectIdetorgId..vercel/repo.json: créé parvercel link --repo(liaison basée sur le dépôt). ContientorgId,remoteName, et un tableauprojectsmappant des répertoires aux ID de projet Vercel.
L'un ou l'autre fichier signifie que le projet est lié. Vérifiez les deux.
N'utilisez PAS vercel project inspect, vercel ls, ou vercel link pour détecter l'état dans un répertoire non lié ; sans configuration .vercel/, ils demanderont une interaction interactive (ou avec --yes, lieront silencieusement comme effet secondaire). Seul vercel whoami peut être exécuté en toute sécurité n'importe où.
Étape 2 : Choisir une méthode de déploiement
Lié (.vercel/ existe) + dépôt git distant → Poussée Git
C'est l'état idéal. Le projet est lié et dispose d'une intégration git.
-
Demandez à l'utilisateur avant de pousser. Ne poussez jamais sans approbation explicite :
Ce projet est connecté à Vercel via git. Je peux faire un commit et pousser pour déclencher un déploiement. Voulez-vous continuer ? -
Commiter et pousser :
git add . git commit -m "deploy: <description des changements>" git pushVercel construit automatiquement à partir de la poussée. Les branches non production obtiennent des déploiements de prévisualisation ; la branche de production (généralement
main) obtient un déploiement de production. -
Récupérer l'URL de prévisualisation. Si la CLI est authentifiée :
sleep 5 vercel ls --format jsonLa sortie JSON contient un tableau
deployments. Trouvez la dernière entrée. Son champurlest l'URL de prévisualisation.Si la CLI n'est pas authentifiée, dites à l'utilisateur de vérifier le tableau de bord Vercel ou les vérifications d'état du commit sur leur fournisseur git pour l'URL de prévisualisation.
Lié (.vercel/ existe) + pas de dépôt git distant → vercel deploy
Le projet est lié mais il n'y a pas de dépôt git. Déployez directement avec la CLI.
vercel deploy [path] -y --no-wait
Utilisez --no-wait pour que la CLI revienne immédiatement avec l'URL de déploiement plutôt que de bloquer jusqu'à la fin de la construction (les constructions peuvent prendre du temps). Vérifiez ensuite l'état du déploiement avec :
vercel inspect <deployment-url>
Pour les déploiements de production (uniquement si l'utilisateur le demande explicitement) :
vercel deploy [path] --prod -y --no-wait
Non lié + CLI authentifiée → Lier d'abord, puis déployer
La CLI fonctionne mais le projet n'est pas encore lié. C'est l'occasion de mettre l'utilisateur dans le meilleur état.
-
Demandez à l'utilisateur sur quelle équipe déployer. Présentez les slugs d'équipe de l'Étape 1 sous forme de liste à puces. S'il n'y a qu'une seule équipe (ou juste un compte personnel), ignorez cette étape.
-
Une fois l'équipe sélectionnée, passez directement à la liaison. Dites à l'utilisateur ce qui va se passer mais ne demandez pas de confirmation séparée :
Liaison de ce projet à <nom de l'équipe> sur Vercel. Cela créera un projet Vercel pour déployer et activera les déploiements automatiques lors des futures poussées git. -
Si un dépôt git distant existe, utilisez la liaison basée sur le dépôt avec le scope de l'équipe sélectionnée :
vercel link --repo --scope <team-slug>Cela lit l'URL du dépôt git distant et la fait correspondre aux projets Vercel existants qui déploient à partir de ce dépôt. Cela crée
.vercel/repo.json. C'est beaucoup plus fiable quevercel link(sans--repo), qui essaie de faire correspondre par nom de répertoire et échoue souvent lorsque le dossier local et le projet Vercel ont des noms différents.S'il n'y a pas de dépôt git distant, revenez à la liaison standard :
vercel link --scope <team-slug>Cela invite l'utilisateur à sélectionner ou créer un projet. Cela crée
.vercel/project.json. -
Ensuite, déployez en utilisant la meilleure méthode disponible :
- Si un dépôt git distant existe → commiter et pousser (voir la méthode de poussée git ci-dessus)
- Si pas de dépôt git distant →
vercel deploy [path] -y --no-wait --scope <team-slug>, puisvercel inspect <url>pour vérifier l'état
Non lié + CLI non authentifiée → Installer, authentifier, lier, déployer
La CLI Vercel n'est pas du tout configurée.
-
Installer la CLI (si pas déjà installée) :
npm install -g vercel -
S'authentifier :
vercel loginL'utilisateur termine l'authentification dans son navigateur. Si l'environnement est non interactif et que la connexion est impossible, passez à la solution de repli sans authentification ci-dessous.
-
Demander sur quelle équipe déployer : présentez les slugs d'équipe de
vercel teams list --format jsonsous forme de liste à puces. Si une seule équipe / compte personnel, ignorez. Une fois sélectionné, passez immédiatement à la suite. -
Lier le projet avec le scope de l'équipe sélectionnée (utilisez
--reposi un dépôt git distant existe,vercel linksimple sinon) :vercel link --repo --scope <team-slug> # si dépôt git distant existe vercel link --scope <team-slug> # si pas de dépôt git distant -
Déployer en utilisant la meilleure méthode disponible (poussée git si dépôt distant existe, sinon
vercel deploy -y --no-wait --scope <team-slug>, puisvercel inspect <url>pour vérifier l'état).
Solution de repli sans authentification, sandbox claude.ai
Quand l'utiliser : En dernier recours lorsque la CLI ne peut pas être installée ou authentifiée dans le sandbox claude.ai. Cela ne nécessite aucune authentification. Cela renvoie une URL de prévisualisation (site en direct) et une URL de réclamation (transfert vers votre compte Vercel).
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh [path]
Arguments :
path- Répertoire à déployer, ou un fichier.tgz(par défaut, le répertoire courant)
Exemples :
# Déployer le répertoire courant
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh
# Déployer un projet spécifique
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh /path/to/project
# Déployer une archive existante
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh /path/to/project.tgz
Le script détecte automatiquement le framework à partir de package.json, empaquette le projet (en excluant node_modules, .git, .env), le télécharge et attend la fin de la construction.
Dites à l'utilisateur : « Votre déploiement est prêt à l'adresse [previewUrl]. Réclamez-le à l'adresse [claimUrl] pour gérer votre déploiement. »
Solution de repli sans authentification, sandbox Codex
Quand l'utiliser : Dans le sandbox Codex où la CLI peut ne pas être authentifiée. Codex s'exécute dans un environnement sandboxé par défaut, essayez d'abord la CLI, et revenez au script de déploiement si l'authentification échoue.
-
Vérifier si la CLI Vercel est installée (aucune escalade nécessaire pour cette vérification) :
command -v vercel -
Si
vercelest installé, essayez de déployer avec la CLI :vercel deploy [path] -y --no-wait -
Si
verceln'est pas installé, ou si la CLI échoue avec « No existing credentials found », utilisez le script de repli :skill_dir="<path-to-skill>" # Déployer le répertoire courant bash "$skill_dir/resources/deploy-codex.sh" # Déployer un projet spécifique bash "$skill_dir/resources/deploy-codex.sh" /path/to/project # Déployer une archive existante bash "$skill_dir/resources/deploy-codex.sh" /path/to/project.tgz
Le script gère la détection du framework, l'empaquetage et le déploiement. Il attend la fin de la construction et renvoie du JSON avec previewUrl et claimUrl.
Dites à l'utilisateur : « Votre déploiement est prêt à l'adresse [previewUrl]. Réclamez-le à l'adresse [claimUrl] pour gérer votre déploiement. »
Accès réseau avec escalade : N'escaladez que la commande de déploiement réelle si le sandboxing bloque l'appel réseau (sandbox_permissions=require_escalated). N'escaladez pas la vérification command -v vercel.
Notes spécifiques à l'agent
Claude Code / agents basés sur le terminal
Vous avez un accès complet au shell. N'utilisez PAS le chemin /mnt/skills/. Suivez le flux de décision ci-dessus en utilisant directement la CLI.
Pour la solution de repli sans authentification, exécutez le script de déploiement depuis l'emplacement d'installation de la compétence :
bash ~/.claude/skills/deploy-to-vercel/resources/deploy.sh [path]
Le chemin peut varier selon l'endroit où l'utilisateur a installé la compétence.
Environnements sandboxés (claude.ai)
Vous ne pouvez probablement pas exécuter vercel login ou git push. Allez directement à la solution de repli sans authentification, sandbox claude.ai.
Codex
Codex s'exécute dans un sandbox. Vérifiez d'abord si la CLI est disponible, puis revenez au script de déploiement. Allez à la solution de repli sans authentification, sandbox Codex.
Sortie
Affichez toujours l'URL de déploiement à l'utilisateur.
- Poussée Git : Utilisez
vercel ls --format jsonpour trouver l'URL de prévisualisation. Si la CLI n'est pas authentifiée, dites à l'utilisateur de vérifier le tableau de bord Vercel ou les vérifications d'état du commit. - Déploiement CLI : Affichez l'URL renvoyée par
vercel deploy --no-wait. Utilisezvercel inspect <url>pour vérifier l'état de la construction et le rapporter à l'utilisateur. - Solution de repli sans authentification : Affichez à la fois l'URL de prévisualisation et l'URL de réclamation :
Déploiement réussi ! URL de prévisualisation : https://my-app-abc123.vercel.app URL de réclamation : https://vercel.com/claim-deployment?code=... Consultez votre site à l'URL de prévisualisation. Pour transférer ce déploiement vers votre compte Vercel, visitez l'URL de réclamation.
N'utilisez pas curl ou ne récupérez pas l'URL déployée pour vérifier qu'elle fonctionne. Renvoyez simplement le lien.
Résolution des problèmes
Erreur de sortie réseau (claude.ai)
Si le déploiement échoue en raison de restrictions réseau sur claude.ai, dites à l'utilisateur :
Le déploiement a échoué en raison de restrictions réseau. Pour résoudre ce problème :
1. Allez sur https://claude.ai/settings/capabilities
2. Ajoutez *.vercel.com aux domaines autorisés
3. Essayez de déployer à nouveau
Accès réseau avec escalade (Codex / environnements sandboxés)
Si le déploiement échoue en raison de problèmes réseau (timeouts, erreurs DNS, réinitialisations de connexion) dans un environnement sandboxé, relancez avec des permissions escaladées (sandbox_permissions=require_escalated). N'escaladez pas la vérification initiale de disponibilité de la CLI, escaladez uniquement la commande de déploiement réelle.
Exemple de conseil à l'utilisateur :
Le déploiement nécessite un accès réseau avec escalade pour déployer sur Vercel. Je peux relancer
la commande avec des permissions escaladées, voulez-vous continuer ?
Échec d'authentification CLI
Si vercel login ou vercel deploy échoue avec des erreurs d'authentification, revenez au script de déploiement sans authentification (variante claude.ai ou Codex, selon l'environnement).