Пошук уроків, статей та іншого контенту
Навчитеся діагностувати типові проблеми після deployment: 404, змінні середовища, кеш, порти та помилки збірки.
Після deployment проблема часто виникає не в коді як такому, а в різниці між локальним і production-середовищем:
інший режим запуску;
інші змінні середовища;
інша операційна система;
кеш браузера або CDN;
інший порт чи спосіб маршрутизації;
помилка під час збірки, яку не було помітно локально.
Зручно перевіряти проблему в такому порядку:
Переконатися, що deployment завершився успішно.
Переглянути логи запуску застосунку.
Перевірити адресу, порт і маршрути.
Перевірити змінні середовища.
Виконати production-збірку локально.
Відкинути проблеми з кешем.
Помилка 404 Not Found означає, що сервер не знайшов ресурс за вказаною адресою. У Next.js найчастіші причини такі:
відкрито неправильний URL;
файл маршруту лежить не в тій директорії;
deployment виконується не з того проєкту або гілки;
маршрут доступний лише за іншого basePath;
платформа неправильно налаштувала маршрутизацію.
Для App Router маршрут /about має відповідати такій структурі:
app/
├── about/
│ └── page.tsx
└── page.tsxДля Pages Router той самий маршрут має виглядати так:
pages/
├── about.tsx
└── index.tsxВажливо враховувати регістр символів. У Linux шлях About і шлях about — різні. Код, який працює на файловій системі без чутливості до регістру, може зламатися після deployment.
basePathЯкщо в next.config.js задано:
/** @type {import('next').NextConfig} */
const nextConfig = {
basePath: "/app",
};
module.exports = nextConfig;то сторінка /about буде доступна за адресою:
/app/aboutПосилання, зображення та запити також повинні враховувати цей префікс. Якщо застосунок розгорнуто в корені домену, але конфігурація очікує /app, частина адрес може повертати 404.
Якщо проєкт використовує:
const nextConfig = {
output: "export",
};
module.exports = nextConfig;результатом є набір статичних файлів. У такому режимі серверні можливості Next.js, зокрема API Routes і серверна логіка, недоступні як звичайні серверні endpoints.
Тому потрібно перевірити, чи deployment справді підтримує той тип застосунку, який було зібрано:
статичний export має роздаватися як статичні файли;
серверний Next.js-застосунок має запускатися через production-сервер.
Локально змінні часто зберігаються у .env.local. Цей файл зазвичай не додають до Git, тому після deployment його вміст автоматично не з’являється на сервері.
На платформі deployment змінні потрібно додати окремо в налаштуваннях проєкту.
Змінна без префікса NEXT_PUBLIC_ доступна лише серверному коду:
DATABASE_URL=postgresql://...Змінна з префіксом NEXT_PUBLIC_ може потрапити до клієнтського JavaScript:
NEXT_PUBLIC_API_URL=https://api.example.comНе можна використовувати NEXT_PUBLIC_ для паролів, токенів і ключів доступу. Значення такої змінної вважається доступним користувачу браузера.
Зміна змінної середовища не завжди впливає на вже зібрані файли. Особливо це важливо для NEXT_PUBLIC_*: їхні значення можуть бути вставлені під час build.
Після зміни змінних потрібно:
зберегти налаштування на платформі;
запустити новий deployment;
перевірити логи збірки;
оновити сторінку без старого кешу.
Для перевірки наявності серверної змінної можна тимчасово створити endpoint:
// app/api/health/route.ts
import { NextResponse } from "next/server";
export const dynamic = "force-dynamic";
export function GET() {
const hasDatabaseUrl = Boolean(process.env.DATABASE_URL);
if (!hasDatabaseUrl) {
return NextResponse.json(
{
ok: false,
error: "DATABASE_URL не налаштовано",
},
{ status: 503 },
);
}
return NextResponse.json(
{ ok: true },
{
headers: {
"Cache-Control": "no-store",
},
},
);
}Після deployment endpoint можна перевірити запитом:
curl -i https://example.com/api/healthТакий endpoint не повертає саме значення секрету, а лише перевіряє його наявність. Не залишайте детальні діагностичні endpoints у production без потреби або захисту доступу.
Після успішного deployment браузер або CDN може повертати стару версію сторінки. Це створює враження, що deployment не спрацював.
Можливі джерела кешу:
кеш браузера;
CDN або reverse proxy;
кеш відповідей API;
кеш даних Next.js;
старий HTML, який посилається на попередні ресурси.
Перевірте сторінку:
у приватному вікні браузера;
в іншому браузері;
через curl;
з вимкненим кешем у DevTools.
Наприклад:
curl -i -H "Cache-Control: no-cache" https://example.com/api/healthЯкщо curl повертає нову відповідь, а звичайний браузер показує стару, проблема, ймовірно, пов’язана з кешем.
Для даних, які не можна кешувати, запит можна виконати з опцією no-store:
const response = await fetch("https://api.example.com/profile", {
cache: "no-store",
});
const profile = await response.json();Це доречно для даних, які повинні бути актуальними для кожного запиту. Для даних, які рідко змінюються, кешування може бути бажаним.
Після зміни кешованої логіки перевіряйте не лише вихідний код, а й:
заголовки відповіді;
час створення даних;
поведінку після нового deployment;
наявність інвалідації кешу на платформі.
На локальному комп’ютері застосунок часто запускається на порту 3000. У production-платформі порт може передаватися через змінну PORT.
Для стандартного Next.js production-запуску в package.json зазвичай достатньо:
{
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start"
}
}Запуск:
npm run build
npm run startNext.js використовує production-порт, переданий середовищем або параметром командного рядка:
npm run start -- -p 8080Типові помилки:
production-команда запускає лише next dev;
застосунок слухає інший порт, ніж очікує платформа;
у Docker порт усередині контейнера не збігається з опублікованим портом;
процес завершився одразу після запуску;
платформа очікує HTTP-сервер, а deployment містить лише статичні файли.
Потрібно дивитися не лише на повідомлення в браузері, а й на логи процесу. Якщо порт зайнятий або сервер не запустився, це буде видно саме в логах.
У production deployment спочатку виконується build. Якщо build завершився з помилкою, нова версія не буде запущена.
Найпоширеніші причини:
помилка TypeScript;
помилка ESLint, якщо вона блокує build;
відсутній пакет у dependencies;
імпорт файлу з неправильним регістром;
відсутня змінна середовища під час build;
несумісна версія Node.js;
розбіжність між lock-файлом і package.json;
код працює в dev, але не проходить production-збірку.
Перевіряйте deployment локально тією самою послідовністю:
rm -rf .next
npm ci
npm run build
npm run startnpm ci встановлює залежності на основі lock-файлу. Це допомагає виявити ситуації, коли локальна папка node_modules містить пакети, яких немає в чистому deployment-середовищі.
Якщо проєкт використовує іншу версію Node.js на платформі, зафіксуйте її в package.json:
{
"engines": {
"node": "22.x"
}
}Конкретна версія має відповідати тій, яку підтримує ваша платформа та використовує команда.
Команда next dev не є перевіркою production-збірки. У режимі розробки Next.js може:
компілювати модулі за потреби;
показувати детальніші помилки;
використовувати локальні змінні;
не виявляти частину проблем із чистим встановленням залежностей.
Тому обов’язково перевіряйте саме:
npm run build
npm run startПеревірте повну адресу та шлях.
Перевірте структуру app або pages.
Перевірте регістр назв файлів і директорій.
Перевірте basePath і налаштування статичного export.
Переконайтеся, що deployment створено з потрібної гілки та проєкту.
Перегляньте логи та результат build.
Перевірте назву змінної.
Переконайтеся, що вона додана на платформі deployment.
Визначте, де вона використовується: на сервері чи в браузері.
Для клієнтського коду перевірте префікс NEXT_PUBLIC_.
Запустіть новий deployment після зміни змінної.
Не виводьте значення секрету в HTML або логи.
Перевірте deployment-лог і commit.
Відкрийте сайт у приватному вікні.
Перевірте відповідь через curl.
Перевірте заголовки кешування.
Очистьте або інвалідуйте кеш CDN, якщо це передбачено платформою.
Перевірте кешування даних у серверному коді.
Перевірте, чи успішно завершився next build.
Перевірте команду start.
Перевірте змінну PORT.
Перегляньте runtime-логи.
Локально виконайте npm ci, npm run build і npm run start.
Перевірте версію Node.js та наявність усіх production-залежностей.
Перевіряти лише dev-режим і не запускати next build.
Додавати .env.local до репозиторію замість налаштування змінних на платформі.
Використовувати NEXT_PUBLIC_ для секретних значень.
Змінити змінну середовища, але не виконати новий deployment.
Вважати будь-яку 404 помилкою Next.js, не перевіривши URL, basePath і структуру файлів.
Запускати застосунок на жорстко заданому порту, який не використовує платформа.
Діагностувати кеш лише через один браузер.
Ігнорувати регістр назв файлів, якщо локальна система не показує проблеми.
Припускати, що успішний build означає успішний запуск: runtime-помилки можуть виникнути вже після build.
Додавати в діагностичні відповіді значення токенів, паролів або рядків підключення до бази даних.
Після deployment проблеми Next.js найчастіше пов’язані з п’ятьма категоріями:
404 — неправильний шлях, структура маршруту, basePath або тип deployment;
змінні середовища — вони мають бути налаштовані на платформі, а публічні значення потребують нового build;
кеш — стара відповідь може надходити від браузера, CDN або серверного кешу;
порти — production-сервер має слухати порт, який очікує платформа;
помилки збірки — їх потрібно відтворювати через чисте встановлення залежностей і npm run build.
Найнадійніший спосіб діагностики — порівняти локальний production-запуск, логи deployment і фактичні HTTP-відповіді застосунку.