رفع خطای CORS در جاوا اسکریپت + آموزش کامل حل مشکل

خطای "CORS" در جاوا اسکریپت زمانی رخ می‌دهد که مرورگر به‌دلیل محدودیت‌های امنیتی، اجازه ارسال درخواست بین دو "Origin" متفاوت را ندهد. برخلاف تصور بسیاری از افراد این مشکل معمولا از کدهای جاوا اسکریپت نیست و بیشتر به تنظیمات سمت سرور و "Header"های پاسخ مربوط می‌شود. در ادامه این مقاله از مجله سبزلرن، علاوه‌بر آموزش رفع خطای CORS در جاوا اسکریپت، یاد می‌گیریم این خطا دقیقاً چرا ایجاد می‌شود، چگونه علت آن را پیدا کنیم و چه روش‌هایی برای رفع آن وجود دارد.

خطای CORS چیست؟

خطای CORS یکی از رایج‌ترین خطاهایی است که هنگام ارتباط بین فرانت‌اند و بک‌اند رخ می‌دهد و زمانی اتفاق می‌افتد که مرورگر اجازه دسترسی یک Origin به منابع موجود در Origin دیگر را صادر نکند. برای رفع خطای CORS در جاوا اسکریپت ابتدا باید بدانیم که این خطا معمولا به‌دلیل محدودیت‌های امنیتی مرورگر و نه به دلیل مشکل در کدهای جاوا اسکریپت ایجاد می‌شود. مرورگرها برای جلوگیری از حملاتی مانند سرقت اطلاعات کاربران، سیاستی به نام "Same-Origin Policy" دارند که طبق آن یک وب‌سایت فقط می‌تواند به منابعی دسترسی داشته باشد که از همان Origin ارائه شده‌اند؛ مگر این‌که سرور مقصد به‌صورت صریح اجازه این دسترسی را صادر کند. در واقع هر Origin از سه بخش تشکیل می‌شود:

• Protocol (مانند HTTP یا HTTPS)

• Domain

• Port

برای مثال:

https://sabzlearn.ir

با

https://api.sabzlearn.ir

دو Origin متفاوت محسوب می‌شوند؛ زیرا دامنه آن‌ها متفاوت است. همچنین این دو نیز متفاوت هستند:

http://localhost:3000

http://localhost:5173

زیرا شماره Port تغییر کرده است.

به همین دلیل زمانی که پروژه "React" یا "Vue" روی پورت ۵۱۷۳ اجرا می‌شود و قصد دارد به API موجود روی پورت ۸۰۰۰ درخواست ارسال کند، مرورگر ابتدا قوانین CORS را بررسی می‌کند. اگر سرور مجوز لازم را صادر نکرده باشد، درخواست مسدود می‌شود.

پیام خطای CORS چگونه نمایش داده می‌شود؟

بسته به مرورگر و نوع درخواست، پیغام خطای CORS در جاوا اسکریپت ممکن است کمی متفاوت باشد؛ اما مفهوم همه آن‌ها یکسان است. رایج‌ترین پیام‌ها عبارت‌اند از:

Access to fetch at 'https://example.com/api'

from origin 'http://localhost:5173'

has been blocked by CORS policy.

یا:

No 'Access-Control-Allow-Origin'

header is present on the requested resource.

گاهی نیز با خطای زیر مواجه می‌شوید:

Response to preflight request doesn't pass access control check.

چرا خطای CORS رخ می‌دهد؟

باید بدانیم که خطای CORS معمولا زمانی رخ می‌دهد که بین تنظیمات امنیتی مرورگر و مجوزهای تعریف‌شده در سمت سرور هماهنگی وجود نداشته باشد. در فرآیند رفع خطای CORS در جاوا اسکریپت بسیاری از توسعه‌دهندگان ابتدا به سراغ تغییر کدهای فرانت‌اند می‌روند، اما در بیشتر مواقع مشکل اصلی در تنظیمات API یا سرور مقصد است. در جدول زیر مهم‌ترین دلایل بروز خطای CORS و توضیحات هر کدام را بررسی می‌کنیم.

روش‌های قطعی رفع خطای CORS

برای رفع خطای CORS ابتدا باید بدانید که این مشکل معمولاً از سمت Backend ایجاد می‌شود. مرورگر تنها درخواست‌هایی را اجرا می‌کند که سرور مقصد اجازه دسترسی به آن‌ها را صادر کرده باشد. به‌طور کلی سه روش اصلی برای حل مشکل CORS وجود دارد:

تنظیم CORS در سمت سرور (راهکار استاندارد و امن)

رفع خطای CORS در سمت بک‌اند بهترین و اصولی‌ترین روش است که با تنظیم "Header"های مربوط به CORS در سرور انجام می‌شود. در این حالت سرور مشخص می‌کند چه دامنه‌هایی اجازه ارسال درخواست دارند.مهم‌ترین Headerهای CORS عبارت‌اند از:

Access-Control-Allow-Origin

این Header مشخص می‌کند چه Origin هایی اجازه دسترسی دارند. به‌طور مثال:

Access-Control-Allow-Origin: https://example.com

یعنی فقط درخواست‌هایی که از دامنه example.com ارسال شوند، مجاز هستند. برای توسعه محلی می‌توان از مقدار زیر استفاده کرد:

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

اما استفاده از مقدار زیر در پروژه‌های واقعی توصیه نمی‌شود:

Access-Control-Allow-Origin: *

زیرا تمام دامنه‌ها اجازه دسترسی خواهند داشت.

برای درک بهتر کار با API و درخواست‌های HTTP در جاوااسکریپت، دوره آموزش جاوا اسکریپت نقطه شروع مناسبی برای تقویت مهارت‌های شما است.

تنظیم CORS در Node.js و Express

اگر از Node.js و Express استفاده می‌کنید، ساده‌ترین روش استفاده از پکیج cors است. ابتدا پکیج را نصب کنید:

npm install cors

سپس در فایل اصلی پروژه:

const express = require("express");

const cors = require("cors");

const app = express();

app.use(cors());

app.listen(3000);

با این تنظیم، تمام درخواست‌های Cross-Origin مجاز خواهند بود. اما برای امنیت بیشتر، بهتر است دامنه‌های مجاز را مشخص کنید:

app.use(

  cors({

origin: "http://localhost:5173"

  })

);

در این حالت فقط پروژه Frontend شما اجازه ارسال درخواست خواهد داشت.

برای یادگیری پروژه‌محور زبان Node.js و مسلط شدن بر موضوعاتی مثل تنظیم CORS در Node.js، دوره آموزش Node.js را از دست ندهید.

تنظیم CORS در Laravel

در Laravel معمولاً تنظیمات CORS داخل فایل زیر قرار دارد:

config/cors.php

نمونه تنظیم:

return [

'paths' => ['api/*'],

'allowed_methods' => [

     '*'

],

'allowed_origins' => [

     'http://localhost:5173'

],

'allowed_headers' => [

     '*'

],

];

بعد از تغییر تنظیمات، کش Laravel را پاک کنید:

php artisan config:clear

تنظیم CORS در Django

در Django ابتدا باید پکیج زیر نصب شود:

pip install django-cors-headers

سپس آن را به INSTALLED_APPS اضافه کنید:

INSTALLED_APPS = [

...

"corsheaders",

]

Middleware مربوط به CORS:

MIDDLEWARE = [

    "corsheaders.middleware.CorsMiddleware",

]

سپس دامنه مجاز را مشخص کنید:

CORS_ALLOWED_ORIGINS = [

"http://localhost:5173"

]

برای یادگیری Django به صورت پروژه‌محور از پایه تا سطح حرفه‌ای، پیشنهاد می‌کنیم در دوره آموزش جنگو ثبت نام کنید.

رفع موقت CORS در سمت فرانت‌اند

گاهی هنگام توسعه پروژه Frontend، دسترسی به Backend ندارید یا امکان تغییر تنظیمات سرور وجود ندارد. در این شرایط می‌توان از روش‌های موقت استفاده کرد.

استفاده از Proxy در React و Vite

در پروژه‌های React می‌توان درخواست‌ها را از طریق Proxy ارسال کرد. نمونه تنظیم در Vite:

export default {

  server: {

proxy: {

   "/api": {

     target: "http://localhost:8000",

     changeOrigin: true

   }

}

  }

}

حالا به جای:

fetch("http://localhost:8000/api/users")

از:

fetch("/api/users")

استفاده می‌کنید؛ در این حالت مرورگر تصور می‌کند درخواست به همان Origin ارسال شده است.

استفاده از افزونه‌های مرورگر

برخی افزونه‌های مرورگر امکان غیرفعال کردن موقت CORS را برای تست فراهم می‌کنند، اما این روش فقط روی سیستم توسعه‌دهنده کاربرد دارد و برای کاربران واقعی سایت یا محیط Production قابل استفاده نیست. بنابراین از این راهکار تنها برای Debug و بررسی موقت مشکل استفاده می‌شود و راه‌حل اصلی، تنظیم صحیح CORS در سمت سرور است.

تفاوت CORS و Same-Origin Policy چیست؟

در واقع "Same-Origin Policy" یک قانون امنیتی در مرورگر است که به‌صورت پیش‌فرض مانع دسترسی یک "Origin" به منابع Origin دیگر می‌شود، در حالی‌که CORS مکانیزمی برای کنترل و مدیریت همین محدودیت است. این دو مفهوم ارتباط نزدیکی با یکدیگر دارند، اما کاربردشان متفاوت است. به بیان ساده Same-Origin Policy دسترسی بین دامنه‌های مختلف را مسدود می‌کند و CORS با استفاده از Headerهای مشخص از سمت سرور، در صورت تایید، اجازه این دسترسی را صادر می‌کند.

آیا می‌توان CORS را به طور کامل غیرفعال کرد؟

امکان غیرفعال کردن CORS از نظر فنی در محیط توسعه وجود دارد، اما در پروژه‌های واقعی توصیه نمی‌شود. زیرا CORS یک قابلیت امنیتی مهم مرورگر است و حذف آن می‌تواند کاربران را در معرض خطر قرار دهد. برای مثال اگر مرورگر هیچ محدودیتی برای درخواست‌های Cross-Origin نداشته باشد، یک سایت مخرب می‌تواند درخواست‌هایی به سایت‌های دیگر ارسال کند و به اطلاعات حساس کاربران دسترسی پیدا کند.

چک‌لیست سریع رفع خطای CORS

خطای CORS یکی از رایج‌ترین مشکلات در ارتباط بین Frontend و Backend است که معمولاً به دلیل تنظیمات نادرست دسترسی بین Originهای مختلف ایجاد می‌شود. برای رفع این خطا باید بررسی کنید درخواست از کجا ارسال شده، سرور چه Headerهایی برمی‌گرداند و تنظیمات CORS در سمت Backend به‌درستی انجام شده است. مراحل زیر یک چک‌لیست سریع برای شناسایی و رفع مشکل CORS ارائه می‌دهد:

• بررسی Origin درخواست: ابتدا مشخص کنید درخواست از چه دامنه، پورت یا پروتکلی ارسال می‌شود؛ زیرا تفاوت در این موارد باعث ایجاد Cross-Origin می‌شود. در مرورگر از مسیر Developer Tools > Network، درخواست موردنظر را باز کرده و مقدار Origin در Request Header را بررسی کنید.

• بررسی Headerهای پاسخ سرور: بررسی کنید پاسخ سرور شامل Header مهم Access-Control-Allow-Origin باشد تا مرورگر اجازه دسترسی به منبع را صادر کند. در صورت نیاز، Headerهای Access-Control-Allow-Methods و Access-Control-Allow-Headers را نیز برای متدها و Headerهای مجاز بررسی کنید.

• بررسی درخواست Preflight: اگر درخواست شامل متدهایی مانند POST، PUT، PATCH، DELETE یا Header سفارشی باشد، مرورگر ابتدا یک درخواست OPTIONS ارسال می‌کند. مطمئن شوید سرور این درخواست Preflight را به‌درستی پاسخ می‌دهد و Headerهای لازم CORS را در پاسخ قرار می‌دهد.

• بررسی تنظیمات Backend: فعال بودن CORS در سمت Backend ضروری است و باید تنظیمات مربوط به دامنه‌های مجاز به‌درستی انجام شود. در فریم‌ورک‌های مختلف مانند Express، Laravel، Django و Spring Boot باید تنظیمات مخصوص CORS بررسی و اصلاح شود.

• بررسی Credentialها: اگر برنامه از Cookie، Session یا اطلاعات احراز هویت استفاده می‌کند، باید گزینه Access-Control-Allow-Credentials: true در پاسخ سرور فعال شود. همچنین در این شرایط نمی‌توان از مقدار * برای Access-Control-Allow-Origin استفاده کرد و باید Origin مشخصی تعریف شود.