اگر هنگام اجرای دستور npm install با خطاهایی مثل ECONNRESET، ETIMEDOUT یا 403 Forbidden روبه‌رو می‌شوید، لزوماً مشکل از کد پروژه شما نیست. در بسیاری از مواقع، ریشه مشکل به اینترنت، تنظیمات NPM یا دسترسی به Registry برمی‌گردد.

در ایران این خطاها بیشتر دیده می‌شوند؛ زیرا کیفیت اتصال، DNS، Proxy یا حتی مسیر ارتباطی با سرورهای خارجی همیشه پایدار نیست. به همین دلیل، توسعه‌دهندگان گاهی هنگام نصب پکیج‌ها با کندی شدید یا خطاهای متوالی مواجه می‌شوند.

در این مقاله، مرحله‌به‌مرحله روش‌های رفع مشکل npm install در ایران را بررسی می‌کنیم. علاوه بر این، راه‌حل خطاهای رایج NPM را هم توضیح می‌دهیم تا بتوانید سریع‌تر علت اصلی مشکل را پیدا کنید.

چرا npm install در ایران با مشکل مواجه می‌شود؟

وقتی دستور زیر را اجرا می‌کنید، NPM باید برای دریافت اطلاعات و دانلود پکیج‌ها به Registry متصل شود:

npm install

به‌صورت پیش‌فرض، Registry رسمی NPM این آدرس است:

https://registry.npmjs.org/

اگر ارتباط سیستم شما با این سرویس پایدار نباشد، احتمال بروز خطا زیاد می‌شود. برای مثال، ممکن است یکی از خطاهای زیر را ببینید:

npm ERR! code ECONNRESET
npm ERR! code ETIMEDOUT
npm ERR! 403 Forbidden

از طرف دیگر، گاهی هم npm install بدون خطای واضح متوقف می‌شود یا زمان زیادی روی دانلود یک پکیج می‌ماند. در نتیجه، تشخیص درست علت مشکل اهمیت زیادی دارد.

رایج‌ترین دلایل این اختلال‌ها عبارت‌اند از:

  • اختلال در اتصال اینترنت
  • مشکل DNS
  • تنظیم اشتباه Registry
  • وجود Proxy نامعتبر
  • Cache خراب NPM
  • اختلال در فایل .npmrc
  • ناسازگاری نسخه Node.js یا npm
  • مشکل در Dependencyهای پروژه

1. بررسی Registry فعلی NPM

اولین قدم این است که Registry فعلی NPM را بررسی کنید. زیرا اگر آدرس Registry قبلاً تغییر کرده باشد، نصب پکیج‌ها ممکن است با خطا روبه‌رو شود.

npm config get registry

در حالت عادی، باید این مقدار نمایش داده شود:

https://registry.npmjs.org/

با این حال، اگر خروجی چیز دیگری بود، Registry را به حالت پیش‌فرض برگردانید:

npm config set registry https://registry.npmjs.org/

سپس دوباره این دستور را اجرا کنید:

npm config get registry

در نهایت، دوباره تلاش کنید:

npm install

2. تست اتصال به NPM Registry

پیش از هر تغییر مهم، بهتر است اتصال خود به Registry را تست کنید. این کار کمک می‌کند بفهمید مشکل از دسترسی شبکه است یا از خود پروژه.

npm ping

اگر پاسخ موفقیت‌آمیز دریافت کردید، یعنی ارتباط اولیه برقرار است. همچنین در Linux و macOS یا سیستم‌هایی که curl دارند، می‌توانید این دستور را هم اجرا کنید:

curl https://registry.npmjs.org/

اگر پاسخ بسیار کند بود یا Timeout دریافت کردید، احتمالاً اختلال از اینترنت، DNS یا مسیر ارتباطی شماست. بنابراین قبل از دستکاری پروژه، وضعیت شبکه را بررسی کنید.

3. اجرای npm install در حالت Verbose

یکی از بهترین روش‌ها برای پیدا کردن علت خطا، اجرای NPM در حالت Verbose است. در این حالت، جزئیات بیشتری از فرایند نصب نمایش داده می‌شود.

npm install --verbose

به کمک این خروجی، راحت‌تر متوجه می‌شوید که:

  • کدام پکیج باعث خطا شده است
  • درخواست به کدام URL ارسال شده است
  • خطا دقیقاً در چه مرحله‌ای رخ داده است
  • مشکل از Network است یا از Dependencyها

در نتیجه، به‌جای حدس زدن، می‌توانید بر اساس داده واقعی تصمیم بگیرید.

4. رفع خطای ECONNRESET در npm

خطای زیر یکی از رایج‌ترین خطاهای NPM است:

npm ERR! code ECONNRESET

این خطا معمولاً زمانی رخ می‌دهد که اتصال شبکه در میانه دانلود یا دریافت اطلاعات قطع شود. برای همین، علت آن اغلب به خود اینترنت یا تنظیمات ارتباطی برمی‌گردد.

دلایل رایج ECONNRESET

  • اینترنت ناپایدار
  • مشکل DNS
  • قطع شدن VPN
  • Proxy اشتباه
  • محدودیت شبکه یا Firewall
  • اختلال در NPM Registry

ابتدا Registry را بررسی کنید:

npm config get registry

سپس اتصال را تست کنید:

npm ping

بعد از آن، خروجی دقیق نصب را ببینید:

npm install --verbose

اگر خطا همچنان تکرار شد، بهتر است DNS یا وضعیت Proxy و VPN را هم بررسی کنید.

5. رفع خطای ETIMEDOUT در npm

خطای زیر معمولاً به این معناست که NPM در زمان مشخص نتوانسته از سرور پاسخ بگیرد:

npm ERR! code ETIMEDOUT

این خطا بیشتر زمانی رخ می‌دهد که ارتباط شبکه کند یا ناپایدار باشد. با این حال، تنظیمات اشتباه Registry هم می‌تواند همین مشکل را ایجاد کند.

برای شروع، این دستورات را اجرا کنید:

npm ping
npm config get registry
npm install --verbose

اگر در خروجی مشخص شد یک URL خاص Timeout می‌شود، احتمالاً مشکل به همان مسیر ارتباطی مربوط است. بنابراین بررسی DNS یا استفاده از مسیر جایگزین می‌تواند مفید باشد.

6. رفع خطای 403 Forbidden در NPM

گاهی هم NPM با خطای زیر متوقف می‌شود:

npm ERR! 403 Forbidden

این خطا یعنی سرور درخواست شما را دریافت کرده اما اجازه دسترسی نداده است. برای مثال، ممکن است Registry اشتباه باشد یا یک پکیج خصوصی نیاز به احراز هویت داشته باشد.

رایج‌ترین دلایل خطای 403 شامل این موارد است:

  • Registry اشتباه
  • Private Registry
  • Token منقضی‌شده
  • تنظیمات اشتباه فایل .npmrc
  • عدم دسترسی به پکیج خصوصی

ابتدا این دستورات را اجرا کنید:

npm config get registry
npm config list

علاوه بر این، اگر پروژه فایل .npmrc دارد، محتوای آن را هم بررسی کنید.

7. پاک کردن Cache در NPM

گاهی مشکل از Cache خراب NPM است. البته این راه‌حل همیشه ضروری نیست؛ اما در بعضی شرایط می‌تواند مفید باشد.

در قدم اول، وضعیت Cache را بررسی کنید:

npm cache verify

اگر همچنان مشکل ادامه داشت، Cache را پاک کنید:

npm cache clean --force

سپس دوباره نصب را امتحان کنید:

npm install

با این حال، اگر مشکل از Network باشد، پاک کردن Cache به‌تنهایی کافی نخواهد بود.

8. حذف node_modules و نصب مجدد پکیج‌ها

اگر این خطا فقط در یک پروژه خاص رخ می‌دهد، احتمال دارد برخی Dependencyها ناقص نصب شده باشند. در چنین شرایطی، حذف node_modules می‌تواند کمک‌کننده باشد.

در Linux و macOS:

rm -rf node_modules
npm install

در Windows هم می‌توانید پوشه node_modules را حذف کنید و بعد دوباره دستور نصب را اجرا کنید.

آیا package-lock.json را هم حذف کنیم؟

معمولاً نه. بهتر است ابتدا فقط node_modules را حذف کنید. زیرا فایل package-lock.json نسخه دقیق Dependencyها را نگه می‌دارد و حذف آن همیشه تصمیم درستی نیست.

9. استفاده از npm ci به جای npm install

اگر پروژه شما فایل معتبر package-lock.json دارد، در بعضی مواقع استفاده از npm ci انتخاب بهتری است.

npm ci

این دستور برای نصب تمیز و قابل تکرار Dependencyها استفاده می‌شود. به همین دلیل، در محیط‌های CI/CD هم بسیار رایج است.

تفاوت npm install و npm ci چیست؟

npm install می‌تواند بسته به وضعیت پروژه Dependencyها را تغییر دهد. در مقابل، npm ci دقیقاً بر اساس Lock File عمل می‌کند. بنابراین، اگر دنبال نصب پایدارتر هستید، npm ci گزینه خوبی است.

10. بررسی نسخه Node.js و npm

همه خطاهای نصب به اینترنت ربط ندارند. گاهی نسخه Node.js یا npm با پروژه شما سازگار نیست. به همین دلیل، بهتر است نسخه‌ها را هم بررسی کنید.

node -v
npm -v

سپس فایل package.json را ببینید. برای مثال، بعضی پروژه‌ها در بخش engines نسخه موردنیاز را مشخص می‌کنند:

{
  "engines": {
    "node": ">=20"
  }
}

اگر از نسخه قدیمی Node استفاده کنید، احتمال بروز خطا بالا می‌رود.

11. بررسی Proxy در تنظیمات NPM

گاهی دلیل اصلی مشکل، Proxy قدیمی یا اشتباه است. در نتیجه، بهتر است این تنظیمات را هم بررسی کنید.

npm config get proxy
npm config get https-proxy

اگر Proxy اشتباه تنظیم شده بود، آن را حذف کنید:

npm config delete proxy
npm config delete https-proxy

بعد از آن، دوباره تست بگیرید:

npm ping
npm install

12. بررسی فایل .npmrc

فایل .npmrc می‌تواند تنظیمات مهمی مثل Registry، Proxy یا Authentication را ذخیره کند. بنابراین، اگر مشکل غیرعادی بود، حتماً این فایل را بررسی کنید.

برای دیدن تنظیمات فعال، این دستور مفید است:

npm config list

نکته امنیتی: اگر داخل .npmrc توکن یا اطلاعات احراز هویت وجود دارد، آن را در سایت یا GitHub منتشر نکنید.

13. استفاده از NPM Mirror برای حل مشکلات اتصال

اگر اتصال شما به Registry رسمی NPM ضعیف یا ناپایدار است، استفاده از NPM Mirror می‌تواند راه‌حل مناسبی باشد. این روش در بعضی شرایط باعث دسترسی بهتر به پکیج‌ها می‌شود.

npm config set registry MIRROR_URL

بعد از تغییر Registry، حتماً بررسی کنید:

npm config get registry

برای توضیحات کامل‌تر، می‌توانید به مقاله مربوط به راهنمای استفاده از NPM Mirror لینک بدهید.

14. چگونه NPM را به Registry اصلی برگردانیم؟

اگر قبلاً از Mirror یا Registry دیگری استفاده کرده‌اید، هر زمان خواستید می‌توانید تنظیمات را به حالت پیش‌فرض برگردانید:

npm config set registry https://registry.npmjs.org/

سپس این دستورات را اجرا کنید:

npm config get registry
npm ping

15. اگر مشکل فقط در یک پروژه وجود دارد

اگر NPM در پروژه‌های دیگر درست کار می‌کند اما فقط در یک پروژه خطا می‌دهد، احتمالاً مشکل از خود پروژه است. در این شرایط، بهتر است این موارد را بررسی کنید:

  • package.json
  • package-lock.json
  • نسخه Node.js
  • نسخه npm
  • Peer Dependencies
  • Private Packages
  • فایل .npmrc

همچنین، اجرای دستور زیر اطلاعات مفیدی می‌دهد:

npm install --verbose

16. مشکل npm install در React، Next.js و Vue

این مشکل فقط به پروژه‌های بک‌اند محدود نیست. برای مثال، هنگام راه‌اندازی پروژه‌های React، Next.js، Vue، Angular یا Vite هم ممکن است دقیقاً همین خطاها را ببینید.

بنابراین، اگر در پروژه فرانت‌اند هم با ECONNRESET یا ETIMEDOUT روبه‌رو شدید، ابتدا Network و Registry را بررسی کنید و فوراً سراغ تغییر کد نروید.

ترتیب پیشنهادی برای رفع مشکل npm install

اگر نمی‌دانید از کجا شروع کنید، این ترتیب معمولاً بهترین نتیجه را می‌دهد:

مرحله 1: بررسی نسخه‌ها

node -v
npm -v

مرحله 2: بررسی Registry

npm config get registry

مرحله 3: تست اتصال

npm ping

مرحله 4: اجرای Verbose

npm install --verbose

مرحله 5: بررسی Proxy

npm config get proxy
npm config get https-proxy

مرحله 6: بررسی Cache

npm cache verify

در نهایت، اگر مشکل فقط در یک پروژه خاص بود، فایل‌های پروژه و Dependencyها را بررسی کنید.

سوالات متداول درباره مشکلات npm

چرا npm install اجرا نمی‌شود؟

این مشکل می‌تواند به اینترنت، DNS، Registry، Proxy، Cache خراب، نسخه نامناسب Node.js یا Dependencyهای پروژه مربوط باشد. بنابراین بهترین کار، بررسی مرحله‌به‌مرحله است.

چرا npm install در ایران کند است؟

معمولاً کیفیت اتصال، DNS و مسیر ارتباط با Registry روی سرعت npm اثر می‌گذارند. به همین دلیل، ابتدا با npm ping وضعیت اتصال را بسنجید.

خطای ECONNRESET در npm چیست؟

این خطا نشان می‌دهد اتصال شبکه هنگام دریافت یا ارسال اطلاعات قطع شده است. در نتیجه، باید اینترنت، DNS، VPN و Proxy را بررسی کنید.

خطای ETIMEDOUT در npm چیست؟

این خطا زمانی رخ می‌دهد که NPM در زمان مشخص از سرور پاسخ نگیرد. برای همین، اختلال در اینترنت یا دسترسی ضعیف به Registry از دلایل رایج آن است.

چگونه Registry فعلی npm را بررسی کنیم؟

npm config get registry

چگونه npm را به Registry اصلی برگردانیم؟

npm config set registry https://registry.npmjs.org/

آیا پاک کردن npm cache مشکل را حل می‌کند؟

گاهی بله؛ اما همیشه نه. ابتدا بهتر است Cache را بررسی کنید و فقط در صورت نیاز آن را پاک کنید.

npm cache verify

npm install بهتر است یا npm ci؟

برای کار روزمره معمولاً npm install استفاده می‌شود. با این حال، اگر پروژه Lock File معتبر دارد و نصب قابل تکرار می‌خواهید، npm ci انتخاب بهتری است.

جمع‌بندی

برای رفع مشکل npm install در ایران بهتر است به‌جای آزمون‌وخطای تصادفی، اول علت اصلی را پیدا کنید. در واقع، سه دستور زیر بهترین نقطه شروع هستند:

npm config get registry
npm ping
npm install --verbose

اگر مشکل به اتصال مربوط باشد، باید Network، DNS، Proxy یا Registry را بررسی کنید. از سوی دیگر، اگر خطا فقط در یک پروژه دیده می‌شود، بهتر است فایل‌های پروژه و Dependencyها را بررسی کنید.

در نهایت، اگر ارتباط با Registry رسمی ناپایدار بود، استفاده از NPM Mirror هم می‌تواند گزینه مناسبی باشد.