كيفية إصلاح خطأ تعذر العثور على الوحدة النمطية في Node.js وTypeScript

الخطأخطأ: لا يمكن العثور على الوحدة النمطية ‘x’ (أولا يمكن العثور على الوحدة النمطية ‘x’ أو إعلانات النوع المقابلة لهافي TypeScript) أمر شائع للغاية. وله عدة أسباب مميزة — وإليك كيفية تشخيص كل منها وإصلاحه.

السبب الأول: الحزمة غير مثبتة

# The most common cause — you forgot to install it
npm install express

# Reinstall everything if node_modules is corrupted
rm -rf node_modules package-lock.json
npm install

# Verify it's actually in package.json
npm list express

السبب 2: مسار استيراد خاطئ (الواردات النسبية)

// 🐛 Wrong path
import { helper } from './utils/helper';  // but file is at ./lib/helper

// ✅ Fix: correct the relative path
import { helper } from './lib/helper';

// Common mistakes:
// - Missing ./ for local files: import x from 'utils' looks in node_modules
// - Wrong case: ./Helper vs ./helper (case-sensitive on Linux!)
// - Missing file extension in ESM (see Cause 5)

السبب 3: تعريفات النوع المفقودة (TypeScript)

# Error: Cannot find module 'lodash' or its corresponding type declarations

# The package works but has no bundled types. Install @types:
npm install --save-dev @types/lodash

# For packages that will never have types, declare them:
# create src/types/untyped-module.d.ts
declare module 'some-untyped-package';

السبب 4: لم يتم تكوين الأسماء المستعارة لمسار tsconfig

// You use import { x } from '@/utils' but it's not configured

// tsconfig.json — add path mapping
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

// For runtime (Node), you also need tsconfig-paths or a bundler:
// npm install -D tsconfig-paths
// node -r tsconfig-paths/register dist/index.js
// Or use tsx which handles this automatically

السبب 5: مشكلات ملحق ESM مقابل CommonJS

// In ESM ("type": "module" in package.json), you MUST include .js extension
// even when importing .ts files:

// 🐛 Fails in ESM
import { helper } from './utils/helper';

// ✅ Correct in ESM
import { helper } from './utils/helper.js';  // yes, .js even for .ts source

// package.json
{
  "type": "module"
}

// tsconfig.json
{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "bundler"  // or "nodenext"
  }
}

السبب 6: الوحدة النمطية مثبتة ولكن غير مبنية (Monorepo/مساحة العمل)

# In a monorepo, the dependency package hasn't been built yet
# Cannot find module '@myorg/shared'

# Build the dependency first
npm run build --workspace=@myorg/shared

# Or build all packages (Turborepo/Nx)
turbo build
npx nx run-many --target=build

قائمة التشخيص

1. هل تم تثبيته؟ تشغيلnpm list <module>
2. هل المسار صحيح؟ التحقق من حساسية الحالة والمسار النسبي
3. هل تحتاج إلى @types؟ حاولnpm i -D @types/<module>
4. قضية الإدارة السليمة بيئيا؟ أضف.js ملحقات إذا"type": "module"
5. الاسم المستعار للمسار؟ تحقق من tsconfigpaths ومحلل وقت التشغيل
6. أعد تشغيل خادم TS في المحرر الخاص بك (رمز VS: Cmd+Shift+P، ثم “إعادة تشغيل خادم TS”)

دقة وحدة العقدة — كيف تعمل

// import 'foo' (no ./) → Node looks in:
//   1. Core modules (fs, path, http)
//   2. node_modules in current dir
//   3. node_modules in parent dirs, up to root

// import './foo' (with ./) → resolves relative to current file
//   Looks for: ./foo.js, ./foo.json, ./foo/index.js, etc.

// Understanding this explains most "cannot find module" errors:
// - No ./ means Node searches node_modules (fails if it's a local file)
// - ./ means relative path (fails if the path is wrong)

الأسئلة المتداولة

س: لماذا يعمل محليًا ولكنه يفشل على الخادم/CI؟
ج: عادةً ما تكون حساسية حالة الأحرف – نظامي التشغيل macOS/Windows غير حساسين لحالة الأحرف، أما نظام التشغيل Linux فهو ليس كذلك. ./Helper يعمل محليًا ولكنه يفشل على Linux إذا كان الملف./helper. تطابق دائما الحالة الدقيقة.

س: لقد قمت بتثبيت الحزمة ولكنني مازلت أتلقى الخطأ. لماذا؟
ج: أعد تشغيل خادم TypeScript الخاص بالمحرر، أو خادم التطوير. تحقق أيضًا من وجود الحزمةdependencies، ولم يتم تثبيته محليًا فقط دون حفظه. احذف Node_modules وأعد تثبيته إذا لم تكن متأكدًا.

س: ما الفرق بين خطأ الوحدة النمطية وخطأ تعريف النوع؟
ج: “لا يمكن العثور على الوحدة النمطية” وحدها = لم يتم العثور على وحدة JS. “… أو إعلانات النوع المقابلة لها” = الوحدة موجودة ولكن لا يمكن لـ TypeScript العثور على الأنواع. الثاني يحتاج@types/x أو.d.ts تصريح.

س: كيف يمكنني إصلاح ذلك في بناء Docker؟
ج: تأكدnpm install يعمل داخل الحاوية (لا تنسخ عقدة المضيف). انسخ package.json أولاً، ثم قم بتثبيته، ثم انسخ المصدر – وهذا أيضًا يعمل على تحسين التخزين المؤقت لطبقة Docker.

س: هل يجب أن أستخدم “moduleResolution”: “node” أو “bundler”؟
ج: في عام 2026، استخدم"bundler" للمشاريع التي تم إنشاؤها باستخدام Vite/esbuild/webpack (لا حاجة إلى ملحق)، أو"nodenext" للعقدة ESM النقية (الملحقات مطلوبة). تجنب الإرث"node" للمشاريع الجديدة.

الخلاصة

غالبًا ما يرجع السبب “لا يمكن العثور على الوحدة النمطية” إلى أحد الأسباب التالية: لم يتم تثبيت الحزمة، مسار الاستيراد خاطئ (تحقق من حالة الأحرف!)، مفقود@typesأو متطلبات ملحق ESM أو الأسماء المستعارة للمسارات غير المكونة. اعمل من خلال قائمة التحقق التشخيصية من الأعلى إلى الأسفل —npm list، تحقق من المسار، تحقق من@types، وأعد تشغيل خادم TS الخاص بك. يتم حل تسعين بالمائة من الحالات في الخطوات الثلاث الأولى.