tsconfig.json خيارات المترجم وقالب الإعداد
آخر تحديث: 2026-10-22
tsconfig.json خيارات المترجم وقالب الإعداد
ملف tsconfig.json هو «مفتاح التحكم الكامل» لمشروع TypeScript: يوضع في جذر المشروع ويخبر المترجم (tsc) بالملفات التي تُترجم وكيف تُترجم. والخيار strict هو أهمها على الإطلاق — عَلَم واحد يفعّل عائلة الصرامة كاملة (strictNullChecks وnoImplicitAny وغيرهما) فيصطاد معظم مخاطر الفراغ والأنواع في وقت الترجمة.
| المجموعة | الإعداد والتطبيق |
|---|---|
| النوع | إعداد |
| الوضع الصارم | غير مطلوب |
ℹ️ معلومة يحوّل المحرر لغة TypeScript إلى JavaScript ثم يشغّلها (بدون فحص أنواع)؛ راجع ناتج كل مثال لنتيجة فحص الأنواع.
📝 الصيغة
// tsconfig.json (أصغر إعداد strict)
{
"compilerOptions": {
"target": "ES2020", // إصدار لغة JS للمخرجات
"module": "commonjs", // صيغة الوحدات (commonjs لـ Node، وESNext للحزّامات)
"outDir": "./dist", // دليل المخرجات
"rootDir": "./src", // جذر المصادر
"paths": { "@utils/*": ["./src/utils/*"] }, // أسماء بديلة لمسارات الوحدات
"strict": true // يفعّل عائلة فحوصات strict دفعة واحدة
},
"include": ["src"] // يترجم ملفات src فقط
}⚙️ المعاملات
| strict | المفتاح الكلي للفحص الصارم: يفعّل معًا strictNullChecks وnoImplicitAny وstrictFunctionTypes وغيرها؛ وينصح بتفعيله في المشاريع الجديدة دون تفكير |
|---|---|
| target / module | يحدد target إصدار لغة JS للناتج (وتتبع الأنواع المدمجة المتاحة إياه)؛ ويحدد module صيغة الوحدات في الناتج |
| outDir / rootDir / paths | مجلد الناتج / جذر الشيفرة المصدرية / أسماء المسارات المستعارة. والـ paths مجرد مطابقة أسماء في وقت الترجمة — فحل الأسماء في التشغيل ما يزال يحتاج تعاون المُجمِّع أو إعداد مسارات Node الفرعية |
القيمة المُعادة：لا قيمة معادة — tsconfig.json ملف إعدادات يعمل في وقت الترجمة فقط ولا يشارك في التشغيل إطلاقًا.
▶ مثال
عدّل الكود أدناه واضغط «جرّب» لرؤية نتيجة التحويل:
الناتج：
length = 5
sum = 5
(مخرجات التشغيل بعد الترجمة؛ الفحص النوعي يتولاه tsc — إزالة الاحتياط ?? تعطي error TS18047، وإزالة تعليقات أنواع معاملات sum تعطي error TS7006)💡 نقاط مهمة
ℹ️ معلومة الـ strict ليس فحصًا واحدًا بل مفتاح مجموعة فحوص: strictNullChecks وnoImplicitAny وstrictFunctionTypes وstrictBindCallApply وstrictPropertyInitialization وuseUnknownInCatchVariables وغيرها.
💡 تلميح يمكن توليد قالب في المشاريع الجديدة بأمر tsc --init ثم تقليصه؛ وينبغي مزامنة أسماء paths المستعارة مع أسماء المُجمِّع (alias في Vite/webpack) وإلا نجحت الترجمة وفشل إيجاد الوحدات في التشغيل.
⚠️ تنبيه لا داعي في المشاريع القائمة إلى فرض strict دفعة واحدة: فعّل strictNullChecks وحده أولًا وأصلح تدريجيًا، ثم افتح الصرامة كاملة بعد أن تصبح الشيفرة كلها نظيفة، تفاديًا لظهور مئات الأخطاء دفعة واحدة.
🏷️ الإعداد والتطبيق ذو صلة
💡 حالات ذات صلة
المزيد من الحالات قادم قريبًا.
📚 دروس ذات صلة
❓ أسئلة شائعة
س ما الفحوص التي يفتحها strict: true تحديدًا؟
ج إنه مفتاح مجموعة فحوص: strictNullChecks (وجوب معالجة null/undefined صراحة) وnoImplicitAny (منع any الضمني) وstrictFunctionTypes (فحص تباين معاملات الدوال) وstrictPropertyInitialization (وجوب تهيئة خصائص الأصناف) وuseUnknownInCatchVariables (متغيرات catch من نوع unknown) وغيرها. ويمكن إيقاف أي منها منفردًا للترحيل التدريجي.
س ما الفرق بين target و module؟
ج يحدد target إلى أي إصدار JS تُخفَّض الصياغات الجديدة (فـ ES2020 يدعم السلسلة الاختيارية مثلًا)؛ ويحدد module نظام الوحدات للناتج (commonjs / ESNext / node16). الأول يدير ميزات اللغة والثاني يدير الشكل الذي تُترجم إليه import/export.
س أعددت أسماء paths المستعارة لكن التشغيل لا يجد الوحدات — لماذا؟
ج الـ paths مجرد مطابقة أسماء يراها المترجم، وتبقى الأسماء المستعارة في ناتج الترجمة كما هي. فيجب أن يتعرّف عليها التشغيل أيضًا: اضبط resolve.alias في Vite/webpack لمشاريع المُجمِّع، أو استخدم حقل imports في package.json (أو رقعة تشغيل مثل tsconfig-paths) في Node المجرد.
