NPM Mirror چیست؟ آموزش تنظیم NPM Registry برای ایران

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

در این آموزش بررسی می‌کنیم NPM Mirror چیست، چه تفاوتی با NPM Registry دارد، چگونه Registry فعلی npm را مشاهده و تغییر دهیم و چطور از یک Mirror در پروژه‌های Node.js، Docker و محیط‌های CI/CD استفاده کنیم.

NPM Mirror چیست؟

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

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

NPM Registry چیست؟

NPM Registry سرویسی است که npm برای پیدا کردن اطلاعات پکیج‌ها و دریافت آن‌ها از آن استفاده می‌کند.

Registry پیش‌فرض npm به آدرس زیر است:

https://registry.npmjs.org/

npm از مقدار تنظیم‌شده در گزینه registry به‌عنوان آدرس Registry استفاده می‌کند.

تفاوت NPM Registry و NPM Mirror چیست؟

ویژگی	NPM Registry	NPM Mirror
کاربرد	منبع اصلی یا انتخاب‌شده برای دریافت پکیج‌ها	مسیر جایگزین برای دسترسی به پکیج‌ها
نمونه	registry.npmjs.org	Mirrorهای ارائه‌شده توسط سرویس‌دهندگان مختلف
هدف	مدیریت و ارائه پکیج‌ها	بهبود دسترسی یا ایجاد مسیر جایگزین
تنظیم در npm	از طریق گزینه registry	به‌عنوان یک Registry جایگزین تنظیم می‌شود

چطور NPM Registry فعلی را ببینیم؟

قبل از تغییر Registry بهتر است ابتدا بررسی کنید npm در حال حاضر از چه آدرسی استفاده می‌کند.

npm config get registry

اگر تنظیمات پیش‌فرض فعال باشد، معمولاً خروجی مشابه زیر خواهد بود:

https://registry.npmjs.org/

استفاده از NPM Mirror برای کاربران ایرانی

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

یکی از سرویس‌هایی که برای این منظور در دسترس توسعه‌دهندگان ایرانی قرار گرفته، NPM Mirror رانفلر است.

قبل از استفاده دائمی از هر Mirror بهتر است مستندات رسمی سرویس‌دهنده را بررسی کنید، زیرا آدرس، شرایط استفاده یا ساختار سرویس ممکن است در طول زمان تغییر کند.

تنظیم NPM Mirror

برای تغییر Registry در npm از دستور زیر استفاده می‌شود:

npm config set registry MIRROR_URL

عبارت MIRROR_URL را باید با آدرس Mirror موردنظر جایگزین کنید.

بررسی Registry بعد از تغییر

بعد از اعمال تنظیمات دوباره دستور زیر را اجرا کنید:

npm config get registry

به این ترتیب می‌توانید مطمئن شوید Registry جدید به‌درستی ثبت شده است.

نصب یک پکیج با Registry جایگزین بدون تغییر تنظیمات دائمی

اگر نمی‌خواهید تنظیمات اصلی npm را تغییر دهید، می‌توانید Registry را فقط برای همان دستور مشخص کنید.

npm install express --registry=MIRROR_URL

این روش برای تست یک Mirror یا استفاده موقت از Registry جایگزین مناسب است.

برگرداندن NPM Registry به حالت پیش‌فرض

اگر بعداً خواستید دوباره از Registry رسمی npm استفاده کنید، دستور زیر را اجرا کنید:

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

سپس مقدار Registry را بررسی کنید:

npm config get registry

حذف تنظیم سفارشی Registry

روش دیگر این است که مقدار سفارشی Registry را از تنظیمات npm حذف کنید:

npm config delete registry

بعد از آن npm می‌تواند دوباره از تنظیمات پیش‌فرض خود استفاده کند.

استفاده از NPM Mirror در فایل .npmrc

یکی از روش‌های رایج برای تنظیم Registry در سطح پروژه استفاده از فایل .npmrc است.

در ریشه پروژه یک فایل با نام زیر ایجاد کنید:

.npmrc

سپس مقدار Registry را داخل آن قرار دهید:

registry=MIRROR_URL

این روش زمانی مناسب است که می‌خواهید تنظیمات Registry فقط برای یک پروژه خاص اعمال شود.

تفاوت تنظیم Registry در پروژه و تنظیم Global

روش	محدوده اثر	کاربرد مناسب
.npmrc پروژه	فقط پروژه فعلی	پروژه‌هایی که Registry مشخص دارند
npm config	بسته به محل تنظیمات	استفاده عمومی در محیط توسعه
–registry در دستور	فقط همان اجرا	تست یا استفاده موقت

استفاده از NPM Mirror در Docker

اگر پروژه Node.js را با Docker اجرا می‌کنید، می‌توانید Registry را قبل از اجرای npm install تنظیم کنید.

FROM node:22-alpine

WORKDIR /app

COPY package*.json ./

RUN npm config set registry MIRROR_URL

RUN npm install

COPY . .

CMD ["npm", "start"]

در این مثال، npm هنگام ساخت Image از Registry انتخاب‌شده استفاده می‌کند.

استفاده از NPM Mirror در CI/CD

در Pipelineهای CI/CD نیز می‌توان Registry را قبل از نصب Dependencyها تنظیم کرد.

برای مثال:

npm config set registry MIRROR_URL
npm ci

اگر Pipelineهای شما در دانلود پکیج‌ها دچار Timeout یا ناپایداری هستند، استفاده از Registry مناسب می‌تواند یکی از مواردی باشد که ارزش بررسی دارد.

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

در محیط توسعه معمولاً از npm install برای نصب یا تغییر Dependencyها استفاده می‌شود.

اما در CI/CD اغلب npm ci انتخاب مناسب‌تری است؛ زیرا نصب را بر اساس package-lock.json انجام می‌دهد و برای اجرای قابل‌تکرار در محیط‌های خودکار طراحی شده است.

استفاده از nrm برای مدیریت چند NPM Registry

اگر مرتب بین چند Registry جابه‌جا می‌شوید، ابزارهایی مانند nrm می‌توانند مدیریت Registryها را ساده‌تر کنند.

برای نصب nrm:

npm install -g nrm

برای مشاهده Registryهای موجود:

nrm ls

همچنین می‌توانید Registry سفارشی خود را اضافه کنید:

nrm add mymirror MIRROR_URL

و سپس آن را فعال کنید:

nrm use mymirror

رفع خطای Timeout در npm

خطای Timeout ممکن است دلایل مختلفی داشته باشد؛ از مشکلات شبکه گرفته تا دسترسی ناپایدار به Registry.

در اولین مرحله Registry فعلی را بررسی کنید:

npm config get registry

سپس می‌توانید اتصال را با Registry دیگری آزمایش کنید.

رفع خطای ECONNRESET در npm

خطای ECONNRESET معمولاً به قطع شدن ارتباط شبکه در حین دریافت اطلاعات مربوط است.

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

همچنین در صورت نیاز می‌توانید Registry دیگری را به‌صورت موقت تست کنید:

npm install package-name --registry=MIRROR_URL

رفع خطای 403 در npm

خطای 403 معمولاً نشان می‌دهد سرور درخواست را دریافت کرده اما اجازه دسترسی به Resource موردنظر را نداده است.

در چنین شرایطی ابتدا Registry را بررسی کنید:

npm config get registry

اگر از Registry خصوصی یا Mirror استفاده می‌کنید، تنظیمات احراز هویت و فایل .npmrc نیز باید بررسی شوند.

پاک کردن Cache در npm

در برخی مشکلات مربوط به نصب پکیج‌ها ممکن است بررسی Cache هم مفید باشد.

برای بررسی Cache:

npm cache verify

در شرایط خاص می‌توانید Cache را به‌صورت اجباری پاک کنید:

npm cache clean --force

استفاده از --force را فقط زمانی انجام دهید که واقعاً به آن نیاز دارید.

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

اگر مشکل از Dependencyهای نصب‌شده یا Lock File باشد، گاهی نصب مجدد می‌تواند کمک کند.

rm -rf node_modules
npm install

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

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

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

ابتدا مشکل Registry، شبکه، Cache و خود Dependencyها را بررسی کنید و تنها در صورت وجود دلیل مشخص سراغ حذف Lock File بروید.

آیا استفاده از NPM Mirror امن است؟

استفاده از یک Registry جایگزین یعنی مسیر دریافت Metadata و Packageها را به سرویس دیگری می‌سپارید. بنابراین انتخاب سرویس‌دهنده معتبر اهمیت زیادی دارد.

قبل از استفاده از هر Mirror، مستندات سرویس‌دهنده، HTTPS، سیاست‌های امنیتی، نحوه Sync شدن Packageها و شرایط استفاده از سرویس را بررسی کنید.

برای پروژه‌های حساس سازمانی بهتر است Registry مورد استفاده بخشی از سیاست امنیتی و مدیریت Dependencyهای تیم باشد.

چطور بفهمیم مشکل واقعاً از NPM Registry است؟

اول Registry فعلی را بررسی کنید:

npm config get registry

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

npm install package-name --registry=OTHER_REGISTRY

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

NPM Mirror برای چه کسانی مفید است؟

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

همچنین تیم‌هایی که در CI/CD تعداد زیادی Dependency دانلود می‌کنند، ممکن است از یک Registry یا Proxy Registry کنترل‌شده در زیرساخت خود استفاده کنند.

آیا NPM Mirror سرعت دانلود را همیشه بیشتر می‌کند؟

خیر. سرعت به عوامل مختلفی مانند موقعیت جغرافیایی، کیفیت اتصال، وضعیت سرویس Mirror، Cache و مسیر شبکه وابسته است.

بنابراین بهتر است به‌جای تکیه بر یک عدد ثابت، چند Registry را در محیط واقعی خودتان تست کنید.

چه زمانی بهتر است از Registry اصلی npm استفاده کنیم؟

اگر Registry رسمی npm بدون مشکل و با سرعت مناسب در دسترس شماست، معمولاً نیازی به استفاده از Mirror وجود ندارد.

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

سوالات متداول درباره NPM Mirror

NPM Mirror چیست؟

NPM Mirror یک مسیر جایگزین برای دسترسی به پکیج‌های npm است که می‌تواند به‌عنوان Registry در تنظیمات npm استفاده شود.

NPM Registry اصلی چیست؟

Registry پیش‌فرض npm در آدرس زیر قرار دارد:

https://registry.npmjs.org/

چطور Registry فعلی npm را ببینیم؟

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

npm config get registry

چطور NPM Registry را تغییر دهیم؟

از دستور زیر استفاده کنید:

npm config set registry MIRROR_URL

چطور NPM Mirror را غیرفعال کنیم؟

برای بازگرداندن Registry رسمی npm می‌توانید این دستور را اجرا کنید:

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

آیا می‌توان Registry را فقط برای یک دستور تغییر داد؟

بله. برای مثال:

npm install express --registry=MIRROR_URL

آیا NPM Mirror مشکل ECONNRESET را همیشه حل می‌کند؟

خیر. ECONNRESET می‌تواند دلایل مختلفی مانند شبکه، Proxy، VPN، Firewall یا Registry داشته باشد. تغییر Registry فقط یکی از روش‌های عیب‌یابی است.

آیا حذف npm cache برای رفع مشکلات ضروری است؟

خیر. ابتدا بهتر است از npm cache verify استفاده کنید و فقط در شرایط ضروری Cache را با گزینه --force پاک کنید.

آیا NPM Mirror برای Docker هم قابل استفاده است؟

بله. می‌توانید Registry را قبل از اجرای npm install یا npm ci داخل Dockerfile تنظیم کنید.

آیا بهتر است Registry را داخل .npmrc قرار دهیم؟

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

جمع‌بندی

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

مهم‌ترین نکته این است که قبل از تغییر تنظیمات، Registry فعلی را بررسی کنید و تغییرات را ابتدا به‌صورت موقت تست کنید.

برای مشاهده Registry فعلی:

npm config get registry

برای بازگرداندن npm به Registry رسمی:

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

اگر مشکل شما صرفاً مربوط به Mirror نیست و هنگام اجرای npm install با خطاهایی مانند Timeout، ECONNRESET یا 403 مواجه می‌شوید، بهتر است راهنمای کامل رفع خطاهای npm را نیز بررسی کنید.