Vercel CLI с токенами

Деплой и управление проектами на Vercel через CLI с токен-аутентификацией — без интерактивного vercel login.

Шаг 1: Найти токен Vercel

Перед любыми командами Vercel CLI определите источник токена. Проверяйте сценарии по порядку.

A) VERCEL_TOKEN уже задан в окружении

printenv VERCEL_TOKEN

Если команда вернула значение — переходите к шагу 2.

B) Токен в файле .env под именем VERCEL_TOKEN

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

Если найден — экспортируйте:

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

C) Токен в .env под другим именем

Ищите переменную с токеном Vercel (обычно начинается с vca_):

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

Найдите нужную переменную и экспортируйте её как VERCEL_TOKEN:

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

D) Токен не найден — спросить пользователя

Если ни один из способов не дал результата, попросите пользователя предоставить токен. Создать токен можно на vercel.com/account/tokens.

Важно: после экспорта VERCEL_TOKEN Vercel CLI читает его автоматически — не передавайте токен через флаг --token. Секреты в аргументах командной строки видны в истории shell и списке процессов.

# Плохо — токен виден в истории shell и процессах
vercel deploy --token "vca_abc123"

# Хорошо — CLI читает VERCEL_TOKEN из окружения
export VERCEL_TOKEN="vca_abc123"
vercel deploy

Шаг 2: Найти ID проекта и команды

# Проверить окружение
printenv VERCEL_PROJECT_ID
printenv VERCEL_ORG_ID

# Или .env файл
grep -i 'vercel' .env 2>/dev/null

Если есть URL проекта (например, https://vercel.com/my-team/my-project), извлеките slug команды:

echo "$PROJECT_URL" | sed 's|https://vercel.com/||' | cut -d/ -f1

Если VERCEL_ORG_ID и VERCEL_PROJECT_ID заданы — экспортируйте их вместе (оба обязательны; один без другого вызывает ошибку):

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

Установка CLI

npm install -g vercel
vercel --version

Деплой проекта

По умолчанию всегда деплоить как preview — в production только по явному запросу.

Быстрый деплой (есть project ID — линкинг не нужен)

# Прямой деплой
vercel deploy -y --no-wait

# С командой
vercel deploy --scope <team-slug> -y --no-wait

# Production (только по явному запросу)
vercel deploy --prod --scope <team-slug> -y --no-wait

# Статус деплоя
vercel inspect <deployment-url>

Полный деплой (нет project ID — нужен линкинг)

Проверка состояния проекта

# Есть ли git remote?
git remote get-url origin 2>/dev/null

# Уже привязан к Vercel?
cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null

Линкинг проекта

# С git remote (предпочтительно) — читает remote и создаёт .vercel/repo.json
vercel link --repo --scope <team-slug> -y

# Без git remote — создаёт .vercel/project.json
vercel link --scope <team-slug> -y

# Привязка к конкретному проекту по имени
vercel link --project <project-name> --scope <team-slug> -y

Деплой после линкинга

A) Git Push Deploy — есть git remote (предпочтительно)

1. Всегда спрашивать у пользователя разрешение перед push
2. Commit и push:

   git add .
   git commit -m "deploy: <описание изменений>"
   git push

3. Vercel строит автоматически. Не-production ветки получают preview-деплои
4. Получить URL деплоя:

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

B) CLI Deploy — нет git remote

vercel deploy --scope <team-slug> -y --no-wait
vercel inspect <deployment-url>

Управление переменными окружения

# Для всех окружений
echo "value" | vercel env add VAR_NAME --scope <team-slug>

# Для конкретного окружения (production, preview, development)
echo "value" | vercel env add VAR_NAME production --scope <team-slug>

# Список переменных
vercel env ls --scope <team-slug>

# Скачать в .env.local
vercel env pull --scope <team-slug>

# Удалить переменную
vercel env rm VAR_NAME --scope <team-slug> -y

Просмотр деплоев

# Список последних деплоев
vercel ls --format json --scope <team-slug>

# Информация о деплое
vercel inspect <deployment-url>

# Логи сборки (требуется Vercel CLI v35+)
vercel inspect <deployment-url> --logs

# Runtime-логи запросов (живой стрим; --no-follow для снапшота)
vercel logs <deployment-url>

Управление доменами

# Список доменов
vercel domains ls --scope <team-slug>

# Добавить домен (привязанная директория)
vercel domains add <domain> --scope <team-slug>

# Добавить домен (непривязанная директория)
vercel domains add <domain> <project> --scope <team-slug>

Соглашение о работе

• Никогда не передавать VERCEL_TOKEN через флаг --token. Экспортировать переменную и дать CLI прочитать её из окружения.
• Проверять окружение до запроса токена у пользователя. Сначала смотреть в текущем env и файлах .env.
• По умолчанию — preview-деплой. В production только по явному запросу.
• Спрашивать перед git push. Никогда не пушить без разрешения пользователя.
• Не редактировать файлы .vercel/ напрямую. CLI управляет этой директорией; читать можно.
• Не делать curl/fetch на задеплоенные URL для проверки. Просто вернуть ссылку пользователю.
• Использовать --format json для структурированного вывода.
• Использовать -y в командах с подтверждением, чтобы избежать интерактивной блокировки.

Устранение неполадок

Токен не найден

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

Ошибка аутентификации

Если CLI выдаёт Authentication required: токен мог истечь или стать недействительным. Проверьте: vercel whoami. Попросите пользователя предоставить свежий токен.

Неверная команда

vercel whoami --scope <team-slug>

Ошибка сборки

vercel inspect <deployment-url> --logs

Частые причины: отсутствуют зависимости в package.json; не заданы переменные окружения; неверная конфигурация фреймворка в vercel.json (Vercel автоопределяет Next.js, Remix, Vite из package.json).

CLI не установлен

npm install -g vercel