Kaip išspręsti CORS antraštės Access-Control-Allow-Origin trūkumo klaidą Express.js

Jei naršyklė rodo klaidą CORS header 'Access-Control-Allow-Origin' missing, svarbus požymis yra ne tai, kad Express.js nepavyko gauti užklausos. Naršyklė nurodo, kad atsakyme nebuvo CORS antraštės, leidžiančios puslapio kilmę skaityti tą atsakymą. Todėl sprendimas turi būti taikomas serveryje arba proxy, kurį valdote, o ne atsitiktiniame kliento pusės nustatyme.

Iliustracinis pavyzdys, naudojamas visame šiame vadove: įsivaizduokite užduočių skydelį, veikiančią adresatu http://localhost:5173, kuris kreipiasi į Express API adresu http://localhost:3000/api/tasks. Naršyklė blokuoja JavaScript galimybę skaityti API atsakymą, nes API negrąžina Access-Control-Allow-Origin. Tai hipotetinis mokomasis pavyzdys, o ne teiginys apie realų testą, produktą ar diegimą.

Patikrinta 2026 m. rugsėjo 11 d., oficialioje Express CORS tarpinės programinės įrangos dokumentacijoje nurodyta cors versija 2.8.6 ir ji apibūdinama kaip tarpinė programinė įranga, nustatanti CORS atsakymo antraštes. Dabartinis Express paketo sąrašas yra 5.x kartos, todėl šiame vadove pirmenybė teikiama programos lygio tarpinei programinei įrangai, o ne senesniems laukinių maršrutų šablonams.

Ką iš tikrųjų reiškia ši klaida

Tinklalapis turi kilmę, sudarytą iš jo schemos, pagrindinio kompiuterio ir prievado. Pavyzdyje http://localhost:5173 ir http://localhost:3000 yra skirtingos kilmės, nes jų prievadai skiriasi. Naršyklių vienodos kilmės politika paprastai neleidžia vienos kilmės JavaScript skaityti išteklių iš kitos kilmės, nebent tikslinis serveris grąžina tinkamas tarpšaltinės išteklių dalijimosi (CORS) antraštes.

MDN dokumentacija šiai konkrečiai klaidai paaiškina, kad atsakyme trūksta būtinos Access-Control-Allow-Origin antraštės. Jei kontroliuojate serverį, turėtumėte sukonfigūruoti užklausą siunčiančios svetainės kilmę kaip leidžiamą kilmę. Viešoms, be kredencialų naudojamoms API, * gali būti tinkamas; privačioms arba su kredencialais naudojamoms API, vietoj to naudokite konkrečias patikimas kilmes. Žiūrėkite MDN paaiškinimą apie trūkstamą Access-Control-Allow-Origin klaidą.

1 žingsnis: Patvirtinkite, kad problema yra CORS, ir nustatykite tikslią kilmę

Atidarykite naršyklės kūrėjo įrankius ir patikrinkite tiek Konsolės, tiek Tinklo skydelius. Užfiksuokite frontend kilmę tiksliai taip, kaip ją siunčia naršyklė. Mūsų iliustraciniu atveju tai yra http://localhost:5173.

Nesuprastinkite kilmės tik iki pagrindinio kompiuterio pavadinimo. Šios yra skirtingos kilmės: http://localhost:5173, http://localhost:3000, http://127.0.0.1:5173 ir https://localhost:5173. Gamintojo leidžiamųjų sąrašas taip pat turi atskirti https://app.example.com nuo kitų schemų, pagrindinių kompiuterių, prievadų ar poantraščių, nebent sąmoningai leidžiate jas.

Jei API atsakymas yra 404, 500, peradresavimas, autentifikavimo nesėkmė arba proxy sugeneruotas klaidų puslapis, patikrinkite ir tą atsakymą. CORS antraštės turi būti pateiktos atsakyme, kurį naršyklė iš tikrųjų gauna. Programos maršruto taisymas nepadės, jei atvirkštinis proxy, CDN, apkrovos balansuotojas ar klaidų apdorojimo programa grąžina kitą atsakymą be antraštės.

2 žingsnis: Įdiekite ir įkelkite oficialią Express CORS tarpinę programinę įrangą

Daugumai Express programų mažiausiai klaidų sukeliantis sprendimas yra cors tarpinė programinė įranga, kurią prižiūri Express projektas. Oficiali Express tarpinės programinės įrangos puslapyje ji išvardyta tarp tarpinių programų, kurias prižiūri Express.js komanda. Įdiekite ją savo API projekte:

npm install cors

Tada įkelkite ją šalia Express:

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

const app = express();

Oficiali dokumentacija prieinama adresu Express.js cors tarpinės programinės įrangos dokumentacija. Express taip pat dokumentuoja, kaip programos lygio tarpinė programinė įranga veikia užklausų tvarka, adresu Express.js: Tarpinės programinės įrangos naudojimas.

3 žingsnis: Sąmoningai leiskite frontend kilmę

Hipotetiniam skydeliui sukonfigūruokite tikslią plėtros kilmę prieš maršrutus, kuriems reikia 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);

Svarbu, kad app.use(cors(corsOptions)) būtų prieš API maršrutus, nes Express apdoroja tarpinę programinę įrangą pagal eiliškumą. Tarpinei programinei įrangai reikia galimybės pridėti atsakymo antraštes prieš tai, kai maršrutas arba ankstesnė tarpinė programinė įranga baigia užklausą.

Tikrai viešai API, kuri nenaudoja kredencialų, app.use(cors()) naudoja numatytąjį tarpinės programinės įrangos leidžiantį kilmės elgesį. Tai patogu, tačiau tai neturėtų būti automatinis gamintojo pasirinkimas. MDN rekomenduoja apriboti Access-Control-Allow-Origin iki minimalių reikalingų kilmų ir išteklių. Žiūrėkite MDN CORS saugumo gaires.

Leiskite kelias žinomas kilmes, neleisdami visiems

Dažna gamintojo konfigūracija turi vietinį frontend, bandymų aplinkos frontend ir gamintojo frontend. Naudokite leidžiamųjų sąrašą ir patikrinkite gaunamą kilmę:

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

!origin šaka leidžia klientams, kurie nesiunčia Origin antraštės, pvz., daugeliui serverio ir serverio užklausų bei komandinės eilutės įrankiams. Ar norite tokio elgesio, yra programos politikos sprendimas; pats CORS nėra autentifikavimas.

4 žingsnis: Patikrinkite paprastą užklausą ir bet kokį išankstinį tikrinimą

Perkraukite frontend ir patikrinkite Tinklo skydelį. Sėkmės sąlyga nėra vien tik 200 būsena. Patikrinkite atsakymo antraštes. Mūsų iliustraciniu atveju API atsakyme turėtų būti kilmės reikšmė, atitinkanti:

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

Kai kurios tarpšaltinės užklausos sukelia išankstinį tikrinimą: naršyklė siunčia OPTIONS užklausą prieš tikrąją užklausą, kad patikrintų, ar metodas ir antraštės yra leidžiami. Užklausos, naudojantys metodus, tokius kaip PUT ar DELETE, arba tam tikras tinkintas/užklausos antraštes, dažniausiai reikalauja išankstinio tikrinimo. Kai cors yra įdiegta kaip programos lygio tarpinė programinė įranga naudojant app.use(cors(...)), oficiali Express dokumentacija teigia, kad išankstinės tikrinimo užklausos yra apdorojamos visiems maršrutams.

Taip pat galite patikrinti antraštes ne naršyklėje, neteigdami, kad komandinės eilutės klientas taiko CORS:

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

Tai naudinga norint pamatyti, ką grąžina serveris, tačiau sėkminga curl arba API kliento užklausa neproto, kad naršyklės CORS yra sukonfigūruotas teisingai. Express CORS dokumentacija aiškiai nurodo, kad CORS taiko naršyklės; ne naršyklių klientai netaiko to paties skaitymo apribojimo.

Užklausos su kredencialais: nejungkite kredencialų su laukinio ženklo kilme

Jei frontend turi siųsti slapukus arba HTTP autentifikavimą tarp šaltinių, abi pusės turi turėti suderinamus nustatymus. Express pusėje sukonfigūruokite konkrečią patikimą kilmę ir įgalinkite kredencialus:

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

Naršyklės pusėje fetch užklausa, kuriai reikia slapukų, paprastai naudoja credentials: 'include'. Nekeiskite serverio kilmės į * užklausai su kredencialais. Naršyklės nepriima laukinio ženklo Access-Control-Allow-Origin kartu su CORS su kredencialais taip, kaip dažnai tikisi kūrėjai, o neapribota kilmė taip pat būtų prasta saugumo riba.

Kodėl dažni „sprendimai“ nepavyksta

Kai Express kodas atrodo teisingas, bet klaida lieka

Jei keturi aukščiau nurodyti žingsniai neišsprendžia klaidos, sekite visą užklausos kelią, o ne aklai pridėkite daugiau antraščių.

• Patikrinkite tarpinės programinės įrangos eiliškumą. CORS tarpinė programinė įranga turėtų veikti prieš maršrutus arba apdorojimo programas, kurios baigia atsakymą.
• Patikrinkite peradresavimus. Naršyklė gali gauti atsakymą iš kito URL arba kilmės po peradresavimo.
• Patikrinkite proxy/CDN elgesį. Nginx, vartai, serverless platforma arba CDN gali pridėti, pašalinti, dubliuoti arba pakeisti antraštes.
• Patikrinkite klaidų atsakymus. Įprastas 200 atsakymas gali turėti CORS antraštes, o 401, 404 arba 500 atsakymas – ne.
• Patikrinkite literalinę kilmę. Schema, pagrindinio kompiuterio pavadinimas ir prievadas yra svarbūs; localhost ir 127.0.0.1 nėra pakaitiniai CORS atitikimui.
• Patikrinkite dubliuotas antraštes. MDN dokumentuoja, kad kelios Access-Control-Allow-Origin antraštės nėra leidžiamos. Žiūrėkite MDN apie kelias Access-Control-Allow-Origin antraštes.

Rankinės antraštės prieš cors tarpinę programinę įrangą

Galite nustatyti CORS antraštes rankiniu būdu naudodami Express atsakymo API, tačiau lengva praleisti išankstinio tikrinimo elgesį, kredencialų taisykles, dinaminį kilmės atitikimą, Vary: Origin arba klaidų kelius. Oficiali cors tarpinė programinė įranga jau pateikia parinktis origin, metodams, leidžiamoms antraštėms, atskleidžiamoms antraštėms, kredencialams, išankstinio tikrinimo elgesiui ir maksimaliam amžiui. Daugumai Express projektų šios tarpinės programinės įrangos naudojimas išlaiko politiką aiškią ir lengviau peržiūrimą.

Jei patys įgyvendinate dinaminę kilmės logiką, niekada automatiškai neatkartokite kiekvienos gaunamos Origin reikšmės vien todėl, kad ji yra pateikta. Patikrinkite ją pagal patikimų kilmų rinkinį. MDN įspėja, kad neapriboti tarpšaltiniai skaitymai gali atskleisti duomenis, ypač kai naudojami kredencialai.

Praktinis gamintojo patikros sąrašas

• Išvardykite tikslias frontend kilmes, kurios turėtų galėti skaityti API.
• Gamintoje aplinkoje naudokite HTTPS kilmes ir laikykite plėtros kilmes atskirai.
• Įdiekite CORS tarpinę programinę įrangą prieš apsaugotus API maršrutus, kuriems jos reikia.
• Privačioms arba su kredencialais naudojamoms galinėms taškams naudokite konkrečias kilmes.
• Naršyklėje patikrinkite tiek įprastus atsakymus, tiek išankstinio tikrinimo OPTIONS atsakymus.
• Jei jie gali būti grąžinti tarp šaltinių, patikrinkite nesėkmės kelius, tokius kaip 401, 404 ir 500 atsakymai.
• Laikykite CORS naršyklės skaitymo politika, o ne autentifikavimu arba autorizacija.

Iliustraciniame užduočių skydelio scenarijuje patvarus sprendimas yra paprastas: nustatykite tikslią frontend kilmę, sukonfigūruokite Express grąžinti atitinkančią CORS antraštę, leiskite programos lygio tarpinei programinei įrangai apdoroti išankstinį tikrinimą ir patikrinkite antraštes atsakyme, kurį naršyklė iš tikrųjų gauna. Jei antraštė vis tiek trūksta po to, kitas įtariamasis paprastai yra tarpinės programinės įrangos eiliškumas arba infrastruktūra tarp naršyklės ir Express, o ne pati frontend fetch užklausa.

Oficialios nuorodos

• Express.js cors tarpinės programinės įrangos dokumentacija — konfigūracijos parinktys, dinaminės kilmės, kredencialai ir išankstinio tikrinimo elgesys.
• Express.js tarpinės programinės įrangos vadovas — programos tarpinė programinė įranga ir užklausų apdorojimo tvarka.
• MDN: CORS antraštė Access-Control-Allow-Origin trūksta — šios konkrečios naršyklės klaidos reikšmė.
• MDN CORS saugumo konfigūravimo vadovas — gairės dėl leidžiamų kilmų ribojimo ir prieigos su kredencialais tvarkymo.