يوفر Bun استراتيجية تثبيت حزم بديلة تسمى التثبيتات المعزولة التي تنشئ عزل تبعيات صارم مشابه لنهج pnpm. يمنع هذا الوضع تبعيات الوهم ويضمن عمليات بناء قابلة للتكرار وحتمية.

هذه هي استراتيجية التثبيت الافتراضية لمشاريع مساحة العمل/monorepo الجديدة (مع configVersion = 1 في ملف القفل). تستمر المشاريع الموجودة باستخدام التثبيتات المرفوعة ما لم يتم تكوينها صراحةً.

ما هي التثبيتات المعزولة؟

تنشئ التثبيتات المعزولة هيكل تبعية غير مرفوع حيث لا يمكن للحزم الوصول إلا إلى تبعياتها المعلنة صراحةً. يختلف هذا عن استراتيجية التثبيت "المرفوعة" التقليدية المستخدمة بواسطة npm و Yarn، حيث يتم تسطيح التبعيات في مجلد node_modules مشترك.

الفوائد الرئيسية

• يمنع تبعيات الوهم — لا يمكن للحزم استيراد التبعيات التي لم تعلنها عن طريق الخطأ
• حل حتمي — شجرة التبعيات نفسها بغض النظر عما تم تثبيته أيضًا
• أفضل لـ monorepos — منع عزل مساحة العمل التلوث المتبادل بين الحزم
• بناء قابل للتكرار — سلوك حل أكثر قابلية للتنبؤ عبر البيئات

استخدام التثبيتات المعزولة

سطر الأوامر

استخدم العلامة --linker لتحديد استراتيجية التثبيت:

# استخدام التثبيتات المعزولة
bun install --linker isolated

# استخدام التثبيتات المرفوعة التقليدية
bun install --linker hoisted

ملف التكوين

اضبط استراتيجية الربط الافتراضية في bunfig.toml أو عالميًا في $HOME/.bunfig.toml:

[install]
linker = "isolated"

السلوك الافتراضي

يعتمد سلوك الربط الافتراضي على configVersion لملف القفل الخاص بمشروعك:

configVersion	استخدام مساحات العمل؟	الربط الافتراضي
1	✅	isolated
1	❌	hoisted
0	✅	hoisted
0	❌	hoisted

المشاريع الجديدة: الافتراضي إلى configVersion = 1. في مساحات العمل، يستخدم v1 الربط المعزول افتراضيًا؛ وإلا يستخدم الربط المرفوع.

مشاريع Bun الموجودة (المصنوعة قبل v1.3.2): إذا لم يكن ملف القفل الموجود لديك يحتوي على إصدار بعد، يضبط Bun configVersion = 0 عند تشغيل bun install، مما يحافظ على افتراضي الربط المرفوع السابق.

الهجرات من مديري الحزم الآخرين:

• من pnpm: configVersion = 1 (استخدام التثبيتات المعزولة في مساحات العمل)
• من npm أو yarn: configVersion = 0 (استخدام التثبيتات المرفوعة)

يمكنك تجاوز السلوك الافتراضي عن طريق تحديد العلامة --linker صراحةً أو تعيينها في ملف التكوين الخاص بك.

كيف تعمل التثبيتات المعزولة

هيكل الدليل

بدلاً من رفع التبعيات، تنشئ التثبيتات المعزولة هيكلًا من مستويين:

node_modules/
├── .bun/                          # مخزن الحزم المركزي
│   ├── package@1.0.0/             # تثبيتات الحزم بالإصدار
│   │   └── node_modules/
│   │       └── package/           # ملفات الحزمة الفعلية
│   ├── @scope+package@2.1.0/      # الحزم ذات النطاق (+ يستبدل /)
│   │   └── node_modules/
│   │       └── @scope/
│   │           └── package/
│   └── ...
└── package-name -> .bun/package@1.0.0/node_modules/package  # روابط رمزية

خوارزمية الحل

1. المخزن المركزي — يتم تثبيت جميع الحزم في أدلة node_modules/.bun/package@version/
2. الروابط الرمزية — يحتوي node_modules على المستوى الأعلى على روابط رمزية تشير إلى المخزن المركزي
3. حل النظراء — تبعيات النظير المعقدة تنشئ أسماء أدلة متخصصة
4. إلغاء التكرار — يتم مشاركة الحزم ذات معرفات الحزم المتطابقة ومجموعات تبعيات النظير

معالجة مساحة العمل

في monorepos، يتم معالجة تبعيات مساحة العمل بشكل خاص:

• حزم مساحة العمل — مرتبطة رمزيًا مباشرة بمجلدات المصدر الخاصة بها، وليس المخزن
• تبعيات مساحة العمل — يمكن الوصول إلى حزم مساحة العمل الأخرى في monorepo
• التبعيات الخارجية — مثبتة في المخزن المعزول مع العزل المناسب

مقارنة مع التثبيتات المرفوعة

الجانب	المرفوعة (npm/Yarn)	المعزولة (pnpm-like)
الوصول إلى التبعيات	يمكن للحزم الوصول إلى أي تبعية مرفوعة	ترى الحزم التبعيات المعلنة فقط
تبعيات الوهم	❌ ممكنة	✅ ممنوعة
استخدام القرص	✅ أقل (تثبيتات مشتركة)	✅ مشابه (يستخدم روابط رمزية)
الحتمية	❌ أقل حتمية	✅ أكثر حتمية
توافق Node.js	✅ السلوك القياسي	✅ متوافق عبر الروابط الرمزية
الأفضل لـ	المشاريع الفردية، الكود القديم	monorepos، إدارة التبعيات الصارمة

ميزات متقدمة

معالجة تبعيات النظير

تتعامل التثبيتات المعزولة مع تبعيات النظير من خلال حل متطور:

# الحزمة ذات تبعيات النظير تنشئ مسارات متخصصة
node_modules/.bun/package@1.0.0_react@18.2.0/

يشفر اسم الدليل كلاً من إصدار الحزمة وإصدارات تبعيات النظير الخاصة بها، مما يضمن حصول كل تركيبة فريدة على تثبيتها الخاص.

استراتيجيات الخلفية

يستخدم Bun استراتيجيات عمليات ملفات مختلفة للأداء:

• Clonefile (macOS) - استنساخ نظام ملفات نسخ عند الكتابة لأقصى كفاءة
• Hardlink (Linux/Windows) - روابط صلبة لتوفير مساحة القرص
• Copyfile (احتياطي) - نسخ ملفات كاملة عندما لا تتوفر الطرق الأخرى

تصحيح التثبيتات المعزولة

قم بتمكين التسجيل التفصيلي لفهم عملية التثبيت:

bun install --linker isolated --verbose

يظهر هذا:

• إنشاء إدخال المخزن
• عمليات الرابط الرمزي
• حل تبعيات النظير
• قرارات إلغاء التكرار

استكشاف الأخطاء وإصلاحها

مشاكل التوافق

قد لا تعمل بعض الحزم بشكل صحيح مع التثبيتات المعزولة بسبب:

• المسارات المشفرة - الحزم التي تفترض هيكل node_modules مسطح
• الاستيرادات الديناميكية - الاستيرادات وقت التشغيل التي لا تتبع حل Node.js
• أدوات البناء - الأدوات التي تفحص node_modules مباشرة

إذا واجهت مشاكل، يمكنك:

1. التبديل إلى الوضع المرفوع لمشاريع محددة:

   bun install --linker hoisted

2. الإبلاغ عن مشاكل التوافق للمساعدة في تحسين دعم التثبيت المعزول

اعتبارات الأداء

• وقت التثبيت - قد يكون أبطأ قليلاً بسبب عمليات الرابط الرمزي
• استخدام القرص - مشابه للمرفوعة (يستخدم روابط رمزية، ليس نسخ ملفات)
• استخدام الذاكرة - أعلى أثناء التثبيت بسبب حل النظير المعقد

دليل الهجرة

من npm/Yarn

# إزالة node_modules وملفات القفل الموجودة
rm -rf node_modules package-lock.json yarn.lock

# التثبيت مع الربط المعزول
bun install --linker isolated

من pnpm

التثبيتات المعزولة مشابهة من حيث المبدأ لـ pnpm، لذا يجب أن تكون الهجرة مباشرة:

# إزالة ملفات pnpm
rm -rf node_modules pnpm-lock.yaml

# التثبيت مع الربط المعزول لـ Bun
bun install --linker isolated

الفرق الرئيسي هو أن Bun يستخدم روابط رمزية في node_modules بينما يستخدم pnpm مخزنًا عالميًا مع روابط رمزية.

متى تستخدم التثبيتات المعزولة

استخدم التثبيتات المعزولة عندما:

• العمل في monorepos مع حزم متعددة
• إدارة التبعيات الصارمة مطلوبة
• منع تبعيات الوهم مهم
• بناء مكتبات تحتاج تبعيات حتمية

استخدم التثبيتات المرفوعة عندما:

• العمل مع كود قديم يفترض node_modules مسطح
• التوافق مع أدوات البناء الموجودة مطلوب
• العمل في بيئات حيث الروابط الرمزية غير مدعومة جيدًا
• تفضل سلوك npm التقليدي الأبسط

التوثيق ذي الصلة

• مدير الحزم > مساحات العمل - إدارة مساحة عمل monorepo
• مدير الحزم > ملف القفل - فهم تنسيق ملف قفل Bun
• CLI > install - مرجع أمر bun install الكامل