كيفية إعداد البروكسي لـ npm عند حظر registry: المرايا، .npmrc وطرق تجاوز القيود

```html

npm-registry غير متاح - وقد توقفت عملية بناء المشروع تمامًا. إنها حالة مألوفة للمطورين في الشبكات المؤسسية، أو في المناطق ذات الوصول المحدود، أو عند العمل من خلال جدار ناري صارم. في هذا الدليل، سنستعرض جميع الطرق الفعالة: من التبديل إلى المرايا إلى التكوين الدقيق للبروكسي في .npmrc - لجعل npm install يعمل مرة أخرى بدون أخطاء.

لماذا يتم حظر npm registry وماذا يحدث عند ذلك

يقع npm registry الرسمي على العنوان https://registry.npmjs.org. إنه CDN عالمي، لكنه قد يكون غير متاح لعدة أسباب، وكل منها يتطلب نهجًا مختلفًا.

الأسباب الرئيسية لعدم توفر registry

• جدار ناري مؤسسي - تمنع الشركة الطلبات المباشرة إلى المستودعات الخارجية، مما يسمح بحركة المرور فقط عبر خادم بروكسي داخلي. هذه ممارسة قياسية في البنوك، والهيئات الحكومية، والشركات الكبيرة في مجال تكنولوجيا المعلومات.
• حظر جغرافي أو قيود إقليمية - في بعض البلدان والمناطق، يتم تقييد الوصول إلى npmjs.org على مستوى مزود خدمة الإنترنت أو جدار الحماية الحكومي.
• شبكة مكتبية بدون وصول مباشر إلى الإنترنت - الآلات العاملة في أقسام معزولة من الشبكة ليس لديها وصول مباشر إلى الموارد الخارجية، حيث تمر جميع حركة المرور عبر بوابة الشركة.
• نفق VPN مع بروكسي إلزامي - يقوم VPN المؤسسي بإعادة توجيه جميع حركة المرور، ولا يمكن لـ npm الوصول إلى registry مباشرة.
• مشاكل في فحص SSL - يقوم بروكسي الشركة باعتراض حركة مرور HTTPS واستبدال الشهادات، مما يتسبب في أخطاء مثل SELF_SIGNED_CERT_IN_CHAIN أو UNABLE_TO_VERIFY_LEAF_SIGNATURE.

الأخطاء الشائعة عند حظر registry

npm ERR! code ECONNREFUSED
npm ERR! errno ECONNREFUSED
npm ERR! network request to https://registry.npmjs.org/react failed

npm ERR! code ETIMEDOUT
npm ERR! network This is a problem related to network connectivity.

npm ERR! code CERT_HAS_EXPIRED
npm ERR! code SELF_SIGNED_CERT_IN_CHAIN

كل من هذه الرموز تشير إلى مشكلة مختلفة: ECONNREFUSED - تم رفض الاتصال بواسطة جدار الحماية، ETIMEDOUT - الطلب يذهب إلى لا شيء (محظور بدون رد)، وأخطاء الشهادات - مشكلة في فحص SSL. فهم السبب يضيق دائرة الحلول على الفور.

مرايا npm registry: تجاوز سريع بدون بروكسي

أسهل طريقة لتجاوز الحظر هي تحويل npm إلى مرآة بديلة للregistry. تحتوي المرآة على نفس الحزم مثل registry الرسمي، ولكنها موجودة على خوادم ونطاقات أخرى. هذا يعمل عندما يتم حظر نطاق registry.npmjs.org فقط، وليس كل حركة مرور HTTPS.

المرايا الشهيرة لـ npm

كيفية تحويل registry

التحويل لعملية واحدة (بدون تغيير الإعدادات العالمية):

# تثبيت لمرة واحدة عبر registry بديل
npm install react --registry https://registry.npmmirror.com

# تثبيت عالميًا للمستخدم الحالي
npm config set registry https://registry.npmmirror.com

# التحقق من registry الحالي
npm config get registry

# العودة إلى registry الرسمي
npm config set registry https://registry.npmjs.org

نقطة مهمة: إذا كنت تقوم بالتبديل إلى مرآة في مشروع مع فريق، من الأفضل تثبيت ذلك في ملف .npmrc في جذر المستودع - حينها سيحصل جميع أعضاء الفريق تلقائيًا على التكوين الصحيح عند استنساخ المشروع.

# .npmrc في جذر المشروع
registry=https://registry.npmmirror.com

إعداد البروكسي عبر .npmrc: الصيغة الكاملة

عندما لا تساعد المرآة (على سبيل المثال، عندما يتم حظر كل حركة مرور HTTPS الخارجية)، يجب تحديد عنوان خادم البروكسي لـ npm بشكل صريح. ملف .npmrc هو الملف الرئيسي لتكوين npm، وهو المكان الذي يتم فيه تخزين إعدادات البروكسي.

مواقع ملفات .npmrc

يبحث npm عن التكوين في عدة أماكن - حسب الأولوية (من الأعلى إلى الأدنى):

• مشروع - /path/to/project/.npmrc - ينطبق فقط على هذا المشروع
• مستخدم - ~/.npmrc - ينطبق على المستخدم الحالي للنظام
• عالمي - $PREFIX/etc/npmrc - ينطبق على كل تثبيت npm
• مضمن - /path/to/npm/npmrc - الإعدادات الافتراضية لـ npm نفسه

صيغة إعداد البروكسي في .npmrc

# بروكسي لحركة مرور HTTP
proxy=http://proxy.example.com:8080

# بروكسي لحركة مرور HTTPS (يستخدم لمعظم الطلبات إلى registry)
https-proxy=http://proxy.example.com:8080

# بروكسي مع المصادقة (اسم المستخدم:كلمة المرور في URL)
proxy=http://username:[email protected]:8080
https-proxy=http://username:[email protected]:8080

# الاستثناءات - العناوين التي تتجاوز البروكسي
noproxy=localhost,127.0.0.1,internal.company.com

تعيين البروكسي عبر أوامر npm config

بديل لتحرير الملف يدويًا - استخدام الأمر npm config set. سيقوم تلقائيًا بتسجيل الإعدادات في ~/.npmrc:

# تعيين البروكسي
npm config set proxy http://proxy.example.com:8080
npm config set https-proxy http://proxy.example.com:8080

# التحقق من إعدادات البروكسي الحالية
npm config get proxy
npm config get https-proxy

# حذف إعدادات البروكسي (العودة إلى الاتصال المباشر)
npm config delete proxy
npm config delete https-proxy

# عرض كل تكوين npm
npm config list

بروكسي عبر متغيرات البيئة لـ npm

يقرأ npm تلقائيًا متغيرات البيئة النظامية القياسية للبروكسي. هذا مفيد في خطوط CI/CD، وحاويات Docker، والأنظمة التي يتم فيها تحديد التكوين على مستوى البيئة، وليس الملفات.

متغيرات البيئة القياسية

# Linux / macOS - تعيين في الجلسة الحالية
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1

# النسخ الصغيرة (npm يفهم كلاهما)
export http_proxy=http://proxy.example.com:8080
export https_proxy=http://proxy.example.com:8080

# Windows (موجه الأوامر)
set HTTP_PROXY=http://proxy.example.com:8080
set HTTPS_PROXY=http://proxy.example.com:8080

# Windows (PowerShell)
$env:HTTP_PROXY = "http://proxy.example.com:8080"
$env:HTTPS_PROXY = "http://proxy.example.com:8080"

أولوية تكوين npm

من المهم فهم أن npm يستخدم الأولوية التالية لتحديد البروكسي (من الأعلى إلى الأدنى):

1. علامات سطر الأوامر: --proxy http://...
2. متغيرات البيئة مع بادئة npm_config_: على سبيل المثال، npm_config_proxy
3. مشروع .npmrc
4. مستخدم ~/.npmrc
5. عالمي $PREFIX/etc/npmrc
6. متغيرات البيئة القياسية HTTP_PROXY / HTTPS_PROXY

إذا تم إعداد البروكسي في .npmrc، ولكن متغير البيئة يشير إلى عنوان آخر - سيفوز .npmrc. هذه هي سبب شائع للارتباك في أنظمة CI/CD.

الإعداد في CI/CD (GitHub Actions، GitLab CI)

# GitHub Actions - إضافة إلى قسم env في الوظيفة أو الخطوة
jobs:
  build:
    runs-on: ubuntu-latest
    env:
      HTTP_PROXY: http://proxy.example.com:8080
      HTTPS_PROXY: http://proxy.example.com:8080
      NO_PROXY: localhost,127.0.0.1
    steps:
      - uses: actions/checkout@v3
      - run: npm install

# GitLab CI - في متغيرات المشروع أو في .gitlab-ci.yml
variables:
  HTTP_PROXY: "http://proxy.example.com:8080"
  HTTPS_PROXY: "http://proxy.example.com:8080"

بروكسي الشركات مع المصادقة وفحص SSL

تعتبر خوادم بروكسي الشركات الحالة الأكثر تعقيدًا. فهي لا تقوم فقط بإعادة توجيه حركة المرور، بل تتطلب أيضًا المصادقة، وغالبًا ما تقوم بفحص SSL (اعتراض وفك تشفير حركة مرور HTTPS). وهذا يؤدي إلى أخطاء محددة في الشهادات، التي لا يستطيع npm التعامل معها بشكل افتراضي.

بروكسي مع المصادقة NTLM/Basic

إذا كان بروكسي الشركة يتطلب اسم مستخدم وكلمة مرور (المصادقة الأساسية)، يمكن تمريرها مباشرة في URL. ومع ذلك، فإن المصادقة NTLM (نطاق Windows) أكثر تعقيدًا - لا يدعم npm NTLM بشكل أصلي. في هذه الحالة، يتم استخدام أداة وسيطة.

# المصادقة الأساسية - اسم المستخدم وكلمة المرور في URL
npm config set proxy http://user:[email protected]:8080
npm config set https-proxy http://user:[email protected]:8080

# إذا كانت كلمة المرور تحتوي على رموز خاصة - يجب ترميزها في URL
# @ → %40، # → %23، : → %3A
# مثال: كلمة المرور "p@ss#word" → "p%40ss%23word"
npm config set proxy http://user:p%40ss%[email protected]:8080

للمصادقة NTLM، يتم استخدام الأداة cntlm - يتم تشغيلها محليًا، وتقبل طلبات HTTP العادية وتقوم بإجراء المصافحة NTLM مع بروكسي الشركة. بالنسبة لـ npm، يبدو هذا كبروكسي عادي بدون مصادقة:

# بعد إعداد cntlm، فإنه يستمع على localhost:3128
npm config set proxy http://localhost:3128
npm config set https-proxy http://localhost:3128

حل مشكلة فحص SSL

تقوم بروكسي الشركات مع فحص SSL باستبدال شهادات المواقع بشهادتها الخاصة. يتحقق npm من سلسلة الثقة ويرفض هذه الشهادات. هناك ثلاث طرق:

الطريقة 1 (موصى بها): إضافة شهادة CA المؤسسية إلى الموثوق بها

# الحصول على الشهادة المؤسسية من قسم تكنولوجيا المعلومات (ملف .crt أو .pem)
# تحديدها في تكوين npm
npm config set cafile /path/to/corporate-ca.crt

# أو إضافة عدة شهادات عبر cafile
# يمكن دمج عدة CA في ملف PEM واحد

الطريقة 2 (مؤقتة، غير آمنة): تعطيل التحقق من SSL

# استخدم فقط كحل مؤقت للتشخيص!
npm config set strict-ssl false

# أو لعملية واحدة
npm install --legacy-peer-deps --no-strict-ssl

SOCKS5 بروكسي لـ npm: الإعداد عبر أدوات المساعدة

يدعم npm بشكل أصلي فقط بروكسي HTTP/HTTPS. إذا كان لديك بروكسي SOCKS5 (على سبيل المثال، من مزود بروكسي سكنية)، لا يمكن تحديده مباشرة في تكوين npm. تحتاج إلى طبقة وسيطة - أداة تقبل طلبات HTTP من npm وتعيد توجيهها عبر SOCKS5.

الطريقة 1: proxychains (Linux/macOS)

# تثبيت proxychains
# Ubuntu/Debian:
sudo apt-get install proxychains4

# macOS:
brew install proxychains-ng

# تكوين /etc/proxychains4.conf
[ProxyList]
socks5 proxy.example.com 1080 username password

# تشغيل npm عبر proxychains
proxychains4 npm install

الطريقة 2: محول HTTP المحلي إلى SOCKS5

تقوم الأداة privoxy أو polipo بإنشاء بروكسي HTTP محلي، يقوم بتوجيه حركة المرور عبر SOCKS5. بعد التشغيل، يرى npm بروكسي HTTP عادي على localhost:

# تثبيت privoxy
sudo apt-get install privoxy  # Ubuntu/Debian
brew install privoxy          # macOS

# إضافة إلى التكوين /etc/privoxy/config:
forward-socks5 / proxy.example.com:1080 .

# Privoxy يستمع على localhost:8118 بشكل افتراضي
# تحديد npm لاستخدام هذا العنوان:
npm config set proxy http://localhost:8118
npm config set https-proxy http://localhost:8118

الطريقة 3: نفق SSH كبروكسي SOCKS5

إذا كان لديك وصول إلى خادم بعيد مع إنترنت مفتوح، يمكنك إنشاء نفق SSH SOCKS5 وتوجيه حركة مرور npm عبره. هذا مفيد بشكل خاص عند العمل من شبكة مؤسسية مع وصول محدود:

# إنشاء نفق SSH SOCKS5 على المنفذ المحلي 1080
ssh -D 1080 -f -C -q -N [email protected]

# بعد ذلك، استخدم privoxy أو proxychains للتحويل إلى HTTP
# أو مباشرة عبر متغير البيئة (Node.js يفهم SOCKS عبر بعض المكتبات)

# بديل - استخدام curl كاختبار:
curl --socks5 localhost:1080 https://registry.npmjs.org/react/latest

registry خاص كبديل للبروكسي

في البيئات المؤسسية والمعزولة، غالبًا ما يكون الحل الأفضل هو عدم إعداد بروكسي لكل مطور، بل نشر registry npm خاص داخل الشبكة. يقوم هذا registry بتخزين الحزم من npmjs.org العامة ويقدمها من الشبكة الداخلية. لا يحتاج المطورون إلى الوصول إلى الإنترنت - كل شيء يعمل عبر registry المحلي.

Verdaccio: بدء سريع خلال 10 دقائق

Verdaccio هو npm-registry مفتوح المصدر يدعم البروكسي والتخزين المؤقت. يتم تثبيته كحزمة npm، ويعمل كخدمة منفصلة:

# تثبيت Verdaccio عالميًا
npm install -g verdaccio

# التشغيل (يستمع بشكل افتراضي على http://localhost:4873)
verdaccio

# إعداد npm لاستخدام registry المحلي
npm config set registry http://localhost:4873

# نشر الحزم في registry المحلي
npm adduser --registry http://localhost:4873
npm publish --registry http://localhost:4873

يسمح تكوين Verdaccio (~/.config/verdaccio/config.yaml) بإعداد البروكسي عبر بروكسي خارجي لتحميل الحزم من npmjs.org:

# config.yaml - إعداد uplink مع البروكسي
uplinks:
  npmjs:
    url: https://registry.npmjs.org/
    # إذا كان Verdaccio نفسه خلف بروكسي:
    agent_options:
      http_proxy: http://proxy.company.com:8080
      https_proxy: http://proxy.company.com:8080
      no_proxy: localhost,127.0.0.1

packages:
  '@*/*':
    access: $all
    publish: $authenticated
    proxy: npmjs
  '**':
    access: $all
    publish: $authenticated
    proxy: npmjs

مقارنة الحلول للبيئات المعزولة

تشخيص وحل الأخطاء الشائعة

حتى بعد إعداد البروكسي بشكل صحيح، قد تحدث مشاكل. إليك نهج منهجي للتشخيص وقائمة بأكثر الأخطاء شيوعًا مع حلولها.

الخطوة 1: التحقق من تكوين npm الحالي

# عرض جميع إعدادات npm (بما في ذلك البروكسي)
npm config list

# عرض إعدادات البروكسي فقط
npm config get proxy
npm config get https-proxy
npm config get registry
npm config get strict-ssl

# تفعيل الإخراج التفصيلي للتشخيص
npm install react --verbose
npm install react --loglevel verbose

الخطوة 2: التحقق من توفر registry مباشرة

# التحقق من توفر registry عبر curl
curl -v https://registry.npmjs.org/react/latest

# التحقق عبر البروكسي
curl -v --proxy http://proxy.example.com:8080 https://registry.npmjs.org/react/latest

# التحقق من ping (ليس دائمًا مفيدًا لـ HTTPS)
ping registry.npmjs.org

# التحقق من حل DNS
nslookup registry.npmjs.org

الأخطاء الشائعة وحلولها

إعادة تعيين جميع إعدادات البروكسي

# حذف جميع إعدادات البروكسي من التكوين الشخصي
npm config delete proxy
npm config delete https-proxy
npm config delete noproxy

# إعادة تعيين registry إلى الرسمي
npm config set registry https://registry.npmjs.org

# إعادة تعيين strict-ssl (إذا تم تعطيله)
npm config set strict-ssl true

# التحقق من التكوين النهائي
npm config list

العمل مع pnpm و Yarn عند حظر registry

إذا كنت تستخدم مديري حزم بديلين، فإن إعداد البروكسي يبدو مشابهًا، لكن الصيغة تختلف قليلاً:

# pnpm - يستخدم نفس .npmrc مثل npm
# يمكن أيضًا إعداده عبر pnpm config:
pnpm config set proxy http://proxy.example.com:8080
pnpm config set https-proxy http://proxy.example.com:8080
pnpm config set registry https://registry.npmmirror.com

# Yarn Classic (v1) - ملف .yarnrc الخاص به
yarn config set proxy http://proxy.example.com:8080
yarn config set https-proxy http://proxy.example.com:8080
yarn config set registry https://registry.npmmirror.com

# Yarn Berry (v2+) - ملف .yarnrc.yml
# httpProxy: "http://proxy.example.com:8080"
# httpsProxy: "http://proxy.example.com:8080"
# npmRegistryServer: "https://registry.npmmirror.com"

إعداد البروكسي لحزم محددة

أحيانًا تحتاج إلى استخدام registries مختلفة لحزم مختلفة: على سبيل المثال، أخذ الحزم العامة من npmjs.org الرسمية، والحزم المؤسسية @company/* - من Nexus الداخلي. يتم إعداد ذلك عبر registry محددة النطاق في .npmrc:

# .npmrc - registries مختلفة لنطاقات مختلفة
registry=https://registry.npmjs.org

# الحزم المؤسسية @company عبر Nexus الداخلي
@company:registry=http://nexus.company.local/repository/npm-hosted/

# الحزم @myorg عبر Verdaccio
@myorg:registry=http://localhost:4873/

# المصادقة لـ registry محددة
//nexus.company.local/repository/npm-hosted/:_authToken=YOUR_TOKEN_HERE

الخاتمة والتوصيات النهائية

في الختام، يعد إعداد بروكسي لـ npm أمرًا ضروريًا في البيئات التي تواجه حظرًا على الوصول إلى registry. من خلال اتباع الخطوات الموضحة في هذا الدليل، يمكنك تجاوز هذه القيود وضمان سير العمل بسلاسة. تأكد من مراجعة إعداداتك بانتظام وتحديثها حسب الحاجة لضمان الأداء الأمثل.