Jak opravit chybějící hlavičku CORS Access-Control-Allow-Origin v Express.js

Pokud prohlížeč hlásí CORS header 'Access-Control-Allow-Origin' missing, klíčovou nápovědou není to, že Express.js nepřijal požadavek. Prohlížeč vám říká, že odpověď neobsahovala hlavičku CORS, která by oprávnila původ stránky k přečtení této odpovědi. Oprava proto patří na server nebo proxy, kterou kontrolujete, nikoli do náhodného nastavení na straně klienta.

Ilustrativní příklad používaný v této příručce: představte si dashboard úkolů běžící na http://localhost:5173, který volá Express API na http://localhost:3000/api/tasks. Prohlížeč blokuje JavaScriptu čtení odpovědi API, protože API nevrací hlavičku Access-Control-Allow-Origin. Jedná se o hypotetický výukový příklad, nikoli o tvrzení o reálném testu, produktu nebo nasazení.

Jak bylo ověřeno 11. září 2026, oficiální dokumentace middleware CORS pro Express uvádí verzi cors 2.8.6 a popisuje ji jako middleware, který nastavuje hlavičky odpovědi CORS. Aktuální seznam balíčků Express je v generaci 5.x, tato příručka proto upřednostňuje middleware na úrovni aplikace místo spoléhání se na starší vzory wildcard rout.

Co tato chyba ve skutečnosti znamená

Webová stránka má původ (origin) tvořený schématem, hostitelem a portem. V příkladu jsou http://localhost:5173 a http://localhost:3000 různé původy, protože se liší jejich porty. Politika stejného původu (same-origin policy) prohlížeče obvykle brání JavaScriptu na jednom původu číst zdroje z jiného, pokud cílový server nevrátí vhodné hlavičky Cross-Origin Resource Sharing (CORS).

Dokumentace MDN pro tuto přesnou chybu vysvětluje, že odpovědi chybí povinná hlavička Access-Control-Allow-Origin. Pokud kontrolujete server, měli byste nastavit původ požadujícího webu jako povolený původ. Pro veřejná API bez přihlašovacích údajů může být vhodné *; pro soukromá nebo přihlašovaná API použijte místo toho konkrétní důvěryhodné původy. Viz vysvětlení chyby chybějící Access-Control-Allow-Origin na MDN.

Krok 1: Potvrďte, že problém je CORS, a identifikujte přesný původ

Otevřete vývojářské nástroje prohlížeče a zkontrolujte panely Console i Network. Zaznamenejte původ frontendu přesně tak, jak ho odesílá prohlížeč. V našem ilustrativním případě je to http://localhost:5173.

Neredukujte původ pouze na hostname. Tyto jsou různé původy: http://localhost:5173, http://localhost:3000, http://127.0.0.1:5173 a https://localhost:5173. Seznam povolených původů (allowlist) v produkci musí rovněž rozlišovat https://app.example.com od jiných schémat, hostitelů, portů nebo subdomén, pokud je záměrně nepovolíte.

Pokud je odpovědí API 404, 500, přesměrování, selhání autentizace nebo chybová stránka generovaná proxy, zkontrolujte i tuto odpověď. Hlavičky CORS musí být přítomny v odpovědi, kterou prohlížeč skutečně obdrží. Oprava aplikační routy nepomůže, pokud reverzní proxy, CDN, load balancer nebo obsluha chyb vrátí jinou odpověď bez této hlavičky.

Krok 2: Nainstalujte a načtěte oficiální middleware CORS pro Express

Pro většinu aplikací Express je nejméně chybovým řešením middleware cors spravovaný projektem Express. Oficiální stránka middleware Expressu jej uvádí mezi middleware spravovaný týmem Express.js. Nainstalujte ho ve svém API projektu:

npm install cors

Poté ho načtěte vedle Expressu:

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

const app = express();

Oficiální dokumentace je dostupná na dokumentaci middleware cors pro Express.js. Express také dokumentuje, jak middleware na úrovni aplikace běží v pořadí požadavků, na Express.js: Používání middleware.

Krok 3: Úmyslně povolte původ frontendu

Pro hypotetický dashboard nakonfigurujte přesný vývojový původ před routami, které potřebují 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);

Umístění app.use(cors(corsOptions)) před routy API je důležité, protože Express zpracovává middleware v pořadí. Middleware potřebuje příležitost přidat hlavičky odpovědi dříve, než routa nebo předchozí middleware ukončí požadavek.

Pro skutečně veřejné API, které nepoužívá přihlašovací údaje, používá app.use(cors()) výchozí permisivní chování middleware pro původ. To je pohodlné, ale nemělo by to být vaše automatická volba pro produkci. MDN doporučuje omezit Access-Control-Allow-Origin na minimální počet původů a zdrojů, které jsou potřeba. Viz bezpečnostní doporučení MDN pro CORS.

Povolte několik známých původů bez povolení všem

Běžné produkční nastavení má lokální frontend, staging frontend a produkční frontend. Použijte allowlist a validujte příchozí 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));

Větev !origin povoluje klienty, kteří neodesílají hlavičku Origin, jako je mnoho požadavků server-to-server a nástrojů příkazového řádku. To, zda toto chování chcete, je rozhodnutí aplikační politiky; CORS samo o sobě není autentizace.

Krok 4: Ověřte jednoduchý požadavek a případný preflight

Načtěte znovu frontend a zkontrolujte panel Network. Podmínkou úspěchu není pouze stav 200. Zkontrolujte hlavičky odpovědi. V našem ilustrativním případě by odpověď API měla obsahovat hodnotu původu ekvivalentní:

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

Některé cross-origin požadavky spouštějí preflight: prohlížeč před skutečným požadavkem odešle požadavek OPTIONS, aby zkontroloval, zda jsou povoleny metoda a hlavičky. Požadavky používající metody jako PUT nebo DELETE, nebo určité vlastní/požadované hlavičky, obvykle potřebují preflight. Když je cors nainstalován jako middleware na úrovni aplikace pomocí app.use(cors(...)), oficiální dokumentace Expressu uvádí, že preflight požadavky jsou zpracovávány pro všechny routy.

Hlavičky můžete zkontrolovat i mimo prohlížeč, aniž byste tvrdili, že klient příkazového řádku vynucuje CORS:

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

To je užitečné pro zjištění, co server vrací, ale úspěšný požadavek curl nebo API klienta nedokazuje, že je CORS v prohlížeči správně nakonfigurován. Dokumentace CORS pro Express explicitně uvádí, že CORS je vynucováno prohlížeči; nebrowseroví klienti neuplatňují stejné omezení čtení.

Požadavky s přihlašovacími údaji: nekombinujte přihlašovací údaje s wildcard původem

Pokud musí frontend posílat cookies nebo HTTP autentizaci cross-origin, obě strany potřebují kompatibilní nastavení. Na straně Expressu nakonfigurujte konkrétní důvěryhodný původ a povolte přihlašovací údaje:

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

Na straně prohlížeče požadavek fetch, který potřebuje cookies, obvykle používá credentials: 'include'. Nepřepínejte původ serveru na * pro požadavek s přihlašovacími údaji. Prohlížeče neakceptují wildcard Access-Control-Allow-Origin spolu s CORS s přihlašovacími údaji způsobem, který vývojáři často očekávají, a neomezený původ by byl také špatnou bezpečnostní hranicí.

Proč běžná „řešení“ selhávají

Když kód Express vypadá správně, ale chyba přetrvává

Pokud čtyři výše uvedené kroky nevyřeší chybu, sledujte celou cestu požadavku, místo abyste slepě přidávali další hlavičky.

• Zkontrolujte pořadí middleware. Middleware CORS by měl běžet před routami nebo obsluhami, které ukončují odpověď.
• Zkontrolujte přesměrování. Prohlížeč může po přesměrování obdržet odpověď z jiné URL nebo původu.
• Zkontrolujte chování proxy/CDN. Nginx, gateway, serverless platforma nebo CDN mohou přidávat, odstraňovat, duplikovat nebo nahrazovat hlavičky.
• Zkontrolujte chybové odpovědi. Normální odpověď 200 může obsahovat hlavičky CORS, zatímco odpověď 401, 404 nebo 500 ne.
• Zkontrolujte doslovný původ. Schéma, hostname a port jsou všechny důležité; localhost a 127.0.0.1 nejsou pro shodu CORS zaměnitelné.
• Zkontrolujte duplicitní hlavičky. MDN dokumentuje, že více hlaviček Access-Control-Allow-Origin není povoleno. Viz MDN o více hlavičkách Access-Control-Allow-Origin.

Manuální hlavičky versus middleware cors

Hlavičky CORS můžete nastavit ručně pomocí API odpovědí Expressu, ale je snadné přehlédnout chování preflight, pravidla pro přihlašovací údaje, dynamické shody původů, Vary: Origin nebo cesty chyb. Oficiální middleware cors již nabízí možnosti pro origin, metody, povolené hlavičky, vystavené hlavičky, přihlašovací údaje, chování preflight a max age. Pro většinu projektů Express udržuje použití tohoto middleware politiku explicitní a snáze přezkoumatelnou.

Pokud implementujete dynamickou logiku původů sami, nikdy automaticky neodrážejte každou příchozí hodnotu Origin jen proto, že je přítomna. Validujte ji proti důvěryhodné množině. MDN varuje, že neomezené cross-origin čtení může odhalit data, zejména když jsou zapojeny přihlašovací údaje.

Praktický produkční kontrolní seznam

• Uveďte přesné původy frontendu, které by měly mít přístup ke čtení API.
• V produkci používejte původy HTTPS a udržujte vývojové původy oddělené.
• Nainstalujte middleware CORS před chráněné routy API, které ho potřebují.
• Pro soukromé nebo přihlašované endpointy používejte konkrétní původy.
• V prohlížeči ověřte jak normální odpovědi, tak odpovědi preflight OPTIONS.
• Ověřte cesty selhání, jako jsou odpovědi 401, 404 a 500, pokud mohou být vráceny cross-origin.
• Chápejte CORS jako politiku čtení prohlížeče, nikoli jako autentizaci nebo autorizaci.

V ilustrativním scénáři dashboardu úkolů je trvalá oprava přímočará: identifikujte přesný původ frontendu, nakonfigurujte Express tak, aby vracel odpovídající hlavičku CORS, nechte middleware na úrovni aplikace zpracovat preflight a ověřte hlavičky v odpovědi, kterou prohlížeč skutečně obdrží. Pokud hlavička stále chybí, dalším podezřelým je obvykle pořadí middleware nebo infrastruktura mezi prohlížečem a Express, nikoli samotné volání fetch na frontendu.

Oficiální odkazy

• Dokumentace middleware cors pro Express.js — konfigurační možnosti, dynamické původy, přihlašovací údaje a chování preflight.
• Průvodce middleware Express.js — middleware aplikace a pořadí zpracování požadavků.
• MDN: Chybí hlavička CORS Access-Control-Allow-Origin — význam této specifické chyby prohlížeče.
• Průvodce bezpečnostní konfigurací CORS na MDN — doporučení pro omezení povolených původů a zpracování přístupu s přihlašovacími údaji.