به محتوای اصلی

خطای CORS در اتصال وب‌اپ به API؛ ۴ علت و راه‌حل

خطای CORS یعنی مرورگر پاسخ را مسدود کرده، نه اینکه سرور خراب باشد. چهار علت رایج (credentials، هدر سفارشی، PUT، آدرس اشتباه) را با کد درست ببینید.

عاطفه امیری۳ دقیقه مطالعه
در این مطلب

خطای CORS یعنی مرورگر پاسخ سرور را گرفته ولی اجازه نداده کد جاوااسکریپت شما آن را بخواند. سرور خراب نیست و کلیدتان هم لزوماً اشتباه نیست؛ مرورگر دارد از کاربر محافظت می‌کند. اگر API شما فیکارو باشد، این خطا تقریباً همیشه از یکی از چهار اشتباه کوچک می‌آید، و هیچ‌کدامش با افزونه‌ی «Allow CORS» یا پروکسی عمومی درست نمی‌شود. این مقاله اول می‌گوید CORS دقیقاً چه چیزی را چک می‌کند، بعد چهار علت و راه‌حلشان را با کد نشان می‌دهد.

CORS چیست و چرا فقط در مرورگر پیش می‌آید؟

مرورگر وقتی صفحه‌ی https://myapp.ir می‌خواهد به https://api.fikaro.ir درخواست بزند، پیش از دادن پاسخ به کدتان هدرهای پاسخ را نگاه می‌کند. اگر سرور با هدر Access-Control-Allow-Origin نگفته باشد این مبدأ مجاز است، پاسخ را مسدود می‌کند و در کنسول خطای CORS می‌بینید.

برای درخواست‌های غیرساده (مثلاً با هدر Authorization یا بدنه‌ی JSON) مرورگر قبلش یک درخواست آزمایشی OPTIONS به نام preflight می‌فرستد و می‌پرسد: «این روش و این هدرها مجازند؟». اگر جواب منفی باشد، درخواست اصلی اصلاً فرستاده نمی‌شود.

این چک فقط در مرورگر هست. به همین دلیل همان درخواست در Postman و curl درست کار می‌کند و در وب‌اپ خطا می‌دهد، و اپ فلاتر و ری‌اکت‌نیتیو (غیر وب) هرگز CORS نمی‌بینند.

فیکارو چه سیاستی دارد؟

API هر پروژه (/{slug}/v1/* و فایل‌های عمومی) از هر مبدأیی پاسخ می‌دهد، چون وب‌اپ شما روی دامنه‌ی خودتان یا localhost است و فیکارو نمی‌تواند از قبل بداند کجاست. در عوض این مرزها را دارد:

موردمقدار
مبدأ مجازهمه (*)
کوکی و credentialsغیرفعال
روش‌های مجازGET ،POST ،PATCH ،DELETE ،OPTIONS
هدرهای مجاز درخواستAuthorization ،Content-Type ،Accept-Language
هدرهای قابل‌خواندن در پاسخRetry-After و X-RateLimit-* و X-Pagination-Limit-Clamped و Content-Disposition

دلیل ایمن بودنِ «همه‌ی مبدأها»: هیچ اعتبارنامه‌ای خودکار با مرورگر نمی‌رود. کلید و توکن را خودِ کد شما در هدر Authorization می‌گذارد، پس صفحه‌ی مخرب نمی‌تواند از طرف کاربر درخواست بفرستد. حالا چهار خطای رایج.

علت ۱: credentials یا withCredentials روشن است

رایج‌ترین علت. اگر در fetch گذاشته‌اید credentials: "include" یا در axios withCredentials: true، مرورگر پاسخی را که * دارد و credentials ندارد نمی‌پذیرد. چون فیکارو کوکی نمی‌خواهد، آن را بردارید:

const res = await fetch("https://api.fikaro.ir/my-shop/v1/product", {
  headers: { Authorization: "Bearer " + key },
});

علت ۲: هدر سفارشی مثل X-API-Key

اگر کلید را در هدری غیر از Authorization فرستاده‌اید، preflight شکست می‌خورد، چون فقط سه هدر بالا مجازند. کلید (و توکن کاربر) همیشه به شکل Authorization: Bearer … می‌رود. هدرهای سفارشی دیگر را هم حذف یا به فیلد بدنه منتقل کنید.

علت ۳: متد PUT

ویرایش در فیکارو با PATCH است و فقط فیلدهایی را عوض می‌کند که می‌فرستید. PUT در فهرست مجاز نیست و preflight را رد می‌کند. اگر کلاینت قدیمی‌ای دارید که PUT می‌زند، به PATCH تغییرش بدهید.

علت ۴: آدرس اشتباه، نه CORS

اپ شما باید به https://api.fikaro.ir/{slug}/v1/... درخواست بزند. مسیرهای /api/platform/* مال خود پنل فیکاروست و عمداً فقط برای همان یک مبدأ باز است؛ اگر آن را از وب‌اپ خودتان صدا بزنید خطای CORS می‌گیرید و راه‌حلش عوض کردن آدرس است، نه تنظیمی.

وقتی کنسول می‌گوید CORS، حتماً تب Network را هم باز کنید. گاهی علت واقعی یک وضعیت ۴۰۱ یا ۴۲۹ است که مرورگر پشت پیام CORS پنهانش کرده؛ پس کد وضعیت واقعی و بدنه‌ی problem را همان‌جا بخوانید.

چیزهایی که حل نمی‌کنند

افزونه‌ی «Allow CORS» فقط روی مرورگر خودتان اثر دارد، نه کاربرانتان. پروکسی‌های عمومی مثل cors-anywhere کلید شما را از سروری ناشناس رد می‌کنند، که از نظر امنیتی بدترین کار ممکن است. اگر واقعاً نمی‌خواهید کلید در مرورگر باشد، درست‌ترین کار این است که درخواست‌های حساس را از سرور خودتان بزنید و در مرورگر فقط کلید عمومی (فقط‌خواندنی) را بگذارید؛ تفاوت کلیدها در امنیت API آمده است.

برای ساختن لایه‌ی ارتباط کامل، اتصال فرانت‌اند به API را ببینید، و جزئیات توکن کاربر در کلیدها و احراز هویت است. می‌خواهید خودتان امتحان کنید؟ ثبت‌نام یک پروژه‌ی آماده می‌دهد.

سوالات متداول

چرا در Postman کار می‌کند ولی در مرورگر خطای CORS می‌دهد؟
چون CORS چکی است که فقط مرورگر انجام می‌دهد. Postman و curl هدرهای Access-Control را نادیده می‌گیرند. در مرورگر معمولاً علت یکی از این‌هاست: credentials روشن، هدر سفارشی مثل X-API-Key، متد PUT، یا آدرس اشتباه.
چطور خطای CORS را در localhost حل کنیم؟
API فیکارو از هر مبدأ از جمله localhost پاسخ می‌دهد، پس تنظیمی لازم نیست. credentials را خاموش کنید، کلید را فقط در هدر Authorization بفرستید و برای ویرایش از PATCH استفاده کنید.
آیا اپ فلاتر هم خطای CORS می‌گیرد؟
نسخه‌ی موبایل و دسکتاپ نه، چون مرورگر در کار نیست. فقط فلاتر وب (و هر اپ دیگر داخل مرورگر) مشمول CORS است.

مطالب مرتبط