Пошук уроків, статей та іншого контенту
Опублікуєте Next.js на Vercel, налаштуєте проєкт, змінні середовища та production-деплой.
Vercel — платформа для розгортання вебзастосунків. Вона автоматично збирає та публікує Next.js-проєкти, підтримує домени, змінні середовища, попередні деплої та автоматичні оновлення після змін у репозиторії.
Після розгортання застосунок отримує адресу на кшталт:
https://my-next-app.vercel.appДля цього уроку потрібні:
готовий Next.js-проєкт;
обліковий запис Vercel;
репозиторій проєкту на GitHub, GitLab або Bitbucket;
доступ до цього репозиторію.
Перед розгортанням перевірте, що застосунок запускається локально.
npm install
npm run devВідкрийте адресу, яку покаже Next.js, зазвичай:
http://localhost:3000Також варто перевірити production-збірку:
npm run build
npm startКоманда npm run build створює production-версію застосунку. Якщо під час її виконання виникають помилки, спочатку виправте їх локально.
У файлі package.json мають бути доступні скрипти build і start. Наприклад:
{
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start"
}
}Vercel зазвичай сам визначає, що проєкт використовує Next.js, і підставляє правильні команди.
Vercel розгортає проєкт із репозиторію. Додайте файли до Git і відправте їх на віддалений репозиторій.
git add .
git commit -m "Prepare Next.js app for deployment"
git push origin mainНазва основної гілки може бути іншою, наприклад master.
Перевірте, що в репозиторії є:
package.json;
файли застосунку;
next.config.js або next.config.mjs, якщо він потрібен;
файл блокування залежностей: package-lock.json, yarn.lock, pnpm-lock.yaml або bun.lock.
Не додавайте до репозиторію локальний файл .env.local. Він може містити секрети.
Щоб створити деплой через панель Vercel:
Увійдіть до свого облікового запису Vercel.
Створіть новий проєкт.
Виберіть Git-провайдера.
Знайдіть потрібний репозиторій.
Натисніть кнопку імпорту проєкту.
Перевірте параметри проєкту.
Запустіть деплой.
Vercel автоматично визначає Next.js і зазвичай встановлює такі параметри:
Framework Preset — Next.js;
Build Command — команда з package.json, зазвичай next build;
Output Directory — стандартний каталог Next.js;
Install Command — команда встановлення залежностей відповідно до lock-файлу.
Якщо Next.js-проєкт розташований у корені репозиторію, залиште значення Root Directory без змін.
Якщо проєкт знаходиться у вкладеній папці, наприклад frontend, виберіть цю папку як кореневу:
repository/
├── backend/
└── frontend/
├── app/
├── package.json
└── next.config.jsУ такому випадку Vercel має виконувати встановлення залежностей і збірку саме в папці frontend.
Зазвичай достатньо стандартної команди:
npm run buildНе змінюйте її без потреби. Якщо у package.json використовується інший менеджер пакетів, Vercel визначить його за lock-файлом.
Змінні середовища зберігають налаштування, які не потрібно записувати безпосередньо в коді. Наприклад:
адресу API;
ключ підключення до сервісу;
назву середовища;
ідентифікатор проєкту.
Локально такі змінні можна зберігати у файлі .env.local:
API_URL=https://api.example.com
NEXT_PUBLIC_APP_NAME=My Next AppУ Next.js змінні без префікса NEXT_PUBLIC_ доступні лише на сервері. Змінні з префіксом NEXT_PUBLIC_ можуть потрапити до браузерного коду.
Не зберігайте секретні ключі у змінних із префіксом
NEXT_PUBLIC_.
Наприклад, серверну змінну можна прочитати так:
const apiUrl = process.env.API_URL;Публічну змінну можна використати в компоненті:
export default function HomePage() {
const appName = process.env.NEXT_PUBLIC_APP_NAME;
return <h1>{appName}</h1>;
}Змінні середовища налаштовуються в параметрах проєкту Vercel:
Відкрийте проєкт.
Перейдіть до параметрів проєкту.
Відкрийте розділ змінних середовища.
Додайте назву змінної та її значення.
Виберіть середовища, у яких вона доступна.
Збережіть зміни.
Vercel має окремі середовища:
Development — локальна розробка;
Preview — тимчасові деплої для гілок і pull request;
Production — основна опублікована версія.
Наприклад, для production можна додати:
API_URL=https://api.example.comПісля додавання або зміни змінної середовища потрібно виконати новий деплой. Значення змінних застосовується під час збирання та запуску нового деплою.
Створимо просту сторінку, яка показує назву застосунку з публічної змінної середовища.
Файл .env.local:
NEXT_PUBLIC_APP_NAME=Мій Next.js застосунокФайл app/page.js:
export default function HomePage() {
const appName =
process.env.NEXT_PUBLIC_APP_NAME || "Next.js застосунок";
return (
<main>
<h1>{appName}</h1>
<p>Ця сторінка працює на Vercel.</p>
</main>
);
}Перед production-деплоєм додайте таку саму змінну у Vercel. Локальний файл .env.local не передається на Vercel автоматично.
Після натискання кнопки запуску Vercel виконує приблизно такі кроки:
Завантажує код із репозиторію.
Встановлює залежності.
Виконує production-збірку.
Публікує результат.
Надає URL для перегляду застосунку.
Стан і журнали деплою можна переглянути у проєкті Vercel. Якщо збірка завершилася успішно, деплой отримує статус готового.
Production-деплой зазвичай створюється з основної гілки, наприклад main. Коли ви відправляєте новий коміт у цю гілку, Vercel автоматично запускає новий production-деплой.
git add .
git commit -m "Update homepage"
git push origin mainПісля завершення збірки на production-адресі буде доступна нова версія.
Зміни в інших гілках не обов’язково одразу публікуються на основному сайті. Для них Vercel створює preview-деплої.
Це дає змогу:
перевірити зміни до об’єднання гілки;
поділитися тимчасовою адресою;
протестувати production-збірку окремо від основного сайту.
Типовий процес:
git checkout -b feature/new-homepage
# внесення змін
git add .
git commit -m "Create new homepage"
git push origin feature/new-homepageПісля відправлення гілки Vercel створить preview-деплой. Його URL можна знайти у списку деплоїв або в pull request.
Проєкт можна розгорнути не лише через панель, а й через командний рядок.
Встановіть Vercel CLI:
npm install --global vercelУвійдіть до облікового запису:
vercel loginПерейдіть до папки Next.js-проєкту та запустіть деплой:
vercelПід час першого запуску CLI поставить запитання про обліковий запис, команду або проєкт. Після підтвердження Vercel створить preview-деплой.
Для production-деплою використовуйте:
vercel --prodCLI виконує ті самі основні етапи: завантажує проєкт, встановлює залежності, запускає збірку та публікує результат.
Після деплою перевірте:
чи відкривається основна сторінка;
чи завантажуються стилі та зображення;
чи працюють переходи між сторінками;
чи доступні необхідні змінні середовища;
чи правильно працюють серверні запити;
чи немає помилок у журналах деплою.
Перевіряйте застосунок саме за production-адресою, а не лише через localhost. Локальне та production-середовище можуть мати різні змінні, URL і налаштування.
Після першого деплою оновлення зазвичай виглядає так:
# Змінюємо код локально
npm run build
# Зберігаємо зміни в Git
git add .
git commit -m "Fix production page"
# Запускаємо автоматичний деплой
git push origin mainVercel помітить новий коміт, запустить збірку та, якщо вона успішна, опублікує нову версію.
Якщо локально застосунок працює, а після деплою — ні, перевірте змінні середовища у Vercel.
Переконайтеся, що:
назва змінної написана точно;
змінна додана до потрібного середовища;
значення не містить зайвих пробілів;
після зміни змінної було створено новий деплой.
Не записуйте API-ключі та паролі у файли, які передаються до Git.
Перевірте, що .env.local доданий до .gitignore:
.env*
!.env.exampleФайл .env.example може містити лише назви змінних без реальних значень:
API_URL=
NEXT_PUBLIC_APP_NAME=Якщо секрет уже потрапив у репозиторій, його потрібно відкликати або замінити у відповідному сервісі.
Змінна, додана лише для Preview, не буде доступна у production. Перевірте вибрані середовища в налаштуваннях змінної.
Якщо package.json знаходиться у вкладеній папці, але Vercel шукає його в корені репозиторію, збірка завершиться помилкою. Вкажіть правильну Root Directory.
Запустіть локальну перевірку:
npm run buildВиправляйте помилки збірки локально, а потім відправляйте новий коміт. Журнали Vercel допомагають знайти файл і рядок, де виникла проблема.
Не зберігайте кілька lock-файлів для різних менеджерів пакетів в одному проєкті без потреби. Наприклад, виберіть npm і використовуйте package-lock.json, або pnpm і використовуйте pnpm-lock.yaml.
Адреса http://localhost:3000 працює лише на локальному комп’ютері. Для production потрібно використовувати адресу опублікованого API або змінну середовища з потрібним значенням.
Vercel автоматично визначає Next.js-проєкти та виконує їхню збірку.
Для деплою через панель потрібен репозиторій із кодом проєкту.
Перед розгортанням перевірте npm run build.
Змінні середовища додаються в налаштуваннях Vercel окремо для Development, Preview і Production.
Секретні змінні не можна зберігати в репозиторії або називати з префіксом NEXT_PUBLIC_.
Деплой із основної гілки публікує production-версію.
Деплої з інших гілок використовуються для попереднього перегляду.
Після зміни змінних середовища або коду потрібно створити новий деплой.