كيف تصلح أخطاء CORS (ولماذا تحدث)

خطأ CORS يعني أن صفحتك حاولت قراءة استجابة من أصل مختلف (نطاق آخر أو منفذ أو بروتوكول آخر)، ولم يرسل ذلك الخادم ترويسات تقول إن هذا مسموح. يمنع المتصفح الاستجابة لحماية المستخدمين. تصلحه في الخادم، بإرجاع ترويسة Access-Control-Allow-Origin لأصل موقعك ومعالجة طلبات OPTIONS المسبقة، أو تتجنبه بإرسال الطلب عبر خادمك الخلفي على نفس الأصل.

هو من أكثر الأخطاء إرباكاً في تطوير الويب، لأن الطلب غالباً ما يصل إلى الخادم بشكل سليم. يشرح هذا الدليل ما يحدث، وكيف تصلح كل نوع من هذه الأخطاء.

ما معنى «الأصل»

الأصل هو مزيج من البروتوكول والنطاق والمنفذ:

يتبع المتصفح سياسة الأصل الواحد (same-origin policy): يستطيع JavaScript في الصفحة قراءة الاستجابات من أصله بحرية، لكن ليس من الأصول الأخرى. أما CORS (Cross-Origin Resource Sharing، أي مشاركة الموارد بين المصادر) فهو النظام الذي يسمح للخادم بالموافقة صراحةً: «يحق للصفحات القادمة من هذه الأصول قراءة ردودي».

هناك نتيجتان تفاجئان الناس:

• غالباً ما يصل الطلب إلى الخادم. يمنع CORS عادةً كودك من قراءة الاستجابة، ولا يمنع الخادم من استلام الطلب. قد يكون طلب POST قد حُفظ، رغم أنك رأيت خطأً.
• المتصفحات وحدها تفرضه. curl وPostman والكود الذي يعمل على الخادم يتجاهلون CORS تماماً. لهذا السبب لا يعني «يعمل في Postman» شيئاً بخصوص CORS.

الخطوة 1: اقرأ الخطأ كما هو

افتح أدوات المطوّر (انقر بالزر الأيمن ← Inspect أو «فحص»)، واذهب إلى تبويب Console، واقرأ الرسالة كاملة. صياغة Chrome تخبرك بنوع المشكلة:

ثم افتح تبويب Network وابحث عن الطلب الفاشل (وأي طلب OPTIONS قبله)، وانظر إلى رمز الحالة وترويسات الاستجابة.

تحقق من رمز الحالة أولاً. كثير من «أخطاء CORS» هي في الحقيقة خطأ في الخادم متخفٍّ. إذا تعطّل الخادم أو أرجع 404، فإن رسالة الخطأ لا تحمل غالباً ترويسات CORS، فيُبلغ المتصفح عن CORS بدلاً من المشكلة الحقيقية. أصلح الخطأ 500 أو 404، وقد يختفي خطأ CORS معه.

الخطوة 2: قرّر إن كان يجب أن يستدعي المتصفح هذه الواجهة البرمجية أصلاً

قبل إضافة الترويسات، اسأل: هل يجب أن يتصل المتصفح بهذه الواجهة مباشرة؟

• واجهة برمجية لطرف ثالث تحتاج مفتاحاً سرياً (مثل OpenAI أو مفتاح Stripe السري أو معظم خدمات البريد) لا يجب أبداً استدعاؤها من المتصفح. فالمفتاح سيكون مرئياً لكل زائر. استدعها من خادمك الخلفي، فتختفي مشكلة CORS، لأن الطلبات بين الخوادم لا تخضع لـ CORS. راجع كيف تحمي مفاتيح الواجهات البرمجية.
• واجهة برمجية لطرف ثالث لا تتحكم فيها ولا ترسل ترويسات CORS، لا يمكن إصلاحها من جهتك. استدعها من خادمك الخلفي.
• واجهتك البرمجية الخاصة يمكن إصلاحها بضبطها بشكل صحيح. تابع أدناه.

الخطوة 3: أصلح الأمر في خادمك

يجب أن يضيف الخادم الترويسات الصحيحة إلى ردوده، بما في ذلك ردود الخطأ.

للطلب الفعلي، أرسل:

• Access-Control-Allow-Origin: https://myapp.com (الأصل الدقيق لواجهتك الأمامية، بدون شرطة مائلة في النهاية)
• Vary: Origin، إذا كانت القيمة تعتمد على الأصل الذي طلب الاستجابة

لطلب OPTIONS المسبق، أرجع حالة نجاح (200 أو 204) مع:

• Access-Control-Allow-Origin: https://myapp.com
• Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE
• Access-Control-Allow-Headers: Content-Type, Authorization (كل ترويسة مخصصة ترسلها)
• اختيارياً Access-Control-Max-Age: 600، ليخزّن المتصفح الطلب المسبق مؤقتاً لفترة

معظم أطر العمل لديها حزمة أو إعداد يقوم بذلك. في Express توجد حزمة cors، وفي FastAPI توجد CORSMiddleware، وفي ASP.NET Core توجد AddCors، وفي Spring توجد @CrossOrigin أو إعداد CORS. هذا مثال نموذجي لـ Express:

import cors from "cors";

app.use(cors({
  origin: ["https://myapp.com", "http://localhost:5173"],
  credentials: true,
}));

ضع معالجة CORS قبل مساراتك وقبل التحقق من تسجيل الدخول، حتى لا يُرفض الطلب المسبق (الذي لا يحمل تسجيل دخول) بخطأ 401.

مع منشئ تطبيقات بالذكاء الاصطناعي، صِف الإعداد بدقة:

الواجهة الأمامية على https://myapp.com تستدعي الواجهة البرمجية على https://api.myapp.com وتحصل على خطأ «Response to preflight request doesn't pass access control check». اضبط CORS على الواجهة البرمجية ليسمح بالأصل https://myapp.com وأصل المعاينة فقط، وليسمح بطرق GET وPOST وPATCH وDELETE مع ترويستي Content-Type وAuthorization، وليعالج OPTIONS قبل التحقق من الهوية، وليتضمن ترويسات CORS في ردود الأخطاء أيضاً.

الخطوة 4: تعامل مع ملفات تعريف الارتباط وبيانات الاعتماد

إذا كانت واجهتك الأمامية ترسل ملفات تعريف الارتباط (مثل جلسة تسجيل الدخول) إلى أصل آخر، فيجب أن يتفق الطرفان:

• تضبط الواجهة الأمامية credentials: "include" في fetch، أو withCredentials: true في axios.
• يرسل الخادم Access-Control-Allow-Credentials: true.
• يجب أن تكون قيمة Access-Control-Allow-Origin لدى الخادم الأصل الدقيق، وليس *.

كذلك تحتاج ملفات تعريف الارتباط عبر المواقع إلى SameSite=None; Secure، وبعض المتصفحات تقيّد ملفات تعريف الارتباط من الأطراف الثالثة أكثر من ذلك. وهذا سبب إضافي لتفضيل الطريقة الواردة في الخطوة 5.

الخطوة 5: تجنّب CORS بإعداد من نفس الأصل

غالباً ما يكون أنظف حل ألا تُجري طلبات عبر أصول مختلفة من الأساس. قدّم الواجهة البرمجية من نفس أصل الصفحة، مثلاً على https://myapp.com/api/...:

• في بيئة التطوير، تستطيع معظم خوادم التطوير عمل وكيل (proxy). يستطيع server.proxy في Vite أن يحوّل /api إلى خادمك الخلفي على منفذ آخر، فلا يتعامل المتصفح إلا مع أصل واحد.
• في الإنتاج، وجّه /api إلى الخادم الخلفي عبر إعدادات إعادة التوجيه أو الوكيل في منصة الاستضافة، أو قدّم الواجهة الأمامية والواجهة البرمجية من خادم واحد.

عندها تستدعي الواجهة الأمامية مساراً نسبياً مثل fetch("/api/orders"). لا يوجد طلب عبر أصول، ولا طلب مسبق بين الأصول، ولا مشاكل مع ملفات تعريف الارتباط. كما أنك لا تكتب نطاق واجهة برمجية ثابتاً يختلف بين المعاينة والإنتاج.

غيّر الواجهة الأمامية لتستدعي الخادم الخلفي بمسارات /api نسبية بدلاً من رابط كامل، وأعدّ وكيلاً للتطوير يحوّل /api إلى خادم الواجهة البرمجية. ثم احذف أي إعدادات CORS لم نعد نحتاجها.

ما الذي يجب ألا تفعله

• mode: "no-cors" في fetch. لا يتجاوز شيئاً، بل يعطي كودك استجابة فارغة لا يمكن قراءتها.
• إضافات المتصفح التي تعطّل CORS. تغيّر متصفحك أنت فقط. كل زائر سيرى الخطأ نفسه.
• خدمات «وكيل CORS» العامة لتطبيقات حقيقية. يمكنها قراءة كل ما يمر عبرها وتعديله، وقد تتوقف عن العمل.
• Access-Control-Allow-Origin: * على واجهة تستخدم تسجيل الدخول. لن يعمل مع بيانات الاعتماد على أي حال، وهو خيار افتراضي خاطئ للبيانات الخاصة.
• إعادة أي ترويسة Origin كما هي مع السماح ببيانات الاعتماد. هذا يسمح لأي موقع بإرسال طلبات باسم مستخدميك وهم مسجّلو الدخول. استخدم قائمة سماح محددة.

أسباب شائعة في التطبيقات المبنية بالذكاء الاصطناعي

CORS في Mythex

عندما يكون لمشروع Mythex موقع وخادم واجهة برمجية، يعمل الاثنان كخدمتين في المشروع نفسه، ويمكنك التنقل بينهما في المعاينة. اطلب من الوكيل أن تستدعي الواجهة الأمامية الخادم الخلفي عبر مسار /api نسبي، يُوجَّه عبر وكيل في بيئة التطوير، فهذا يتجنب معظم مشاكل CORS. إذا احتجت فعلاً إلى استدعاءات بين أصول مختلفة، فأعطِ الوكيل نص الخطأ كما يظهر في Console والأصول المعنية. تحقق من النتيجة في التطبيق المنشور أيضاً، لأن عنوانه يختلف عن عنوان المعاينة. راجع التطبيقات متعددة الخدمات والواجهات البرمجية الخلفية في الوثائق، وأدلتنا عن تصحيح تطبيق بُني بالذكاء الاصطناعي والواجهة الأمامية مقابل الخلفية.

قائمة مراجعة CORS

• قرأت رسالة الخطأ الكاملة في Console ورمز حالة الطلب الفاشل
• استبعدت وجود خطأ 404 أو 500 مخفي
• الواجهات التي تحتاج مفتاحاً سرياً تُستدعى من الخادم الخلفي، لا من المتصفح
• يرسل الخادم Access-Control-Allow-Origin مع أصول مسموح بها بدقة
• طلب OPTIONS المسبق يُجاب بالطرق والترويسات المسموحة، وقبل التحقق من الهوية
• ترويسات CORS موجودة في ردود الأخطاء أيضاً
• بيانات الاعتماد: أصل دقيق، وAllow-Credentials: true، وإعدادات ملفات تعريف الارتباط الصحيحة
• أصل المعاينة والنشر والنطاق المخصص مشمولة، أو استُخدمت مسارات /api نسبية
• لا توجد اختصارات مثل no-cors أو الوكلاء العامين أو إعادة أي أصل كما هو

الأسئلة