Kako popraviti manjkajoči CORS glavo Access-Control-Allow-Origin v Express.js

Če brskalnik prikaže napako CORS header 'Access-Control-Allow-Origin' missing, ključni namig ni, da Express.js ni prejel zahteve. Brskalnik vam sporoča, da odgovor ni vseboval CORS glave, ki bi pooblastila izvor strani za branje tega odgovora. Popravek zato spada na strežnik ali proxy, ki ga nadzorujete, ne v naključno nastavitev na strani odjemalca.

Ilustrativni primer uporabljen v celotnem vodniku: zamislite si nadzorno ploščo opravil, ki teče na http://localhost:5173 in kliče Express API na http://localhost:3000/api/tasks. Brskalnik blokira branje odgovora API s strani JavaScripta, ker API ne vrne glave Access-Control-Allow-Origin. To je hipotetični učni primer, ne trditev o dejanskem testu, izdelku ali namestitvi.

Kot je bilo preverjeno 11. septembra 2026, uradna dokumentacija vmesne programske opreme Express CORS navaja različico cors 2.8.6 in jo opisuje kot vmesno programsko opremo, ki nastavi odgovore glave CORS. Trenutni seznam paketov Express je v generaciji 5.x, zato ta vodnik daje prednost vmesni programski opremi na ravni aplikacije namesto zanašanja na starejše vzorce potniških kart (wildcard route).

Kaj napaka dejansko pomeni

Spletna stran ima izvor (origin), ki ga sestavljajo shema, gostitelj in vrata. V primeru sta http://localhost:5173 in http://localhost:3000 različna izvora, ker se njuni vrati razlikujeta. Politika istega izvora (same-origin policy) v brskalniku običajno preprečuje, da bi JavaScript na enem izvoru bral vire z drugega, razen če ciljni strežnik vrne ustrezne glave za skupno rabo virov med izvori (CORS).

Dokumentacija MDN za to natančno napako pojasnjuje, da odgovoru manjka zahtevana glava Access-Control-Allow-Origin. Če nadzorujete strežnik, morate konfigurirati izvor zahtevajočega spletnega mesta kot dovoljen izvor. Za javne API-je brez poverilnic je lahko * ustrezna izbira; za zasebne API-je ali API-je s poverilnicami uporabite namesto tega specifične zaupanja vredne izvire. Glejte razlago MDN o manjkajoči napaki Access-Control-Allow-Origin.

Korak 1: Potrdite, da je težava CORS, in identificirajte natančen izvor

Odprite orodja za razvijalce v brskalniku in preverite plošči Console in Network. Natančno zabeležite izvor frontenda, kot ga pošilja brskalnik. V našem ilustrativnem primeru je to http://localhost:5173.

Izvora ne reducirajte samo na ime gostitelja. To so različni izvori: http://localhost:5173, http://localhost:3000, http://127.0.0.1:5173 in https://localhost:5173. Seznam dovoljenih virov v produkciji mora prav tako razlikovati https://app.example.com od drugih shem, gostiteljev, vrat ali poddom, razen če jih namerno dovolite.

Če je odgovor API 404, 500, preusmeritev, napaka pri preverjanju pristnosti ali generirana napaka proxyja, preglejte tudi ta odgovor. Glave CORS morajo biti prisotne v odgovoru, ki ga brskalnik dejansko prejme. Popravljanje aplikacijske poti ne bo pomagalo, če obratni proxy, CDN, uravnotežnik obremenitve ali obravnavalec napak vrne drugačen odgovor brez glave.

Korak 2: Namestite in naložite uradno vmesno programsko opremo Express CORS

Za večino aplikacij Express je najmanj nagnjena k napakam rešitev vmesna programska oprema cors, ki jo vzdržuje projekt Express. Uradna stran vmesne programske opreme Express jo navaja med vmesno programsko opremo, ki jo vzdržuje ekipa Express.js. Namestite jo v svoj projekt API:

npm install cors

Nato jo naložite poleg Express:

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

const app = express();

Uradna dokumentacija je na voljo na dokumentaciji vmesne programske opreme cors za Express.js. Express tudi dokumentira, kako se vmesna programska oprema na ravni aplikacije izvaja po vrsti zahtev na Express.js: Uporaba vmesne programske opreme.

Korak 3: Namerno dovolite izvor frontenda

Za hipotetično nadzorno ploščo konfigurirajte natančen razvojni izvor pred potmi, ki potrebujejo 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);

Pomembno je, da je app.use(cors(corsOptions)) pred potmi API, ker Express obdeluje vmesno programsko opremo po vrsti. Vmesna programska oprema mora imeti priložnost dodati glave odgovora, preden pot ali prejšnja vmesna programska oprema konča zahtevo.

Za resnično javni API, ki ne uporablja poverilnic, app.use(cors()) uporabi privzeto dovoljeno obnašanje izvora vmesne programske opreme. To je priročno, vendar ne bi smela biti vaša samodejna izbira v produkciji. MDN priporoča omejitev Access-Control-Allow-Origin na najmanjše število potrebnih virov in virov. Glejte varnostne smernice MDN za CORS.

Dovolite več znanih virov brez dovoljenja vsem

Pogosta produkcijska nastavitev ima lokalni frontend, frontend za testno okolje (staging) in produkcijski frontend. Uporabite seznam dovoljenih in preverite dohodni izvor:

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

Vejica !origin dovoljuje odjemalce, ki ne pošiljajo glave Origin, kot so mnoge zahteve med strežniki in orodja ukazne vrstice. Ali želite to obnašanje, je odločitev politike aplikacije; CORS sam po sebi ni preverjanje pristnosti.

Korak 4: Preverite preprosto zahtevo in morebitno predhodno preverjanje (preflight)

Ponovno naložite frontend in preglejte ploščo Network. Pogoj uspeha ni zgolj status 200. Preverite glave odgovora. V našem ilustrativnem primeru bi moral odgovor API vsebovati vrednost izvora, enakovredno:

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

Nekatere zahteve med izvori sprožijo predhodno preverjanje (preflight): brskalnik pošlje zahtevo OPTIONS pred dejansko zahtevo, da preveri, ali so metoda in glave dovoljene. Zahteve, ki uporabljajo metode, kot sta PUT ali DELETE, ali določene prilagojene/zahtevane glave, običajno potrebujejo predhodno preverjanje. Ko je cors nameščen kot vmesna programska oprema na ravni aplikacije z app.use(cors(...)), uradna dokumentacija Express navaja, da so zahteve predhodnega preverjanja obravnavane za vse poti.

Glave lahko preverite tudi zunaj brskalnika, ne da bi trdili, da jih odjemalec ukazne vrstice uveljavlja:

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

To je uporabno za ogled tega, kar vrne strežnik, vendar uspešna zahteva curl ali API-odjemalca ne dokazuje, da je CORS v brskalniku pravilno konfiguriran. Dokumentacija CORS za Express izrecno navaja, da CORS uveljavljajo brskalniki; ne-brskalniki odjemalci ne uporabljajo iste omejitve branja.

Zahteve s poverilnicami: ne kombinirajte poverilnic z wildcard izvorom

Če mora frontend pošiljati piškotke ali HTTP preverjanje pristnosti med izvori, morata obe strani imeti združljive nastavitve. Na strani Express konfigurirajte specifičen zaupanja vreden izvor in omogočite poverilnice:

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

Na strani brskalnika zahteva fetch, ki potrebuje piškotke, običajno uporablja credentials: 'include'. Ne preklopite izvora strežnika na * za zahtevo s poverilnicami. Brskalniki ne sprejmejo wildcard Access-Control-Allow-Origin skupaj s CORS s poverilnicami na način, kot ga razvijalci pogosto pričakujejo, neomejen izvor pa bi bil tudi slaba varnostna meja.

Zakaj pogosti »popravki« ne uspejo

Ko je koda Express videti pravilno, a napaka ostaja

Če zgornji štirje koraki ne rešijo napake, sledite celotni poti zahteve, namesto da bi slepo dodajali več glav.

• Preverite vrstni red vmesne programske opreme. Vmesna programska oprema CORS bi morala teči pred potmi ali obravnavalniki, ki končajo odgovor.
• Preverite preusmeritve. Brskalnik morda prejema odgovor z drugega URL-ja ali izvora po preusmeritvi.
• Preverite obnašanje proxyja/CDN. Nginx, prehod (gateway), platforma brez strežnikov ali CDN lahko doda, odstrani, podvoji ali zamenja glave.
• Preverite odgovore napak. Običajen odgovor 200 lahko vsebuje glave CORS, odgovor 401, 404 ali 500 pa ne.
• Preverite dobesedni izvor. Shema, ime gostitelja in vrata so vsi pomembni; localhost in 127.0.0.1 nista zamenljiva za ujemanje CORS.
• Preverite podvojene glave. MDN dokumentira, da več glav Access-Control-Allow-Origin ni dovoljenih. Glejte MDN o več glavah Access-Control-Allow-Origin.

Ročne glave v primerjavi z vmesno programsko opremo cors

Glave CORS lahko nastavite ročno z API-ji odgovora Express, vendar je enostavno spregledati obnašanje predhodnega preverjanja, pravila za poverilnice, dinamično ujemanje izvora, Vary: Origin ali poti napak. Uradna vmesna programska oprema cors že izpostavlja možnosti za origin, metode, dovoljene glave, izpostavljene glave, poverilnice, obnašanje predhodnega preverjanja in največjo starost. Za večino projektov Express uporaba te vmesne programske opreme ohranja politiko eksplicitno in lažjo za pregled.

Če sami implementirate logiko dinamičnega izvora, nikoli samodejno ne odražajte vsake dohodne vrednosti Origin samo zato, ker je prisotna. Preverite jo glede na zaupanja vreden nabor. MDN opozarja, da neomejena branja med izvori lahko razkrijejo podatke, zlasti kadar so vpleteno poverilnice.

Praktičen produkcijski kontrolni seznam

• Navedite natančne izvire frontenda, ki bi morali biti sposobni brati API.
• V produkciji uporabljajte izvire HTTPS in ločite razvojne vire.
• Namestite vmesno programsko opremo CORS pred zaščitenimi potmi API, ki jo potrebujejo.
• Za zasebne končne točke ali končne točke s poverilnicami uporabite specifične izvire.
• V brskalniku preverite tako običajne odgovore kot odgovore predhodnega preverjanja OPTIONS.
• Preverite poti napak, kot so odgovori 401, 404 in 500, če jih je mogoče vrniti med izvori.
• CORS obravnavajte kot politiko branja brskalnika, ne kot preverjanje pristnosti ali pooblastila.

V ilustrativnem scenariju nadzorne plošče opravil je trajna rešitev preprosta: identificirajte natančen izvor frontenda, konfigurirajte Express, da vrne ujemanje glave CORS, dovolite vmesni programski opremi na ravni aplikacije, da obravnava predhodno preverjanje, in preverite glave v odgovoru, ki ga brskalnik dejansko prejme. Če glava še vedno manjka po tem, je naslednji osumljenec običajno vrstni red vmesne programske opreme ali infrastruktura med brskalnikom in Express, ne sam klic fetch na frontendu.

Uradne reference

• Dokumentacija vmesne programske opreme cors za Express.js — možnosti konfiguracije, dinamični izvori, poverilnice in obnašanje predhodnega preverjanja.
• Vodnik po vmesni programski opremi Express.js — vmesna programska oprema aplikacije in vrstni red obdelave zahtev.
• MDN: Manjkajoča glava CORS Access-Control-Allow-Origin — pomen te specifične napake brskalnika.
• Vodnik MDN za varnostno konfiguracijo CORS — smernice za omejitev dovoljenih virov in obravnavo dostopa s poverilnicami.