كمطورين لـ JavaScript وTypeScript، غالبًا ما نواجه أخطاء غير متوقعة أثناء العمل مع أنظمة وحدات مختلفة. إحدى المشكلات الشائعة هي الخطأ "لا يمكن استخدام عبارة الاستيراد خارج الوحدة النمطية". يظهر هذا عادةً عند العمل مع وحدات ES الحديثة (ESM) أو التعامل مع الإعدادات التي تتضمن أدوات حزم مثل بيئات Webpack أو Babel أو Node.js. في هذه المدونة، سنستكشف أسباب هذا الخطأ وسبب حدوثه والحلول العملية لحله.

ماذا يعني هذا الخطأ؟

الخطأ " لا يمكن استخدام عبارة الاستيراد خارج الوحدة النمطية" لا يحتاج إلى شرح: يحدث عندما تواجه JavaScript عبارة استيراد خارج وحدة ES صالحة. في JavaScript، تحدد أنظمة الوحدة كيفية تقسيم التعليمات البرمجية في ملفات متعددة وكيفية تفاعلها مع بعضها البعض، وحدات ES (الاستيراد/التصدير) وCommonJS (require/module.exports) هما نظاما الوحدة الأساسيان.

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

ما الذي يسبب الخطأ "لا يمكن استخدام بيان الاستيراد خارج الوحدة النمطية"؟

يحدث هذا بشكل عام عندما يواجه JavaScript/TypeScript عبارة استيراد خارج سياق الوحدة النمطية. مما يعني أن الملف الذي تحاول الاستيراد منه لم يتم التعرف عليه كوحدة ES.

إليك بعض الأسباب الأكثر شيوعًا لحدوث هذا الخطأ:

• استخدام Node.js بشكل افتراضي : بشكل افتراضي، يستخدم Node.js وحدات CommonJS (CJS)، وليس وحدات ES. وهذا يعني أن صيغة الاستيراد/التصدير غير مدعومة أصلاً ما لم يتم تحديدها.

• تم تكوين Babel/Webpack بشكل خاطئ: عند تجميع التعليمات البرمجية الخاصة بك، قد لا يتم تكوين أدوات مثل Babel أو Webpack للتعامل مع وحدات ES بشكل صحيح، خاصة إذا كانت البيئة المستهدفة لا تدعمها أصلاً.

• "النوع" مفقود: "الوحدة النمطية" في package.json

  : إذا كنت تستخدم وحدات ES في مشروع Node.js، فستحتاج إلى تحديده بشكل صريح عن طريق إضافة "النوع" : "الوحدة النمطية" في package.json الخاص بك.

• عدم تطابق امتداد الملف

  : في بعض الأحيان، قد يؤدي استخدام .js بدلاً من .mjs لوحدات ES أو العكس إلى حدوث هذا الخطأ.

حلول خطوة بخطوة

إليك بعض الحلول لإصلاح الخطأ "لا يمكن استخدام عبارة الاستيراد خارج الوحدة النمطية":

تمكين وحدات ES في Node.js
• :
الحالة الأكثر شيوعًا هي عندما تعمل مع Node.js، والتي يتم تعيينها افتراضيًا على وحدات CommonJS. لتمكين وحدات ES، قم بما يلي:

الطريقة الأولى: تعديل package.json:

{ "النوع": "الوحدة النمطية" }

{
  "type": "module"
}

الطريقة الثانية: إعادة تسمية الملفات إلى .mjs:

إذا كنت لا ترغب في تعديل package.json الخاص بك، فيمكنك إعادة تسمية ملفاتك إلى .mjs (على سبيل المثال، Index.mjs) للإشارة بوضوح إلى أنها وحدات ES.

تحديث تكوين Babel/Webpack
• :
إذا كنت تستخدم Babel أو Webpack، فتأكد من تكوينهما للتعامل مع وحدات ES بشكل صحيح. بالنسبة لـ Babel، يمكنك استخدام المكون الإضافي @babel/preset-modules. بالنسبة لـ Webpack، قم بتعيين الوحدة النمطية على false في التكوين الخاص بك.

بالنسبة لـ Babel: قم بتحديث ملف .babelrc أو babel.config.json:

{ "الإعدادات المسبقة": ["@babel/وحدات الإعداد المسبق"] }

{
  "presets": ["@babel/preset-modules"]
}

module.exports = { الوحدة النمطية: { قواعد: [ { الاختبار: /\.js$/، استبعاد: /node_modules/، يستخدم: { محمل: 'محمل بابل'، خيارات: { الإعدادات المسبقة: ['@babel/preset-env'] } } } ] } };

module.exports = {
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules/,
        use: {
          loader: 'babel-loader',
          options: {
            presets: ['@babel/preset-env']
          }
        }
      }
    ]
  }
};

التحقق من مسار الاستيراد وبناء الجملة
• :
تأكد من صحة مسارات الاستيراد وأنك تستخدم بناء الجملة الصحيح. على سبيل المثال، يجب أن تبدأ المسارات النسبية بـ ./ أو ../.

إذا كنت تقوم باستيراد وحدة نمطية منNode_modules، فتأكد من أن الحزمة تدعم وحدات ES. إذا لم يكن الأمر كذلك، فقد تحتاج إلى استخدام أداة تجميع مثل Webpack للتعامل معها.

التحقق مرة أخرى من امتدادات الملفات
• :
إذا كنت تستخدم وحدات ES، فتأكد من تطابق امتدادات ملفاتك مع نوع الوحدة. استخدم .mjs لوحدات ES و .js لوحدات CommonJS.

.mjs: وحدات ES

• .cjs: وحدات CommonJS
ما هو الفرق بين وحدات ES ووحدات CommonJS؟

إذن الشيء الوحيد الذي يتبادر إلى الذهن هو ما هو الفرق بين وحدات ES ووحدات CommonJS؟ ولماذا يوجد نظامان مختلفان للوحدات النمطية في JavaScript؟

وحدات ES

وحدات ES هي نظام وحدة JavaScript الرسمي الذي تم تقديمه في ES6 (ES2015). يستخدمون الكلمات الأساسية للاستيراد والتصدير لتحديد التبعيات بين الوحدات. وحدات ES قابلة للتحليل بشكل ثابت، مما يعني أنه يتم حل التبعيات في وقت الترجمة، مما يسهل تحسين التعليمات البرمجية.

يتم تحميل وحدات ES بشكل غير متزامن، مما يسمح بأداء أفضل وتحميل متوازي للوحدات. كما أنها تدعم عمليات التصدير المسماة والصادرات الافتراضية والتبعيات الدورية. يتم دعم وحدات ES على نطاق واسع في المتصفحات الحديثة وNode.js (مع علامة "النوع": "الوحدة النمطية").

وحدات CommonJS

CommonJS هو نظام وحدة مستخدم في Node.js والبيئات الأخرى قبل تقديم وحدات ES. تستخدم وحدات CommonJS الوظيفة المطلوبة لاستيراد الوحدات النمطية وmodule.exports أو التصدير لتصدير القيم. يتم تحميل وحدات CommonJS بشكل متزامن، مما قد يؤدي إلى مشكلات في الأداء.

وحدات CommonJS غير مدعومة أصلاً في المتصفحات، ولكن يمكن نقلها إلى وحدات ES باستخدام أدوات مثل Babel أو Webpack. لا تزال وحدات CommonJS تُستخدم على نطاق واسع في مشاريع Node.js، لكن وحدات ES أصبحت أكثر شيوعًا نظرًا لأدائها الأفضل وقابليتها للتحليل الثابت.

يرجع سبب وجود هذين النظامين إلى تطور JavaScript والحاجة إلى نظام وحدات أكثر حداثة وموحدًا. وحدات ES هي مستقبل وحدات JavaScript، لكن وحدات CommonJS لا تزال تستخدم على نطاق واسع في المشاريع والبيئات الحالية.

نصائح التصحيح

إذا كنت قد جربت جميع الحلول المذكورة أعلاه ولا تزال تواجه الخطأ، فإليك بعض النصائح الإضافية لتصحيح الأخطاء:

• التحقق من إصدار Node.js

  : تأكد من أنك تقوم بتشغيل الإصدار 12.x من Node.js أو أعلى، حيث تم تقديم دعم وحدات ES محليًا في Node.js 12. إذا كنت في الإصدار الأقدم، لن تعمل وحدات ES. قم بتحديث الإصدار الخاص بك عن طريق زيارة موقع Node.js.

• التحقق من دعم المتصفح

  : إذا كنت تعمل في بيئة متصفح، فتأكد من أن متصفحك يدعم وحدات ES. معظم المتصفحات الحديثة تفعل ذلك، لكن الإصدارات الأقدم قد لا تفعل ذلك.

• التحقق من الأخطاء المطبعية

  : في بعض الأحيان، قد يؤدي خطأ مطبعي بسيط في التعليمات البرمجية الخاصة بك إلى حدوث هذا الخطأ. تحقق مرة أخرى من التعليمات البرمجية الخاصة بك بحثًا عن أي أخطاء إملائية أو بناء جملة غير صحيح.

• استخدم npx tsc لـ TypeScript

  : إذا كنت تستخدم TypeScript وواجهت هذا الخطأ، فقم بتشغيل npx tsc لتجميع تعليمات TypeScript البرمجية في JavaScript، مما قد يساعد في اكتشاف المشكلات.

خاتمة

يعد الخطأ "لا يمكن استخدام بيان الاستيراد خارج الوحدة النمطية" مشكلة شائعة يواجهها مطورو JavaScript/TypeScript عند العمل مع وحدات ES. من خلال فهم سبب حدوث هذا الخطأ واتباع الحلول خطوة بخطوة المتوفرة في هذه المدونة، يمكنك حل المشكلة بسرعة ومواصلة إنشاء تعليمات برمجية معيارية وقابلة للصيانة.