Hogyan javítsd a hiányzó Access-Control-Allow-Origin CORS fejlécet Express.js-ben

Ha a böngésző azt jelzi, hogy CORS header 'Access-Control-Allow-Origin' missing, a fontos utalás nem az, hogy az Express.js nem kapta meg a kérést. A böngésző azt közli veled, hogy a válasz nem tartalmazott olyan CORS fejlécet, amely engedélyezné az oldal originje számára a válasz elolvasását. A javítás tehát a szerveren vagy egy általad irányított proxy-n történik, nem pedig egy véletlenszerű kliensoldali beállításban.

Ebben az útmutatóban végig használt szemléltető példa: képzelj el egy feladatkezelő dashboardot, amely a http://localhost:5173 címen fut, és egy Express API-t hív meg a http://localhost:3000/api/tasks címen. A böngésző blokkolja a JavaScriptet az API válaszának elolvasásában, mert az API nem adja vissza az Access-Control-Allow-Origin fejlécet. Ez egy hipotetikus oktatási példa, nem valós teszt, termék vagy telepítés állítása.

2026. szeptember 11-i ellenőrzéskor a hivatalos Express CORS middleware dokumentációja a cors 2.8.6-os verzióját sorolja fel, és CORS válaszfejléceket beállító middleware-ként írja le. A jelenlegi Express csomaglista az 5.x generációban van, ezért ez az útmutató az alkalmazásszintű middleware-t részesíti előnyben a régebbi wildcard route minták helyett.

Mit jelent valójában a hiba

Egy weboldalnak van egy originje, amely a sémából, a hostból és a portból áll. A példában a http://localhost:5173 és a http://localhost:3000 különböző originök, mert a portjaik eltérnek. A böngésző same-origin policyja (azonos eredetű szabályzata) általában megakadályozza, hogy az egyik originen futó JavaScript elolvasson erőforrásokat egy másikról, hacsak a célkiszolgáló nem ad vissza megfelelő Cross-Origin Resource Sharing (CORS) fejléceket.

Az MDN dokumentációja ehhez a konkrét hibához azt magyarázza, hogy a válasz hiányos a szükséges Access-Control-Allow-Origin fejléccel. Ha te irányítod a szervert, akkor a kérést küldő oldal originjét engedélyezett originként kell konfigurálnod. Nyilvános, hitelesítés nélküli API-k esetén a * megfelelő lehet; privát vagy hitelesített API-k esetén használj specifikus megbízható originöket. Lásd: Az MDN magyarázata a hiányzó Access-Control-Allow-Origin hibáról.

1. lépés: Erősítsd meg, hogy a CORS a probléma, és azonosítsd a pontos originet

Nyisd meg a böngésző fejlesztői eszközeit, és ellenőrizd mind a Console (Konzol), mind a Network (Hálózat) panelt. Rögzítsd a frontend originjét pontosan úgy, ahogy a böngésző elküldi. A mi szemléltető esetünkben ez http://localhost:5173.

Ne egyszerűsítsd le az origint csak a hostname-re. Ezek különböző originök: http://localhost:5173, http://localhost:3000, http://127.0.0.1:5173 és https://localhost:5173. Egy éles (production) allowlistnak (engedélyezési listának) hasonlóan meg kell különböztetnie a https://app.example.com-ot más sémáktól, hostoktól, portoktól vagy aldomainektől, hacsak nem szándékosan engedélyezed őket.

Ha az API válasz 404, 500, átirányítás, hitelesítési hiba vagy proxy által generált hibaoldal, azt a választ is vizsgáld meg. A CORS fejléceknek jelen kell lenniük azon a válaszon, amelyet a böngésző ténylegesen megkap. Az alkalmazás route-jának javítása nem segít, ha egy reverse proxy, CDN, terheléselosztó vagy hibakezelő egy másik választ ad vissza a fejléc nélkül.

2. lépés: Telepítsd és töltsd be a hivatalos Express CORS middleware-t

A legtöbb Express alkalmazás esetén a legkevesebb hibalehetőséggel járó megoldás az Express projekt által karbantartott cors middleware. A hivatalos Express middleware oldal felsorolja azt az Express.js csapat által karbantartott middleware-ek között. Telepítsd az API projektedben:

npm install cors

Ezután töltsd be az Express mellett:

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

const app = express();

A hivatalos dokumentáció itt érhető el: Express.js cors middleware dokumentáció. Az Express azt is dokumentálja, hogy az alkalmazásszintű middleware hogyan fut a kérések sorrendjében itt: Express.js: Middleware használata.

3. lépés: Engedélyezd szándékosan a frontend originjét

A hipotetikus dashboardhoz konfiguráld a pontos fejlesztői origint azok előtt a route-ok előtt, amelyeknek CORS-ra van szükségük:

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);

Fontos, hogy az app.use(cors(corsOptions)) az API route-ok előtt legyen, mert az Express a middleware-eket sorrendben dolgozza fel. A middleware-nek lehetőséget kell kapnia a válaszfejlécek hozzáadására, mielőtt egy route vagy korábbi middleware befejezné a kérést.

Egy valóban nyilvános API esetén, amely nem használ hitelesítést, az app.use(cors()) a middleware alapértelmezett engedékeny origin viselkedését használja. Ez kényelmes, de nem ez kellene, hogy legyen az automatikus éles (production) választásod. Az MDN azt javasolja, hogy korlátozd az Access-Control-Allow-Origin-t a minimálisan szükséges originökre és erőforrásokra. Lásd: Az MDN CORS biztonsági útmutatója.

Több ismert origin engedélyezése anélkül, hogy mindenkinek engedélyeznéd

Egy gyakori éles (production) beállításban van egy helyi frontend, egy staging frontend és egy éles frontend. Használj allowlistot és validáld a bejövő origint:

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));

A !origin ág engedélyezi azokat a klienseket, amelyek nem küldenek Origin fejlécet, mint például sok szerver-szerver közötti kérés és parancssori eszköz. Az, hogy ezt a viselkedést szeretnéd-e, alkalmazási szabályozási döntés; a CORS önmagában nem hitelesítés.

4. lépés: Ellenőrizd az egyszerű kérést és bármely preflight kérést

Töltsd újra a frontendet és vizsgáld meg a Network panelt. A siker feltétele nem csupán egy 200-as státusz. Ellenőrizd a válaszfejléceket. A mi szemléltető esetünkben az API válasznak tartalmaznia kell egy olyan origin értéket, amely egyenértékű ezzel:

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

Egyes cross-origin kérések preflight kérést indítanak: a böngésző egy OPTIONS kérést küld a valódi kérés előtt, hogy ellenőrizze, engedélyezettek-e a módszer és a fejlécek. Az olyan módszereket használó kérések, mint a PUT vagy DELETE, vagy bizonyos egyedi/kérés fejlécek, gyakran igényelnek preflight kérést. Amikor a cors-t alkalmazásszintű middleware-ként telepíted az app.use(cors(...)) segítségével, a hivatalos Express dokumentáció szerint a preflight kérések minden route-ra kezelve vannak.

A fejléceket a böngészőn kívül is megvizsgálhatod anélkül, hogy azt állítanád, hogy a parancssori kliens kikényszeríti a CORS-t:

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

Ez hasznos annak megtekintésére, hogy a szerver mit ad vissza, de egy sikeres curl vagy API-kliens kérés nem bizonyítja, hogy a böngésző CORS konfigurációja helyes. Az Express CORS dokumentációja kifejezetten megjegyzi, hogy a CORS-ot a böngészők kényszerítik ki; a nem böngésző alapú kliensek nem alkalmazzák ugyanazt az olvasási korlátozást.

Hitelesített kérések: ne kombináld a hitelesítést wildcard originnel

Ha a frontendnek cookie-kat vagy HTTP hitelesítést kell küldenie cross-origin módon, mindkét oldalnak kompatibilis beállításokra van szüksége. Az Express oldalon konfigurálj egy specifikus megbízható origint és engedélyezd a hitelesítést:

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

A böngésző oldalon egy fetch kérés, amelynek cookie-kra van szüksége, általában a credentials: 'include' opciót használja. Ne váltsd át a szerver originjét *-ra hitelesített kérés esetén. A böngészők nem fogadnak el wildcard Access-Control-Allow-Origin-t hitelesített CORS-szal együtt úgy, ahogy a fejlesztők gyakran várják, és egy korlátlan origin rossz biztonsági határ lenne.

Miért buknak el a gyakori „javítások”

Amikor az Express kód helyesnek tűnik, de a hiba továbbra is fennáll

Ha a fenti négy lépés nem oldja meg a hibát, kövesd végig a teljes kérésútvonalat ahelyett, hogy vakon több fejlécet adnál hozzá.

• Ellenőrizd a middleware sorrendet. A CORS middleware-nek a route-ok vagy a választ befejező handler-ek előtt kell futnia.
• Ellenőrizd az átirányításokat. A böngésző átirányítás után egy másik URL-ről vagy originről kaphat választ.
• Ellenőrizd a proxy/CDN viselkedését. Az Nginx, egy gateway, egy serverless platform vagy egy CDN hozzáadhat, eltávolíthat, duplikálhat vagy lecserélhet fejléceket.
• Ellenőrizd a hiba válaszokat. Egy normál 200-as válasz tartalmazhat CORS fejléceket, míg egy 401, 404 vagy 500-as válasz nem.
• Ellenőrizd a szó szerinti origint. A séma, a hostname és a port mind számít; a localhost és a 127.0.0.1 nem felcserélhetők CORS egyezés szempontjából.
• Ellenőrizd a duplikált fejléceket. Az MDN dokumentálja, hogy több Access-Control-Allow-Origin fejléc nem megengedett. Lásd: Az MDN a több Access-Control-Allow-Origin fejlécről.

Kézi fejlécek versus a cors middleware

Manuálisan is beállíthatsz CORS fejléceket az Express válasz API-k segítségével, de könnyű kihagyni a preflight viselkedést, a hitelesítési szabályokat, a dinamikus origin egyezést, a Vary: Origin-t vagy a hiba útvonalakat. A hivatalos cors middleware már kínál opciókat az origin-re, módszerekre, engedélyezett fejlécekre, kitett fejlécekre, hitelesítésre, preflight viselkedésre és max age-re. A legtöbb Express projekt esetén ezen middleware használata explicit és könnyebben felülvizsgálható szabályzatot tart fenn.

Ha te magad valósítasz meg dinamikus origin logikát, soha ne tükrözd automatikusan minden bejövő Origin értéket csak azért, mert jelen van. Validáld egy megbízható halmaz ellen. Az MDN figyelmeztet, hogy a korlátlan cross-origin olvasások kitárhatják az adatokat, különösen, ha hitelesítés is involved.

Gyakorlati éles (production) ellenőrzőlista

• Listázd a pontos frontend originöket, amelyeknek képesnek kell lenniük az API elolvasására.
• Használj HTTPS originöket éles környezetben, és tartsd külön a fejlesztői originöket.
• Telepítsd a CORS middleware-t a védett API route-ok elé, amelyeknek szükségük van rá.
• Használj specifikus originöket privát vagy hitelesített végpontokhoz.
• Ellenőrizd a böngészőben mind a normál válaszokat, mind a preflight OPTIONS válaszokat.
• Ellenőrizd a hiba útvonalakat, mint például a 401, 404 és 500 válaszokat, ha cross-origin módon visszaadhatók.
• Kezeld a CORS-ot böngésző olvasási szabályzatként, nem pedig hitelesítésként vagy engedélyezésként.

A szemléltető feladatkezelő dashboard forgatókönyvben a tartós javítás egyértelmű: azonosítsd a frontend pontos originjét, konfiguráld az Express-t a megfelelő CORS fejléc visszaadására, hagyd, hogy az alkalmazásszintű middleware kezelje a preflight kéréseket, és ellenőrizd a fejléceket azon a válaszon, amelyet a böngésző ténylegesen kap. Ha a fejléc ezután is hiányzik, a következő gyanúsított általában a middleware sorrend vagy az infrastruktúra a böngésző és az Express között, nem pedig maga a frontend fetch hívás.

Hivatalos hivatkozások

• Express.js cors middleware dokumentáció — konfigurációs opciók, dinamikus originök, hitelesítés és preflight viselkedés.
• Express.js middleware útmutató — alkalmazás middleware és kérés-feldolgozási sorrend.
• MDN: CORS header Access-Control-Allow-Origin missing — ennek a konkrét böngésző hibának a jelentése.
• MDN CORS biztonsági konfigurációs útmutató — útmutatás az engedélyezett originök korlátozásáról és a hitelesített hozzáférés kezeléséről.