Kuinka korjata puuttuva CORS-otsake Access-Control-Allow-Origin Express.js:ssä

Jos selain ilmoittaa virheestä CORS header 'Access-Control-Allow-Origin' missing, tärkeä vihje ei ole se, että Express.js ei vastaanottanut pyyntöä. Selain kertoo, että vastaus ei sisältänyt CORS-otsaketta, joka valtuuttaisi sivun alkuperän lukemaan kyseisen vastauksen. Korjaus kuuluu siis palvelimelle tai hallinnoimallesi välityspalvelimelle, ei satunnaiseen asiakaspuolen asetukseen.

Oppaan läpi käytettävä havainnollistava esimerkki: kuvittele tehtäväkoesite, joka toimii osoitteessa http://localhost:5173 ja kutsuu Express API:a osoitteessa http://localhost:3000/api/tasks. Selain estää JavaScriptiä lukemasta API-vastausta, koska API ei palauta otsaketta Access-Control-Allow-Origin. Tämä on hypoteettinen opetusesimerkki, ei väite todellisesta testistä, tuotteesta tai käyttöönotosta.

Expressin virallisen CORS-välineistön dokumentaation tarkistuksen mukaan 11. syyskuuta 2026 cors-kirjaston versio on 2.8.6, ja se kuvataan välineistönä, joka asettaa CORS-vastausotsikkeet. Nykyinen Express-pakkauskuvaus on 5.x-sukupolvessa, joten tämä opas suosii sovellustason välineistöä vanhojen jokerireittikuvioiden sijaan.

Mitä virhe todella tarkoittaa

Verkkosivulla on alkuperä, joka muodostuu sen protokollasta, isännästä ja portista. Esimerkissä http://localhost:5173 ja http://localhost:3000 ovat eri alkuperiä, koska niiden portit eroavat toisistaan. Selaimen samansyntyisyyskäytäntö estää normaalisti JavaScriptiä lukemasta resursseja toisesta alkuperästä, ellei kohdepalvelin palauta sopivia Cross-Origin Resource Sharing (CORS) -otsikkeita.

MDN:n dokumentaatio tästä tarkasta virheestä selittää, että vastauksesta puuttuu vaadittu Access-Control-Allow-Origin -otsake. Jos hallinnoit palvelinta, sinun tulee määrittää pyytävän sivuston alkuperä sallituksi alkuperäksi. Julkisille, ei-uskoja vaativille API:lle * voi olla sopiva; yksityisille tai uskoja vaativille API:lle käytä sen sijaan tiettyjä luotettuja alkuperiä. Katso MDN:n selitys puuttuvasta Access-Control-Allow-Origin -virheestä.

Vaihe 1: Varmista, että CORS on ongelma, ja tunnistat tarkka alkuperä

Avaa selaimen kehittäjätyökalut ja tarkista sekä Konsoli- että Verkko-paneelit. Kirjaa etupään alkuperä tarkasti sellaisena kuin selain lähettää sen. Havainnollistavassa tapauksessamme se on http://localhost:5173.

Älä tiivistä alkuperää vain isäntänimeksi. Nämä ovat eri alkuperiä: http://localhost:5173, http://localhost:3000, http://127.0.0.1:5173 ja https://localhost:5173. Tuotannon sallintalista on myös eroteltava https://app.example.com muista protokollista, isännistä, porteista tai aliverkkotunnuksista, ellet tarkoituksella salli niitä.

Jos API-vastaus on 404, 500, uudelleenohjaus, todennusvirhe tai välityspalvelimen luoma virhesivu, tutki myös sitä vastausta. CORS-otsikkeiden on oltava läsnä vastauksessa, jonka selain todella vastaanottaa. Sovellusreitin korjaaminen ei auta, jos käänteinen välityspalvelin, CDN, kuormantasain tai virheenkäsittelijä palauttaa eri vastauksen ilman otsaketta.

Vaihe 2: Asenna ja lataa virallinen Express CORS -välineistö

Useimmissa Express-sovelluksissa vähiten virhealtis ratkaisu on Express-projektin ylläpitämä cors-välineistö. Virallinen Express-välineistösivu listaa sen Express.js-tiimin ylläpitämän välineistön joukossa. Asenna se API-projektiisi:

npm install cors

Lataa se sitten Expressin viereen:

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

const app = express();

Virallinen dokumentaatio on saatavilla osoitteessa Express.js cors -välineistön dokumentaatio. Express dokumentoi myös, kuinka sovellustason välineistö suoritetaan pyyntöjen järjestyksessä osoitteessa Express.js: Välineistön käyttö.

Vaihe 3: Salli etupään alkuperä tarkoituksella

Hypoteettisessa koesiteessä määritä tarkka kehitysalkuperä ennen reittejä, jotka tarvitsevat CORS:ia:

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

On tärkeää sijoittaa app.use(cors(corsOptions)) ennen API-reittejä, koska Express käsittelee välineistön järjestyksessä. Välineistön on saatava mahdollisuus lisätä vastausotsikkeet ennen kuin reitti tai aiempi välineistö lopettaa pyynnön.

Todella julkiselle API:lle, joka ei käytä uskoja, app.use(cors()) käyttää välineistön oletusarvoista sallivaa alkuperäkäyttäytymistä. Se on kätevää, mutta sen ei tulisi olla automaattinen valintasi tuotannossa. MDN suosittelee rajoittamaan Access-Control-Allow-Origin -otsakkeen vain vähimmäismäärään alkuperiä ja resursseja. Katso MDN:n CORS-turvallisuusohjeet.

Salli useat tunnetut alkuperät sallimatta kaikkia

Yleinen tuotantoasetus sisältää paikallisen etupään, staging-etupään ja tuotanto-etupään. Käytä sallintalistaa ja validoi tuleva alkuperä:

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-haara sallii asiakkaat, jotka eivät lähetä Origin-otsaketta, kuten monet palvelin-väliset pyynnöt ja komentorivityökalut. Haluatko tällaisen käyttäytymisen, on sovelluksen politiikkapäätös; CORS itsessään ei ole todennusta.

Vaihe 4: Varmista yksinkertainen pyyntö ja mahdollinen esitarkistus

Lataa etupää uudelleen ja tutki Verkko-paneelia. Onnistumisen ehto ei ole pelkkä 200-tilakoodi. Tarkista vastausotsikkeet. Havainnollistavassa tapauksessamme API-vastauksen tulisi sisältää alkuperäarvo, joka vastaa:

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

Joissakin poikkeavissa pyynnöissä laukaisee esitarkistuksen: selain lähettää OPTIONS-pyynnön ennen varsinaista pyyntöä tarkistaakseen, sallitaanko menetelmä ja otsikkeet. Pyynnöt, jotka käyttävät menetelmiä kuten PUT tai DELETE, tai tiettyjä mukautettuja/pyyntöotsikkeita, tarvitsevat yleensä esitarkistuksen. Kun cors on asennettu sovellustason välineistönä komennolla app.use(cors(...)), virallinen Express-dokumentaatio sanoo, että esitarkistuspyynnöt käsitellään kaikille reiteille.

Voit myös tutkia otsikkeita selaimen ulkopuolella väittämättä, että komentoriviasiakas pakottaa CORS:in:

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

Tämä on hyödyllistä nähdäksesi, mitä palvelin palauttaa, mutta onnistunut curl- tai API-asiakaspyyntö ei todista, että selaimen CORS on määritetty oikein. Expressin CORS-dokumentaatio huomauttaa nimenomaisesti, että selaimet pakottavat CORS:in; ei-selainasiakkaat eivät sovellata samaa lukurajoitusta.

Uskoja vaativat pyynnöt: älä yhdistä uskoja jokerimerkki-alkuperään

Jos etupään on lähetettävä evästeitä tai HTTP-todennusta poikkeavasti, molempien osapuolten tarvitsee yhteensopivat asetukset. Express-puolella määritä tietty luotettava alkuperä ja ota uskoja käyttöön:

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

Selainpuolella fetch-pyyntö, joka tarvitsee evästeitä, käyttää tyypillisesti credentials: 'include'. Älä vaihda palvelimen alkuperää arvoon * uskoja vaativassa pyynnössä. Selaimet eivät hyväksy jokerimerkkiä Access-Control-Allow-Origin yhdessä uskoja vaativan CORS:in kanssa tavalla, jota kehittäjät usein odottavat, ja rajoittamaton alkuperä olisi myös heikko turvallisuusraja.

Miksi yleiset "korjaukset" epäonnistuvat

Kun Express-koodi näyttää oikealta, mutta virhe pysyy

Jos yllä olevat neljä vaihetta eivät ratkaise virhettä, jäljitä koko pyyntöpolku sen sijaan, että lisäisit otsikkeita sokeasti.

• Tarkista välineistön järjestys. CORS-välineistön tulisi suorittaa ennen reittejä tai käsittelijöitä, jotka lopettavat vastauksen.
• Tarkista uudelleenohjaukset. Selain voi vastaanottaa vastauksen eri URL-osoitteesta tai alkuperästä uudelleenohjauksen jälkeen.
• Tarkista välityspalvelimen/CDN:n käyttäytyminen. Nginx, yhdyskäytävä, palveluton alusta tai CDN voi lisätä, poistaa, kopioida tai korvata otsikkeita.
• Tarkista virhevastaukset. Normaali 200-vastaus voi sisältää CORS-otsikkeet, mutta 401-, 404- tai 500-vastaus ei.
• Tarkista kirjaimellinen alkuperä. Protokolla, isäntänimi ja portti ovat kaikki tärkeitä; localhost ja 127.0.0.1 eivät ole keskenään vaihdettavissa CORS-vastaavuudessa.
• Tarkista päällekkäiset otsikkeet. MDN dokumentoi, että useat Access-Control-Allow-Origin -otsikkeet eivät ole sallittuja. Katso MDN useista Access-Control-Allow-Origin -otsikkeista.

Manuaaliset otsikkeet versus cors-välineistö

Voit asettaa CORS-otsikkeet manuaalisesti Express-vastaus-API:illa, mutta on helppo unohtaa esitarkistuskäyttäytyminen, uskojasäännöt, dynaaminen alkuperäsovitus, Vary: Origin tai virhepolut. Virallinen cors-välineistö tarjoaa jo vaihtoehdot origin-asetukselle, menetelmille, sallituille otsikkeille, paljastetuille otsikkeille, uskojalle, esitarkistuskäyttäytymiselle ja maksimi-ikälle. Useimmissa Express-projekteissa tämän välineistön käyttö pitää politiikan eksplisiittisenä ja helpommin tarkasteltavana.

Jos toteutat dynaamisen alkuperälogiikan itse, älä koskaan heijasta jokaista tulevaa Origin-arvoa automaattisesti vain siksi, että se on läsnä. Validoi se luotettua joukkoa vasten. MDN varoittaa, että rajoittamattomat poikkeavat luvut voivat paljastaa dataa, erityisesti kun uskoja on mukana.

Käytännön tuotantotarkistuslista

• Listaa tarkat etupään alkuperät, joiden tulisi voida lukea API:a.
• Käytä HTTPS-alkuperiä tuotannossa ja pidä kehitysalkuperät erillään.
• Asenna CORS-välineistö ennen suojattuja API-reittejä, jotka tarvitsevat sitä.
• Käytä tiettyjä alkuperiä yksityisille tai uskoja vaativille päätepisteille.
• Varmista sekä normaaleet vastaukset että esitarkistus OPTIONS -vastaukset selaimessa.
• Varmista virhepolut, kuten 401-, 404- ja 500-vastaukset, jos niitä voidaan palauttaa poikkeavasti.
• Kohtele CORS:ia selaimen lukukäytäntönä, ei todennuksena tai valtuutuksena.

Havainnollistavassa tehtäväkoesitetilanteessa kestävä korjaus on suoraviivainen: tunnistaa etupään tarkka alkuperä, määrittää Express palauttamaan vastaavan CORS-otsakkeen, antaa sovellustason välineistön käsitellä esitarkistus ja varmistaa otsikkeet vastauksessa, jonka selain todella vastaanottaa. Jos otsake puuttuu yhä tämän jälkeen, seuraava epäilty on yleensä välineistön järjestys tai infrastruktuuri selaimen ja Expressin välillä, ei itse etupään fetch-kutsu.

Viralliset viitteet

• Express.js cors -välineistön dokumentaatio — määritysvaihtoehdot, dynaamiset alkuperät, uskoja ja esitarkistuskäyttäytyminen.
• Express.js välineistösopas — sovellusvälineistö ja pyyntöjen käsittelyjärjestys.
• MDN: CORS-otsake Access-Control-Allow-Origin puuttuu — tämän tarkka selaimen virheen merkitys.
• MDN CORS-turvallisuusmäärityssopas — ohjeet sallittujen alkuperien rajoittamisesta ja uskoja vaativan pääsyn käsittelystä.