ملف TypeScript .ts لا يعمل؟ حل خطأ "Unknown file extension"

مقدمة: "ملف .ts الخاص بك لا يفتح؟ لست وحدك"

تخيل: أنت تكتب كودًا رائعًا بلغة TypeScript، وتحفظ الملف بالامتداد .ts، وتشغل الأمر node myfile.ts... وتحصل على رد مثل: "Unknown file extension ".ts". هل هذا مألوف؟ إذا كنت قد ألقيت نظرة على Stack Overflow، فأنت تعلم أن هذا السؤال جمع آلاف المشاهدات ومئات التعليقات. المشكلة قديمة، لكنها لا تزال قائمة.

في هذه المقالة، لن نقوم فقط بنسخ إجابة من المنتدى. سنقوم بتحليل لماذا يحدث هذا، كيف يمكن إصلاحه، وماذا تفعل لتجنب مواجهة هذا الخطأ مرة أخرى. ستتعلم كيفية إعداد مشروع TypeScript بشكل صحيح، واستخدام ts-node وإعدادات tsconfig.json. هيا بنا!

لماذا يظهر خطأ "Unknown file extension ".ts"؟

دعنا نصل إلى الجوهر مباشرة. Node.js بشكل افتراضي لا يفهم ملفات .ts. إنه يعرف فقط .js و .json و .mjs و .cjs. عندما تكتب node myfile.ts، يحاول Node.js بصدق تنفيذ كود TypeScript كـ JavaScript عادي، لكنه يصطدم بتركيب نحوي غير مألوف له (مثل الأنواع، والواجهات، والأجناس).

النتيجة هي خطأ. ولكن هناك حالة أخرى: أنت تستخدم ts-node أو tsx، ولكنك لا تزال ترى نفس الرسالة. لماذا؟ لأنه في الإصدارات الحديثة من Node.js (بدءًا من الإصدار 16)، تمت إضافة فحص صارم للامتدادات في package.json، خاصةً عندما يكون "type": "module" موجودًا.

الأسباب الرئيسية:

\n
• التشغيل المباشر node file.ts — Node.js لا يستطيع ترجمة TypeScript بشكل فوري.
\n
• عدم وجود ts-node أو tsx — لا توجد أداة للترجمة.
\n
• إعدادات tsconfig.json غير صحيحة — على سبيل المثال، لم يتم تحديد module أو target.
\n
• مشاكل في package.json — إذا كان "type": "module" موجودًا، فقد يتطلب ts-node تحديد الامتداد بشكل صريح.
\n

الحل 1: استخدام ts-node (الطريقة التقليدية)

أسهل طريقة لتشغيل TypeScript بدون ترجمة مسبقة هي استخدام ts-node. هذه حزمة تقوم بترجمة ملفات .ts في الذاكرة وتمرير النتيجة إلى Node.js.

التثبيت والتشغيل

npm install -g ts-node\nts-node myfile.ts

إذا كنت تستخدم مشروعًا محليًا، فمن الأفضل تثبيته كتبعية تطوير:

npm install --save-dev ts-node\nnpx ts-node myfile.ts

مثال لملف بسيط hello.ts:

const greet = (name: string): string => {\n    return `مرحبًا، ${name}!`;\n};\n\nconsole.log(greet("العالم"));

نقوم بتشغيله: npx ts-node hello.ts — ونرى في وحدة التحكم "مرحبًا، العالم!". يعمل!

لكن هناك تفصيل: "type": "module"

إذا كان في package.json الخاص بك "type": "module"، فقد يرفض ts-node العمل. في هذه الحالة، إما أن تزيل هذا السطر مؤقتًا، أو تستخدم العلم --esm:

npx ts-node --esm myfile.ts

الحل 2: استخدام tsx (أداة حديثة)

tsx هو بديل أسرع لـ ts-node، مبني على esbuild. يعمل مع ESM بشكل افتراضي ولا يتطلب أعلامًا إضافية.

التثبيت:

npm install --save-dev tsx

التشغيل:

npx tsx myfile.ts

مثال باستخدام إمكانيات TypeScript الحديثة:

// types.ts\nexport interface User {\n    id: number;\n    name: string;\n    email: string;\n}\n\nconst user