Ako opraviť chýbajúci CORS hlavičku Access-Control-Allow-Origin v Express.js

Ak prehliadač hlási CORS header 'Access-Control-Allow-Origin' missing, dôležitou stopou nie je to, že Express.js nedokázal prijať požiadavku. Prehliadač vám hovorí, že odpoveď neobsahovala CORS hlavičku, ktorá by oprávnila pôvod stránky na čítanie tejto odpovede. Oprava preto patrí na server alebo na proxy, ktoré ovládate, nie do náhodného nastavenia na strane klienta.

Ilustratívny príklad použitý v tejto príručke: predstavte si dashboard úloh bežiaci na adrese http://localhost:5173, ktorý volá Express API na adrese http://localhost:3000/api/tasks. Prehliadač blokuje JavaScriptu čítanie odpovede API, pretože API nevracia hlavičku Access-Control-Allow-Origin. Toto je hypotetický výukový príklad, nie tvrdenie o reálnom teste, produkte alebo nasadení.

Podľa overenia z 11. septembra 2026 oficiálna dokumentácia middleware CORS pre Express uvádza verziu cors 2.8.6 a opisuje ju ako middleware, ktorý nastavuje CORS hlavičky odpovede. Aktuálne zoznamy balíkov Express sú v generácii 5.x, preto táto príručka uprednostňuje middleware na úrovni aplikácie namiesto spoliehania sa na staršie vzory wildcard rout.

Čo táto chyba skutočne znamená

Webová stránka má pôvod (origin) tvorený jej schémou, hostiteľom a portom. V príklade sú http://localhost:5173 a http://localhost:3000 rôzne pôvody, pretože sa líšia ich porty. Politika rovnakého pôvodu v prehliadači zvyčajne bráni JavaScriptu na jednom pôvode čítať zdroje z iného, pokiaľ cieľový server nevráti vhodné hlavičky Cross-Origin Resource Sharing (CORS).

Dokumentácia MDN pre túto konkrétnu chybu vysvetľuje, že odpovedi chýba požadovaná hlavička Access-Control-Allow-Origin. Ak ovládate server, mali by ste nastaviť pôvod požadujúcej stránky ako povolený pôvod. Pre verejné API bez poverení môže byť vhodné *; pre súkromné alebo poverené API používajte namiesto toho konkrétne dôveryhodné pôvody. Pozri vysvetlenie chyby chýbajúcej Access-Control-Allow-Origin na MDN.

Krok 1: Potvrďte, že problémom je CORS, a identifikujte presný pôvod

Otvorte vývojárske nástroje prehliadača a skontrolujte panely Console aj Network. Presne zaznamenajte pôvod frontendu tak, ako ho odosiela prehliadač. V našom ilustračnom prípade je to http://localhost:5173.

Neredukujte pôvod len na hostname. Tieto sú rôzne pôvody: http://localhost:5173, http://localhost:3000, http://127.0.0.1:5173 a https://localhost:5173. Allowlist v produkcii musí likewise rozlišovať https://app.example.com od iných schém, hostiteľov, portov alebo subdomén, pokiaľ ich zámerne nepovoľujete.

Ak je odpoveďou API 404, 500, presmerovanie, zlyhanie autentizácie alebo chybová stránka generovaná proxy, skontrolujte aj túto odpoveď. CORS hlavičky musia byť prítomné v odpovedi, ktorú prehliadač skutočne prijme. Oprava aplikačnej routy nepomôže, ak reverse proxy, CDN, load balancer alebo obsluha chýb vráti inú odpoveď bez hlavičky.

Krok 2: Nainštalujte a načítajte oficiálny Express CORS middleware

Pre väčšinu aplikácií Express je najmenej chybové riešenie middleware cors udržiavaný projektom Express. Oficiálna stránka middleware Expressu ho uvádza medzi middleware udržiavaný tímom Express.js. Nainštalujte ho vo vašom API projekte:

npm install cors

Potom ho načítajte vedľa Expressu:

const express = require('express');
const cors = require('cors');

const app = express();

Oficiálna dokumentácia je dostupná na dokumentácii middleware cors pre Express.js. Express tiež dokumentuje, ako middleware na úrovni aplikácie beží v poradí požiadaviek na Express.js: Používanie middleware.

Krok 3: Úmyselne povoľte pôvod frontendu

Pre hypotetický dashboard nakonfigurujte presný vývojový pôvod pred routami, ktoré potrebujú CORS:

const express = require('express');
const cors = require('cors');

const app = express();

const corsOptions = {
  origin: 'http://localhost:5173'
};

app.use(cors(corsOptions));
app.use(express.json());

app.get('/api/tasks', (req, res) => {
  res.json({ tasks: ['Learn Express', 'Build API'] });
});

app.listen(3000);

Umiestnenie app.use(cors(corsOptions)) pred routy API je dôležité, pretože Express spracováva middleware v poradí. Middleware potrebuje šancu pridať hlavičky odpovede skôr, než routa alebo skorší middleware ukončí požiadavku.

Pre skutočne verejné API, ktoré nepoužíva poverenia, app.use(cors()) používa predvolené permisívne správanie middlewareu pre pôvod. To je pohodlné, ale nemalo by byť vaším automatickým voľbou v produkcii. MDN odporúča obmedziť Access-Control-Allow-Origin na minimálne potrebné pôvody a zdroje. Pozri bezpečnostné usmernenia MDN pre CORS.

Povoľte niekoľko známych pôvodov bez toho, aby ste povolili všetkých

Bežná produkčná konfigurácia má lokálny frontend, staging frontend a produkčný frontend. Použite allowlist a validujte prichádzajúci pôvod:

const allowedOrigins = new Set([
  'http://localhost:5173',
  'https://staging.example.com',
  'https://app.example.com'
]);

const corsOptions = {
  origin(origin, callback) {
    if (!origin || allowedOrigins.has(origin)) {
      callback(null, true);
      return;
    }
    callback(new Error('Origin not allowed by CORS'));
  }
};

app.use(cors(corsOptions));

Vetva !origin povoľuje klientov, ktorí neodosielajú hlavičku Origin, ako je to pri mnohých požiadavkách server-to-server a nástrojoch príkazového riadku. To, či chcete toto správanie, je rozhodnutím aplikačnej politiky; CORS sám o sebe nie je autentizácia.

Krok 4: Overte jednoduchú požiadavku a prípadnú predbežnú požiadavku (preflight)

Znovu načítajte frontend a skontrolujte panel Network. Podmienkou úspechu nie je len stav 200. Skontrolujte hlavičky odpovede. V našom ilustračnom prípade by odpoveď API mala obsahovať hodnotu pôvodu ekvivalentnú:

Access-Control-Allow-Origin: http://localhost:5173

Niektoré cross-origin požiadavky spúšťajú predbežnú požiadavku (preflight): prehliadač pošle požiadavku OPTIONS pred skutočnou požiadavkou, aby skontroloval, či sú metóda a hlavičky povolené. Požiadavky používajúce metódy ako PUT alebo DELETE, alebo určité vlastné/žiadané hlavičky, zvyčajne potrebujú preflight. Keď je cors nainštalovaný ako middleware na úrovni aplikácie pomocou app.use(cors(...)), oficiálna dokumentácia Expressu uvádza, že predbežné požiadavky sú spracované pre všetky routy.

Hlavičky môžete skontrolovať aj mimo prehliadača bez toho, aby ste tvrdili, že klient príkazového riadku vynucuje CORS:

curl -i   -H "Origin: http://localhost:5173"   http://localhost:3000/api/tasks

To je užitočné na zistenie, čo server vracia, ale úspešná požiadavka curl alebo API klienta nedokazuje, že je CORS v prehliadači správne nakonfigurovaný. Dokumentácia CORS pre Express explicitne uvádza, že CORS je vynucovaný prehliadačmi; nebrowseroví klienti neuplatňujú rovnaké obmedzenie čítania.

Poverené požiadavky: nekombinujte poverenia s wildcard pôvodom

Ak musí frontend posielať cookies alebo HTTP autentizáciu cross-origin, obe strany potrebujú kompatibilné nastavenia. Na strane Expressu nakonfigurujte konkrétny dôveryhodný pôvod a povoľte poverenia:

app.use(cors({
  origin: 'https://app.example.com',
  credentials: true
}));

Na strane prehliadača požiadavka fetch, ktorá potrebuje cookies, zvyčajne používa credentials: 'include'. Neprepínajte pôvod servera na * pre poverenú požiadavku. Prehliadače neakceptujú wildcard Access-Control-Allow-Origin spolu s povereným CORS spôsobom, ktorý vývojári často očakávajú, a neobmedzený pôvod by bol tiež slabou bezpečnostnou hranicou.

Prečo bežné „opravy“ zlyhávajú

Kedy vyzerá kód Expressu správne, ale chyba pretrváva

Ak štyri vyššie uvedené kroky nevyriešia chybu, sledujte celú cestu požiadavky namiesto slepého pridávania ďalších hlavičiek.

• Skontrolujte poradie middleware. CORS middleware by mal bežať pred routami alebo handlermi, ktoré ukončujú odpoveď.
• Skontrolujte presmerovania. Prehliadač môže prijímať odpoveď z inej URL alebo pôvodu po presmerovaní.
• Skontrolujte správanie proxy/CDN. Nginx, gateway, serverless platforma alebo CDN môžu pridávať, odstraňovať, duplikovať alebo nahrádzať hlavičky.
• Skontrolujte chybové odpovede. Normálna odpoveď 200 môže obsahovať CORS hlavičky, zatiaľ čo odpoveď 401, 404 alebo 500 nie.
• Skontrolujte doslovný pôvod. Schéma, hostname a port sú dôležité; localhost a 127.0.0.1 nie sú zameniteľné pre párovanie CORS.
• Skontrolujte duplicitné hlavičky. MDN dokumentuje, že viacero hlavičiek Access-Control-Allow-Origin nie je povolených. Pozri MDN o viacerých hlavičkách Access-Control-Allow-Origin.

Manuálne hlavičky versus middleware cors

CORS hlavičky môžete nastaviť manuálne pomocou API odpovedí Expressu, ale je ľahké prehliadnuť správanie preflight, pravidlá poverení, dynamické párovanie pôvodov, Vary: Origin alebo cesty chýb. Oficiálny middleware cors už ponúka možnosti pre origin, metódy, povolené hlavičky, vystavené hlavičky, poverenia, správanie preflight a max age. Pre väčšinu projektov Express používanie tohto middlewareu udržiava politiku explicitnú a ľahšie preskúmateľnú.

Ak implementujete dynamickú logiku pôvodov sami, nikdy automaticky neodrážajte každú prichádzajúcu hodnotu Origin len preto, že je prítomná. Validujte ju proti dôveryhodnej množine. MDN varuje, že neobmedzené cross-origin čítania môžu odhaliť dáta, najmä keď sú zapojené poverenia.

Praktický produkčný kontrolný zoznam

• Zoznam presných pôvodov frontendu, ktoré by mali byť schopné čítať API.
• V produkcii používajte HTTPS pôvody a udržujte vývojové pôvody oddelené.
• Nainštalujte CORS middleware pred chránené routy API, ktoré ho potrebujú.
• Pre súkromné alebo poverené endpointy používajte konkrétne pôvody.
• V prehliadači overte normálne odpovede aj odpovede predbežných požiadaviek OPTIONS.
• Overte cesty zlyhania, ako sú odpovede 401, 404 a 500, ak môžu byť vrátené cross-origin.
• Považujte CORS za politiku čítania prehliadača, nie za autentizáciu alebo autorizáciu.

V ilustračnom scenári dashboardu úloh je trvalá oprava priamočiara: identifikujte presný pôvod frontendu, nakonfigurujte Express tak, aby vracal zodpovedajúcu CORS hlavičku, nechajte middleware na úrovni aplikácie spracovať preflight a overte hlavičky v odpovedi, ktorú prehliadač skutočne prijíma. Ak hlavička stále chýba aj potom, ďalším podozrivým je zvyčajne poradie middleware alebo infraštruktúra medzi prehliadačom a Expressom, nie samotné volanie fetch na frontendu.

Oficiálne odkazy

• Dokumentácia middleware cors pre Express.js — konfiguračné možnosti, dynamické pôvody, poverenia a správanie preflight.
• Sprievodca middleware Express.js — middleware aplikácie a poradie spracovania požiadaviek.
• MDN: Chýbajúca CORS hlavička Access-Control-Allow-Origin — význam tejto konkrétnej chyby prehliadača.
• Sprievodca bezpečnostnou konfiguráciou CORS na MDN — usmernenia na obmedzenie povolených pôvodov a spracovanie povereného prístupu.