هل تحاول استخدام الحزمة الخاصة (Private Package) في مشروع شركتك ولكنك عالق في تكوين .npmrc؟

لماذا لا تزال تحصل على 404 Not Found حتى بعد تعيين الرمز المميز (Token)؟

عندما يكون لدى الشركة فرق متعددة وحزم متعددة (مثل @frontend، @backend)، كيف تدير .npmrc بأناقة؟

تحطيم أسطورتي .npmrc

لفهم .npmrc، عليك أولاً أن تفهم كيف يعمل.

ببساطة، منطقه الأساسي هو شيئان فقط: رسم خرائط النطاق (Scope Mapping) و المصادقة (Authentication).

1. رسم خرائط النطاق (Scope Mapping)

هذا يخبر npm: عندما ترى حزمة تبدأ بـ @company، لا تذهب إلى npmjs.org الرسمي، اذهب إلى GitLab Registry المحدد لدينا.

@company:registry=https://gitlab.com/api/v4/groups/100/-/packages/npm/

2. المصادقة (Authentication)

مع العنوان، تحتاج أيضًا إلى مفتاح. المفتاح هو AuthToken الخاص بك.

إليك قاعدة بالغة الأهمية: يجب أن يتطابق عنوان URL للسجل ومسار AuthToken “تمامًا”.

# ✅ صحيح: المسار هو بالضبط نفس السجل المحدد أعلاه
//gitlab.com/api/v4/groups/100/-/packages/npm/:_authToken=${GITLAB_TOKEN}

# ❌ غير صحيح: عدم تطابق المسار، سيؤدي هذا إلى فشل الإذن
//gitlab.com/api/v4/:_authToken=${GITLAB_TOKEN}

يفشل الكثير من الناس في التكوين غالبًا لأن المسار يحتوي على شرطة مائلة إضافية أو يفتقر إلى مستوى واحد.

جحيم التبعية وأخطاء 404

الموقف الأكثر إزعاجًا هو: تقوم بتثبيت الحزمة A، التي تعتمد على الحزمة B (وهي خاصة أيضًا)، ثم يبصق npm 404 Not Found.

لماذا يحدث هذا؟ ذلك لأنه عندما يحل npm التبعيات، إذا لم تكن هناك علاقة صحيحة، فإنه يضيع.

خاصة عندما يكون لديك نطاقان مختلفان (على سبيل المثال @team-a و @team-b) في مجموعات GitLab مختلفة، يصبح .npmrc معقدًا للغاية ويصعب صيانته. بالإضافة إلى ذلك، قد تحتاج السجلات المختلفة إلى رموز مميزة مختلفة، فمجرد إدارة متغيرات البيئة هذه أمر مرهق.

هل هناك طريقة أكثر ذكاءً؟

الحل الموصى به: Unified Download Group Registry و Independent Publish Project Registry

لماذا تفعل هذا؟

التكوين في العمل

يمكنك نسخ هذا القالب مباشرة:

تذكر تسليم مهمة حماية الرمز المميز إلى متغيرات البيئة، لا تقم مطلقًا بكتابة الرمز المميز بشكل ثابت في الكود!

# .npmrc
# @company scope يستخدم سجل مستوى المجموعة
# سيتم تثبيت جميع حزم @company/* من هذا السجل
@company:registry=https://gitlab.com/api/v4/groups/YOUR_GROUP_ID/-/packages/npm/

# تكوين مصادقة GitLab npm registry
# استخدم رمز مصادقة gitlab.com المشترك (يغطي جميع طلبات مستوى المجموعة والمشروع)
//gitlab.com/api/v4/groups/YOUR_GROUP_ID/-/packages/npm/:_authToken=${GITLAB_NPM_TOKEN}
# استخدم سجل المشروع لنشر الحزم
//gitlab.com/api/v4/projects/YOUR_PROJECT_ID/packages/npm/:_authToken=${GITLAB_NPM_TOKEN}


# الحزم العامة الأخرى لا تزال تذهب إلى السجل الرسمي
registry=https://registry.npmjs.org/

قم بتكوين publishConfig في package.json لنشر الحزمة في GitLab Project Registry المقابل.

{
  "name": "@company/my-package",
  "publishConfig": {
    "@company:registry": "https://gitlab.com/api/v4/projects/YOUR_PROJECT_ID/packages/npm/"
  }
}

الخاتمة

من خلال استراتيجية “Unified Download Group Registry” و “Independent Publish Project Registry”، يمكننا تقليل تكاليف الصيانة بشكل كبير وجعل تدفق التطوير أكثر سلاسة.

بإتقان هذه المنطق، سيكون GitLab NPM Registry مساعدًا قويًا في عملية تطوير شركتك!