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

لماذا لا يزال يظهر 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 معقدًا للغاية ويصعب صيانته. إلى جانب حقيقة أن السجلات المختلفة قد تتطلب رموزًا مميزة مختلفة، فإن إدارة متغيرات البيئة هذه وحدها تكفي لإشباعك.

هل هناك طريقة أذكى؟

الحل الموصى به: سجل مجموعة التنزيل الموحد وسجل مشروع النشر المستقل

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

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

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

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

# .npmrc
# رمز مصادقة مستوى المجال العام (يغطي جميع طلبات التثبيت على مستوى المجموعة والمشروع)
//gitlab.com/:_authToken=${GITLAB_NPM_TOKEN}

# للنشر: رمز مصادقة مستوى المشروع (يتطلب npm publish مطابقة دقيقة للمسار)
//gitlab.com/api/v4/projects/YOUR_PROJECT_ID/packages/npm/:_authToken=${GITLAB_NPM_TOKEN}

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

# الحزم العامة الأخرى لا تزال تذهب إلى المكتبة الرسمية
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/"
  }
}

الخاتمة

من خلال استراتيجية “سجل مجموعة التنزيل الموحد” و “سجل مشروع النشر المستقل”، يمكننا تقليل تكاليف الصيانة بشكل كبير وجعل عملية التطوير أكثر سلاسة.

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