خطای Cannot find module در Node.js همیشه به معنی نیاز به نصب پکیج نیست. ممکن است فایل شروع اشتباه باشد، مسیر نسبی درست نوشته نشده باشد یا وابستگی واقعاً در محل اجرای برنامه موجود نباشد. ابتدا نامِ مورد جست‌وجو و مسیرِ فایل فراخوان را از پیام خطا جدا کنید؛ نصب کورکورانه می‌تواند مسئله را پنهان کند.
۱. سه حالت با مسیر تشخیص متفاوت
| مورد پیدا نشده | احتمال اول | بررسی |
|---|---|---|
| فایل شروع برنامه | startup path یا محل اجرا اشتباه |
مسیر تنظیم‌شده و وجود همان فایل |
مسیر نسبی مثل ./lib/tool.cjs |
فایل یا نام آن متفاوت است | فراخوان، حروف و ساختار پوشه |
نام بسته مثل some-package |
وابستگی/ورودی بسته پیدا نمی‌شود |
manifest و محل نصب همان پروژه |
در CommonJS، require با مسیر ./ نسبت به فایل فراخوان حل می‌شود؛ با process.cwd یکی فرض نکنید. فایل شروع از فرمان شِل به محل اجرای فرمان وابسته است و در پنل هم باید نسبت به قرارداد همان پنل درست باشد.
۲. یک خطای قابل‌بازتولید و کم‌خطر
در پوشهٔ آزمایش خالی، فایل missing.cjs فقط این خط را دارد؛ فایل not-present.cjs عمداً وجود ندارد:
require('./not-present.cjs');
با اجرای node missing.cjs، نمونهٔ واقعی پیام شامل این بخش‌ها بود:
Error: Cannot find module './not-present.cjs'
code: 'MODULE_NOT_FOUND'
Require stack نشان می‌دهد کدام فایل زنجیرهٔ فراخوان را شروع کرده است. مسیرهای کامل ممکن است نام حساب و ساختار خصوصی داشته باشند؛ پیش از ارسال لاگ، آن‌ها را پاک‌سازی کنید ولی نام نسبیِ لازم برای فهم مسئله را نگه دارید.
۳. اول خود فایل را بررسی کنید
- نام داخل خطا را دقیق بخوانید؛ entry file و فایل داخلی را قاطی نکنید.
- وجود همان فایل و بزرگی/کوچکی حروف را کنترل کنید.
- فایل فراخوان را پیدا کنید و مسیر ./ یا ../ را نسبت به آن بسنجید.
- اگر خطا مربوط به بسته است، بررسی کنید نام درست و dependency متعلق به همین پروژه باشد.
روی بعضی فایل‌سیستم‌های ویندوز، اختلاف حروف ممکن است دیده نشود و روی لینوکس خطا بدهد. موفقیت محلی دلیل کافی برای وجود فایل با همان نام روی هاست نیست. از طرف دیگر، تغییر همهٔ نام‌ها بدون دیدن importها می‌تواند خطای تازه بسازد.
۴. حل مسیر بدون اجرای ماژول هدف
node -p "require.resolve('./hello.cjs')"
این نمونه وقتی فایل hello.cjs در پوشهٔ آزمایش موجود بود، مسیر آن را پیدا کرد. require.resolve در این کاربرد مسیر قابل‌حل را برمی‌گرداند، نه اینکه تابع‌های ماژول هدف را اجرا کند. اگر در کد پروژه استفاده شود، مبدأ حل مسیر همان بافت فراخوان است.
برای بستهٔ واقعی، نام معتبر را جایگزین کنید. فایل package.json، بخش dependencies در برابر devDependencies، نسخهٔ Node و تنظیم exports بسته نیز می‌توانند مهم باشند. npm install از روی هر رشتهٔ داخل خطا یا با گزینهٔ force، قدم تشخیصی مطمئن نیست؛ ابتدا نام و منبع بسته تأیید شود.
۵. خطاهای شبیه هم را یکی نکنید
- ERR_MODULE_NOT_FOUND در مسیر ESM می‌تواند جزئیات و قواعد متفاوتی داشته باشد.
- ERR_PACKAGE_PATH_NOT_EXPORTED یعنی زیرمسیر با قرارداد exports مجاز نیست؛ صرف نصب دوباره الزاماً آن را حل نمی‌کند.
- require is not defined بیشتر به بافت ESM مربوط است، نه نبودن پکیج.
- خطای داخل ماژولِ بارگذاری‌شده را با پیدا نشدن خود ماژول اشتباه نگیرید.
نکته: برای پوشاندن اختلاف نسخه، کل node_modules یا فایل lock را از پروژهٔ دیگر کپی نکنید. پیش از هر تغییر نصب، نسخهٔ پروژه و مسیر برگشت باید مشخص باشد؛ این آموزش بسته‌ای نصب نمی‌کند.
۶. چه چیزی برای پشتیبانی بفرستیم؟
نسخهٔ Node، نام عمومی پروژه، startup file، نام ماژولِ خطادار، require stack پاک‌سازی‌شده و توضیح زمان شروع مشکل مفیدند. رمز، کل فایل env و بستهٔ کامل کد خصوصی لازم نیست. نتیجهٔ خوب تشخیص می‌دهد مشکل در کدام لایه است؛ بعد می‌توان اصلاح محدود همان لایه را برنامه‌ریزی کرد.
اگر خطا با require یا import ارتباط دارد، قبل از نصب مجدد بسته‌ها، تفاوت ESM و CommonJS و نقش فایل‌های mjs و cjs را بررسی کنید.
۷. مسیر مطالعهٔ مرتبط
- راه‌اندازی اپلیکیشن Node.js و پایتون روی هاست
- استقرار پروژه‌ی Next.js ساخته‌شده با دستیار کدنویسی روی هاست Node.js
۸. منابع و روش بررسی
منابع رسمی در ۲۴ اکتبر ۲۰۲۶ بررسی شدند. مثال‌های کدِ این متن در Node.js نسخهٔ ۲۴.۱۹.۰ روی محیط محلی ایزوله بررسی شده‌اند؛ نصب روی هاست، اتصال دیتابیس یا کارایی تولید با این آزمایش اثبات نشده است.
