Kategoria: Vercel i hosting

Aplikacja działa lokalnie, na Vercel brak funkcji Node.js przy Edge Functions

Poradnik techniczny · Kacper Bernecki

Problem: kod, który używa natywnych API Node.js (np. filesystem, sockety, moduły binarne lub procesy potomne) działa lokalnie w środowisku Node, ale po wdrożeniu na Vercel kończy się błędem lub cichym brakiem efektów. Najczęstsza przyczyna to niezamierzone uruchomienie danej cząstki (endpointu, middleware, funkcji) w środowisku Edge (V8 Isolates) zamiast w runtime Node/Serverless. Edge Functions mają ograniczenia: brak pełnego API Node, brak dostępu do systemu plików i modułów binarnych oraz inne różnice zachowania. Trzeba rozróżnić: czy plik/endpoint został oznaczony jako Edge (np. przez eksplicytne ustawienie runtime lub przez wybór frameworka/konwencji), czy build/artifact został przeniesiony do innego typu funkcji podczas deployu. Ten dokument opisuje diagnostykę różnicową, konkretne kroki sprawdzające, warianty przyczyn i test naprawy, tak aby bez zgadywania ustalić, czy to limit Edge Functions czy błąd konfiguracji deploymentu.

Jak rozpoznać przyczynę

Sprawdź, czy dany endpoint jest faktycznie Edge Function: w Next.js to ustawienie runtime: 'edge' (np. eksport config runtime) lub użycie middleware/edge API; w Vercel Functions sprawdź, czy plik trafia do katalogu oznaczonego dla Edge. Jeśli runtime jest Edge, brak obsługi natywnych modułów Node jest oczekiwany.

Jeśli nie ma jawnego ustawienia Edge, zbadaj proces builda i output: logi deploya zawierają informację, czy konkretny plik został utworzony jako Edge Function czy jako Serverless Function. Różnica w zachowaniu może wynikać z automatycznej klasyfikacji przez builder (np. pliki w katalogu pages/api w Next.js mogą być mapowane różnie w zależności od wersji).

Rozwiązanie krok po kroku

1. Otwórz logi deploymentu w panelu Vercel dla konkretnego wdrożenia i znajdź wpisy dotyczące budowy funkcji; szukaj linii 'Edge Function' lub 'Serverless Function' przypisanej do twojego endpointu.

2. W kodzie źródłowym sprawdź, czy plik/endpoint zawiera jawne ustawienie runtime (np. export const config = { runtime: 'edge' } w Next.js) lub czy framework-dedykowane pliki (middleware, edge API) nie zostały użyte omyłkowo.

3. Uruchom prosty testowy endpoint na Vercel: utwórz najprostszy plik, który próbuje użyć process.version lub require('fs'), wdroż go i przeanalizuj odpowiedź oraz logi błędu — brak lub wyjątek wskaże ograniczenia środowiska.

4. Porównaj lokalny build: wygeneruj production build lokalnie (np. next build) i przejrzyj .vercel/output lub build manifest, aby ustalić, jak builder klasyfikuje tę funkcję przed wysłaniem na platformę.

5. Sprawdź ustawienia projektu w dashboardzie Vercel: czy wybrany target framework, ustawienia build & output, lub custom builders mogą przeklasyfikować funkcje na Edge. Skonfrontuj wersję buildera z dokumentacją.

6. Jeśli potrzebujesz Node API, zmień konfigurację tak, by endpoint trafił do runtime Node/Serverless: usuń deklarację Edge, przenieś kod do odpowiedniego katalogu/ścieżki akceptowanej jako Serverless Function i ponownie wdroż.

7. Po zmianie wdrożenia obserwuj logi i odpowiedzi, sprawdź czy importy natywnych modułów teraz przebiegają bez błędów; w razie problemów przeanalizuj błędy stack trace w logach deployu.

Jak sprawdzić, czy problem zniknął

Test 1: Wdróż testowy endpoint, który zwraca typeof process и process.version; jeśli otrzymasz wersję Node — endpoint działa w Node runtime, brak lub undefined oznacza Edge.

Test 2: Wdróż endpoint używający require('fs').readdirSync('.') — jeśli wywołanie zwraca listing plików, masz dostęp do filesystem; jeśli pojawi się błąd o braku modułu lub niedozwolonej operacji, działa Edge.

Czego nie robić

Nie zakładaj, że brak błędu w przeglądarce oznacza działanie Node — błędy mogą być swallowowane; zawsze sprawdź logi deploymentu i odpowiedź endpointu (status, body).

Nie próbuj używać modułów binarnych/child_process w Edge Functions; to nie kwestia konfiguracji, tylko ograniczeń runtime - migracja do Serverless/Node jest konieczna.