Kā novērst CORS galvenes Access-Control-Allow-Origin trūkumu Express.js

Ja pārlūks rāda kļūdu CORS header 'Access-Control-Allow-Origin' missing, svarīgākā norāde nav tā, ka Express.js nesaņēma pieprasījumu. Pārlūks ziņo, ka atbildē nebija CORS galvenes, kas atļautu lapas izcelsmei izlasīt šo atbildi. Tādēļ risinājums jāmeklē serverī vai jūsu kontrolējamā starpniekserverī (proxy), nevis nejaušā klienta puses iestatījumā.

Ilustratīvs piemērs, ko izmantojam visā šajā rokasgrāmatā: iedomājieties uzdevumu paneli, kas darbojas adresē http://localhost:5173 un veic izsaukumus uz Express API adresē http://localhost:3000/api/tasks. Pārlūks bloķē JavaScript piekļuvi API atbildei, jo API neatgriež galveni Access-Control-Allow-Origin. Tas ir hipotētisks mācību piemērs, nevis apgalvojums par reālu testu, produktu vai izvietošanu.

Pārbaudīts 2026. gada 11. septembrī: oficiālā Express CORS vidusprogrammas dokumentācija norāda cors versiju 2.8.6 un apraksta to kā vidusprogrammu, kas iestata CORS atbilžu galvenes. Pašreizējais Express pakotnes saraksts ir 5.x paaudzē, tāpēc šī rokasgrāmata dod priekšroku lietojumprogrammas līmeņa vidusprogrammai, paļaujoties uz vecākiem savvaļas rakstura ceļu modeļiem.

Ko patiesībā nozīmē šī kļūda

Tīmekļa lapai ir izcelsme (origin), ko veido tās shēma, saimniekdators un ports. Piemērā http://localhost:5173 un http://localhost:3000 ir dažādas izcelsmes, jo to porti atšķiras. Pārlūka vienādas izcelsmes politika parasti neļauj vienā izcelsmē esošam JavaScript izlasīt resursus no citas izcelsmes, ja mērķa serveris neatgriež atbilstošas Cross-Origin Resource Sharing (CORS) galvenes.

MDN dokumentācija par šo konkrēto kļūdu skaidro, ka atbildē trūkst nepieciešamās Access-Control-Allow-Origin galvenes. Ja kontrolējat serveri, jums jākonfigurē pieprasītās vietnes izcelsme kā atļautā izcelsme. Publiskiem, bez autentifikācijas datiem paredzētiem API var būt piemērots *; privātiem vai ar autentifikācijas datiem paredzētiem API izmantojiet konkrētas uzticamas izcelsmes. Skatiet MDN skaidrojumu par trūkstošo Access-Control-Allow-Origin kļūdu.

1. solis: Pārliecinieties, ka problēma ir CORS, un identificējiet precīzo izcelsmi

Atveriet pārlūka izstrādātāja rīkus un pārbaudiet gan Konsoli, gan Tīkla paneli. Precīzi pierakstiet frontenda izcelsmi tādu, kādu to nosūta pārlūks. Mūsu ilustratīvajā gadījumā tā ir http://localhost:5173.

Nesamaziniet izcelsmi tikai līdz saimniekdatora vārdam. Šīs ir dažādas izcelsmes: http://localhost:5173, http://localhost:3000, http://127.0.0.1:5173 un https://localhost:5173. Arī ražošanas atļauju sarakstam ir jānošķir https://app.example.com no citām shēmām, saimniekdatoriem, portiem vai apakšdomēniem, ja vien jūs apzināti neatļaujat tos.

Ja API atbilde ir 404, 500, pāradresācija, autentifikācijas kļūme vai starpniekservera ģenerēta kļūdu lapa, pārbaudiet arī šo atbildi. CORS galvenēm ir jābūt klāt atbildē, ko pārlūks faktiski saņem. Lietojumprogrammas ceļa labošana nepalīdzēs, ja apgrieztais starpniekserveris, CDN, slodzes līdzsvarotājs vai kļūdu apstrādātājs atgriež citu atbildi bez galvenes.

2. solis: Instalējiet un ielādējiet oficiālo Express CORS vidusprogrammu

Lielākajai daļai Express lietojumprogrammu vismazāk kļūdām pakļautais risinājums ir cors vidusprogramma, ko uztur Express projekts. Oficiālajā Express vidusprogrammu lapā tā ir norādīta kā vidusprogramma, ko uztur Express.js komanda. Instalējiet to savā API projektā:

npm install cors

Tad ielādējiet to blakus Express:

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

const app = express();

Oficiālā dokumentācija ir pieejama Express.js cors vidusprogrammas dokumentācijā. Express arī dokumentē, kā lietojumprogrammas līmeņa vidusprogramma darbojas pieprasījumu secībā Express.js: Vidusprogrammas izmantošana.

3. solis: Apzināti atļaujiet frontenda izcelsmi

Hipotētiskajam panelim konfigurējiet precīzo izstrādes izcelsmi pirms ceļiem, kam nepieciešams 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);

Ir svarīgi novietot app.use(cors(corsOptions)) pirms API ceļiem, jo Express apstrādā vidusprogrammas secībā. Vidusprogrammai ir jābūt iespējai pievienot atbildes galvenes pirms ceļa vai iepriekšējās vidusprogrammas beidz pieprasījumu.

Patiesi publiskam API, kas neizmanto autentifikācijas datus, app.use(cors()) izmanto vidusprogrammas noklusējuma atļaujošo izcelsmes uzvedību. Tas ir ērti, bet tam nevajadzētu būt jūsu automātiskajai izvēlei ražošanā. MDN iesaka ierobežot Access-Control-Allow-Origin līdz minimālajām nepieciešamajām izcelsmēm un resursiem. Skatiet MDN CORS drošības norādījumus.

Atļaujiet vairākas zināmas izcelsmes, neatļaujot visiem

Biežā ražošanas iestatījumā ir lokāls frontend, testēšanas (staging) frontend un ražošanas frontend. Izmantojiet atļauju sarakstu un validējiet ienākošo izcelsmi:

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

Zars !origin ļauj klientiem, kas nesūta Origin galveni, piemēram, daudziem servera-servera pieprasījumiem un komandrīka rīkiem. Vai vēlaties šādu uzvedību, ir lietojumprogrammas politikas lēmums; CORS pats par sevi nav autentifikācija.

4. solis: Pārbaudiet vienkāršo pieprasījumu un jebkuru iepriekšējo pārbaudi (preflight)

Pārlādējiet frontend un pārbaudiet Tīkla paneli. Panākumu nosacījums nav tikai 200 statuss. Pārbaudiet atbildes galvenes. Mūsu ilustratīvajā gadījumā API atbildei jāiekļauj izcelsmes vērtība, kas atbilst:

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

Daži starpizcelsmes pieprasījumi izraisa iepriekšēju pārbaudi (preflight): pārlūks nosūta OPTIONS pieprasījumu pirms īstā pieprasījuma, lai pārbaudītu, vai metode un galvenes ir atļautas. Pieprasījumi, kas izmanto metodes, piemēram, PUT vai DELETE, vai noteiktas pielāgotas/pieprasījuma galvenes, parasti prasa iepriekšēju pārbaudi. Kad cors ir instalēta kā lietojumprogrammas līmeņa vidusprogramma ar app.use(cors(...)), oficiālā Express dokumentācija nosaka, ka iepriekšējie pieprasījumi tiek apstrādāti visiem ceļiem.

Jūs varat arī pārbaudīt galvenes ārpus pārlūka, neapgalvojot, ka komandrīka klients īsteno CORS:

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

Tas ir noderīgi, lai redzētu, ko serveris atgriež, bet veiksmīgs curl vai API klienta pieprasījums nepierāda, ka pārlūka CORS ir konfigurēts pareizi. Express CORS dokumentācija skaidri norāda, ka CORS īsteno pārlūki; nepārlūka klienti nepiemēro tādu pašu lasīšanas ierobežojumu.

Pieprasījumi ar autentifikācijas datiem: nesajauciet autentifikācijas datus ar savvaļas rakstura izcelsmi

Ja frontendam ir jānosūta sīkdatnes vai HTTP autentifikācija starp izcelsmēm, abām pusēm ir nepieciešami saderīgi iestatījumi. Express pusē konfigurējiet konkrētu uzticamu izcelsmi un iespējojiet autentifikācijas datus:

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

Pārlūka pusē fetch pieprasījumam, kam nepieciešamas sīkdatnes, parasti tiek izmantots credentials: 'include'. Nepārslēdziet servera izcelsmi uz * pieprasījumam ar autentifikācijas datiem. Pārlūki nepieņem savvaļas rakstura Access-Control-Allow-Origin kopā ar autentifikācijas datiem paredzētu CORS tā, kā izstrādātāji bieži sagaida, un neierobežota izcelsme arī būtu slikta drošības robeža.

Kāpēc bieži lietotie “risinājumi” neizdodas

Kad Express kods izskatās pareizs, bet kļūda joprojām pastāv

Ja četri iepriekš minētie soļi neatrisina kļūdu, izsekojiet visu pieprasījuma ceļu, nevis aklpievienojiet vairāk galveņu.

• Pārbaudiet vidusprogrammu secību. CORS vidusprogrammai jādarbojas pirms ceļiem vai apstrādātājiem, kas beidz atbildi.
• Pārbaudiet pāradresācijas. Pārlūks var saņemt atbildi no cita URL vai izcelsmes pēc pāradresācijas.
• Pārbaudiet starpniekservera/CDN uzvedību. Nginx, vārteja, serverless platforma vai CDN var pievienot, noņemt, dublēt vai aizstāt galvenes.
• Pārbaudiet kļūdu atbildes. Parastā 200 atbildē var būt CORS galvenes, bet 401, 404 vai 500 atbildē to var nebūt.
• Pārbaudiet burtisko izcelsmi. Shēmai, saimniekdatora vārdam un portam ir nozīme; localhost un 127.0.0.1 nav savstarpēji aizvietojami CORS sakritībai.
• Pārbaudiet dubultās galvenes. MDN dokumentē, ka vairākas Access-Control-Allow-Origin galvenes nav atļautas. Skatiet MDN par vairākām Access-Control-Allow-Origin galvenēm.

Manuālas galvenes pret cors vidusprogrammu

Jūs varat iestatīt CORS galvenes manuāli, izmantojot Express atbilžu API, bet ir viegli palaist garām iepriekšējās pārbaudes uzvedību, autentifikācijas datu noteikumus, dinamisku izcelsmes sakritību, Vary: Origin vai kļūdu ceļus. Oficiālā cors vidusprogramma jau piedāvā opcijas origin, metodēm, atļautajām galvenēm, atklātajām galvenēm, autentifikācijas datiem, iepriekšējās pārbaudes uzvedībai un maksimālajam vecumam. Lielākajai daļai Express projektu šīs vidusprogrammas izmantošana saglabā politiku skaidru un vieglāk pārskatāmu.

Ja pats īstenojat dinamisku izcelsmes loģiku, nekad automātiski neatspoguļojiet katru ienākošo Origin vērtību tikai tāpēc, ka tā ir klāt. Validējiet to pret uzticamu kopu. MDN brīdina, ka neierobežota starpizcelsmes lasīšana var atklāt datus, īpaši, ja ir iesaistīti autentifikācijas dati.

Praktisks ražošanas pārbaudes saraksts

• Sarakstā iekļaujiet precīzas frontenda izcelsmes, kurām jāspēj izlasīt API.
• Ražošanā izmantojiet HTTPS izcelsmes un turiet izstrādes izcelsmes atsevišķi.
• Instalējiet CORS vidusprogrammu pirms aizsargātajiem API ceļiem, kam tā nepieciešama.
• Privātiem vai ar autentifikācijas datiem paredzētiem galapunktiem izmantojiet konkrētas izcelsmes.
• Pārlūkā pārbaudiet gan parastās atbildes, gan iepriekšējās pārbaudes OPTIONS atbildes.
• Pārbaudiet kļūdu ceļus, piemēram, 401, 404 un 500 atbildes, ja tās var tikt atgrieztas starp izcelsmēm.
• Uztveriet CORS kā pārlūka lasīšanas politiku, nevis kā autentifikāciju vai autorizāciju.

Ilustratīvajā uzdevumu paneļa scenārijā ilgstošais risinājums ir vienkāršs: identificējiet frontenda precīzo izcelsmi, konfigurējiet Express, lai tas atgrieztu atbilstošo CORS galveni, ļaujiet lietojumprogrammas līmeņa vidusprogrammai apstrādāt iepriekšējo pārbaudi un pārbaudiet galvenes atbildē, ko pārlūks faktiski saņem. Ja galvene joprojām trūkst pēc tam, nākamais aizdomās turamais parasti ir vidusprogrammu secība vai infrastruktūra starp pārlūku un Express, nevis pats frontenda fetch izsaukums.

Oficiālās atsauces

• Express.js cors vidusprogrammas dokumentācija — konfigurācijas opcijas, dinamiskas izcelsmes, autentifikācijas dati un iepriekšējās pārbaudes uzvedība.
• Express.js vidusprogrammu rokasgrāmata — lietojumprogrammas vidusprogramma un pieprasījumu apstrādes secība.
• MDN: CORS header Access-Control-Allow-Origin missing — šīs konkrētās pārlūka kļūdas nozīme.
• MDN CORS drošības konfigurācijas rokasgrāmata — norādījumi par atļauto izcelsmju ierobežošanu un autentifikācijas datu apstrādi.