PhuongDeveloper/landingpage

CLI Vercel avec jetons (tokens)

Déployez et gérez des projets sur Vercel en utilisant la CLI avec une authentification par jeton, sans avoir recours à vercel login.

Étape 1 : Localiser le jeton Vercel

Avant d'exécuter une commande CLI Vercel, identifiez d'où provient le jeton. Parcourez ces scénarios dans l'ordre :

A) VERCEL_TOKEN est déjà défini dans l'environnement

printenv VERCEL_TOKEN

Si cela retourne une valeur, vous êtes prêt. Passez à l'Étape 2.

B) Le jeton se trouve dans un fichier .env sous VERCEL_TOKEN

grep '^VERCEL_TOKEN=' .env 2>/dev/null

S'il est trouvé, exportez-le :

export VERCEL_TOKEN=$(grep '^VERCEL_TOKEN=' .env | cut -d= -f2-)

C) Le jeton se trouve dans un fichier .env sous un nom différent

Cherchez toute variable qui ressemble à un jeton Vercel (les jetons Vercel commencent généralement par vca_) :

grep -i 'vercel' .env 2>/dev/null

Inspectez le résultat pour identifier quelle variable contient le jeton, puis exportez-la sous le nom VERCEL_TOKEN :

export VERCEL_TOKEN=$(grep '^<NOM_VARIABLE>=' .env | cut -d= -f2-)

D) Aucun jeton trouvé — demander à l'utilisateur

Si aucune des étapes ci-dessus ne produit un jeton, demandez à l'utilisateur d'en fournir un. Il peut créer un jeton d'accès Vercel sur vercel.com/account/tokens.

---

Important : Une fois que VERCEL_TOKEN est exporté en tant que variable d'environnement, la CLI Vercel le lit nativement — ne le passez pas en tant que drapeau --token. Mettre des secrets dans les arguments de ligne de commande les expose dans l'historique du shell et dans les listes de processus.

# Mauvais — le jeton est visible dans l'historique du shell et les listes de processus
vercel deploy --token "vca_abc123"

# Bon — la CLI lit VERCEL_TOKEN depuis l'environnement
export VERCEL_TOKEN="vca_abc123"
vercel deploy

Étape 2 : Localiser le projet et l'équipe

De même, vérifiez l'ID du projet et le périmètre de l'équipe. Cela permet à la CLI de cibler le bon projet sans avoir besoin de vercel link.

# Vérifier l'environnement
printenv VERCEL_PROJECT_ID
printenv VERCEL_ORG_ID

# Ou vérifier .env
grep -i 'vercel' .env 2>/dev/null

Si vous avez une URL de projet (par ex. https://vercel.com/mon-equipe/mon-projet), extrayez le slug de l'équipe :

# par ex. "mon-equipe" depuis "https://vercel.com/mon-equipe/mon-projet"
echo "$PROJECT_URL" | sed 's|https://vercel.com/||' | cut -d/ -f1

Si vous avez à la fois VERCEL_ORG_ID et VERCEL_PROJECT_ID dans votre environnement, exportez-les — la CLI les utilisera automatiquement et ignorera tout répertoire .vercel/ :

export VERCEL_ORG_ID="<id-org>"
export VERCEL_PROJECT_ID="<id-projet>"

Remarque : VERCEL_ORG_ID et VERCEL_PROJECT_ID doivent être définis ensemble — définir un seul provoque une erreur.

Configuration de la CLI

Assurez-vous que la CLI Vercel est installée et à jour :

npm install -g vercel
vercel --version

Déployer un projet

Déployez toujours en tant que preview sauf si l'utilisateur demande explicitement la production. Choisissez une méthode en fonction de ce dont vous disposez.

Déploiement rapide (ID du projet disponible — pas de liaison nécessaire)

Lorsque VERCEL_TOKEN et VERCEL_PROJECT_ID sont définis dans l'environnement, déployez directement :

vercel deploy -y --no-wait

Avec un périmètre d'équipe (via VERCEL_ORG_ID ou --scope) :

vercel deploy --scope <slug-equipe> -y --no-wait

Production (uniquement sur demande explicite) :

vercel deploy --prod --scope <slug-equipe> -y --no-wait

Vérifiez le statut :

vercel inspect <url-deploiement>

Flux de déploiement complet (pas d'ID de projet — besoin de lier)

Utilisez cette méthode lorsque vous avez un jeton et une équipe mais pas d'ID de projet préexistant.

Vérifier d'abord l'état du projet

# Le projet a-t-il un dépôt distant git ?
git remote get-url origin 2>/dev/null

# Est-il déjà lié à un projet Vercel ?
cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null

Lier le projet

Avec un dépôt distant git (recommandé) :

vercel link --repo --scope <slug-equipe> -y

Lit le dépôt distant git et le connecte au projet Vercel correspondant. Crée .vercel/repo.json. Plus fiable que vercel link simple, qui associe par nom de répertoire.

Sans dépôt distant git :

vercel link --scope <slug-equipe> -y

Crée .vercel/project.json.

Lier à un projet spécifique par son nom :

vercel link --project <nom-projet> --scope <slug-equipe> -y

Si le projet est déjà lié, vérifiez orgId dans .vercel/project.json ou .vercel/repo.json pour confirmer qu'il correspond à l'équipe visée.

Déployer après la liaison

A) Déploiement par push Git — dépôt distant disponible (recommandé)

Les pushes Git déclenchent des déploiements automatiques sur Vercel.

1. Demandez à l'utilisateur avant de pousser. Ne poussez jamais sans approbation explicite.
2. Commitez et poussez :

   git add .
   git commit -m "deploy: <description des modifications>"
   git push
   

3. Vercel construit automatiquement. Les branches non-production reçoivent des déploiements de preview.
4. Récupérez l'URL du déploiement :

   sleep 5
   vercel ls --format json --scope <slug-equipe>
   

   Trouvez l'entrée la plus récente dans le tableau deployments.

B) Déploiement via CLI — pas de dépôt distant

vercel deploy --scope <slug-equipe> -y --no-wait

Vérifiez le statut :

vercel inspect <url-deploiement>

Déployer depuis un dépôt distant (code non cloné localement)

1. Clonez le dépôt :

   git clone <url-depot>
   cd <nom-depot>
   

2. Liez à Vercel :

   vercel link --repo --scope <slug-equipe> -y
   

3. Déployez via un push git (si vous avez les droits d'écriture) ou via le déploiement CLI.

À propos du répertoire .vercel/

Un projet lié contient soit :

• .vercel/project.json — provenant de vercel link. Contient projectId et orgId.
• .vercel/repo.json — provenant de vercel link --repo. Contient orgId, remoteName et une carte projects.

Non nécessaire lorsque VERCEL_ORG_ID + VERCEL_PROJECT_ID sont tous deux définis dans l'environnement.

N'exécutez PAS vercel project inspect ou vercel link dans un répertoire non lié pour détecter l'état — ils demanderaient une interaction ou lieraient silencieusement comme effet secondaire. vercel ls est sûr (dans un répertoire non lié, il liste par défaut tous les déploiements pour le périmètre). vercel whoami est sûr partout.

Gestion des variables d'environnement

# Définir pour tous les environnements
echo "valeur" | vercel env add NOM_VAR --scope <slug-equipe>

# Définir pour un environnement spécifique (production, preview, development)
echo "valeur" | vercel env add NOM_VAR production --scope <slug-equipe>

# Lister les variables d'environnement
vercel env ls --scope <slug-equipe>

# Récupérer les variables d'environnement dans un fichier .env.local
vercel env pull --scope <slug-equipe>

# Supprimer une variable
vercel env rm NOM_VAR --scope <slug-equipe> -y

Inspection des déploiements

# Lister les déploiements récents
vercel ls --format json --scope <slug-equipe>

# Inspecter un déploiement spécifique
vercel inspect <url-deploiement>

# Voir les logs de build (nécessite CLI Vercel v35+)
vercel inspect <url-deploiement> --logs

# Voir les logs d'exécution (suit en direct par défaut ; ajoutez --no-follow pour un instantané)
vercel logs <url-deploiement>

Gestion des domaines

# Lister les domaines
vercel domains ls --scope <slug-equipe>

# Ajouter un domaine au projet — répertoire lié ou lié via environnement (1 argument)
vercel domains add <domaine> --scope <slug-equipe>

# Ajouter un domaine — répertoire non lié (nécessite le paramètre <projet>)
vercel domains add <domaine> <projet> --scope <slug-equipe>

Changements de plan Stripe Projects

Si ce projet est géré par Stripe Projects. Demandez à l'utilisateur avant d'exécuter tout changement de plan payant ou destructeur — les mises à niveau facturent une vraie carte, les rétrogradations suppriment des sièges.

Exécutez d'abord stripe projects status --json pour confirmer le nom local de la ressource Vercel. Les exemples ci-dessous supposent la valeur par défaut (vercel-plan) ; remplacez par le nom réel s'il a été renommé lors de stripe projects add.

• Passer à Pro : stripe projects add vercel/pro (ou stripe projects upgrade vercel-plan pro)
• Revenir à Hobby : stripe projects downgrade vercel-plan hobby

Ce qu'offre Pro

• Frais de plateforme de 20 $/mois, incluant 20 $/mois de crédit d'utilisation.
• Machines de build Turbo (30 vCPUs, 60 Go de mémoire) par défaut pour les nouveaux projets — builds nettement plus rapides que Hobby.
• 1 siège de déploiement + un nombre illimité de sièges Viewer gratuits (collaborateurs en lecture seule, commentaires de preview).
• Allocations incluses plus élevées (1 To de transfert de données rapide, 10 millions de requêtes Edge par mois).
• Modules complémentaires payants disponibles : SAML SSO, HIPAA BAA, Flags Explorer, Observability Plus, Speed Insights, Web Analytics Plus.

Détails complets : https://vercel.com/docs/plans/pro-plan

Accord de travail

• Ne jamais passer VERCEL_TOKEN en tant que drapeau --token. Exportez-le comme variable d'environnement et laissez la CLI le lire nativement.
• Vérifiez l'environnement pour les jetons avant de demander à l'utilisateur. Regardez d'abord dans l'environnement actuel et les fichiers .env.
• Par défaut, effectuez des déploiements preview. Ne déployez en production que sur demande explicite.
• Demandez avant de pousser vers git. Ne poussez jamais de commits sans l'approbation de l'utilisateur.
• Ne modifiez pas les fichiers .vercel/ directement. La CLI gère ce répertoire. Les lire (par ex. pour vérifier orgId) est acceptable.
• N'utilisez pas curl/fetch pour vérifier les URLs déployées. Renvoyez simplement le lien à l'utilisateur.
• Utilisez --format json lorsqu'une sortie structurée facilitera les étapes suivantes.
• Utilisez -y sur les commandes qui demandent une confirmation pour éviter les blocages interactifs.

Dépannage

Jeton introuvable

Vérifiez l'environnement et les éventuels fichiers .env présents :

printenv | grep -i vercel
grep -i vercel .env 2>/dev/null

Erreur d'authentification

Si la CLI échoue avec Authentication required :

• Le jeton a peut-être expiré ou est invalide.
• Vérifiez : vercel whoami (utilise VERCEL_TOKEN depuis l'environnement).
• Demandez à l'utilisateur un nouveau jeton.

Mauvaise équipe

Vérifiez que le périmètre est correct :

vercel whoami --scope <slug-equipe>

Échec de build

Consultez les logs de build :

vercel inspect <url-deploiement> --logs

Causes courantes :

• Dépendances manquantes — assurez-vous que package.json est complet et commité.
• Variables d'environnement manquantes — ajoutez-les avec vercel env add.
• Mauvaise configuration du framework — vérifiez vercel.json. Vercel détecte automatiquement les frameworks (Next.js, Remix, Vite, etc.) depuis package.json ; remplacez avec vercel.json si la détection est erronée.

CLI non installée

npm install -g vercel