import Install from "/snippets/cli/install.mdx";

الاستخدام الأساسي

bun install react
bun install react@19.1.1 # إصدار محدد
bun install react@latest # علامة محددة

يحتوي CLI bun على مدير حزم متوافق مع Node.js مصمم ليكون بديلاً أسرع بشكل كبير لـ npm و yarn و pnpm. إنها أداة مستقلة ستعمل في مشاريع Node.js الموجودة مسبقًا؛ إذا كان مشروعك يحتوي على package.json، يمكن أن يساعدك bun install في تسريع سير عملك.

NOTE

⚡️ أسرع 25 مرة — انتقل من npm install إلى bun install في أي مشروع Node.js لجعل تثبيتاتك أسرع حتى 25 مرة.

لمستخدمي Linux

الحد الأدنى الموصى به لإصدار Linux Kernel هو 5.6. إذا كنت على Linux kernel 5.1 - 5.5، سيعمل bun install، لكن طلبات HTTP ستكون بطيئة بسبب عدم وجود دعم لعملية connect() في io_uring.

إذا كنت تستخدم Ubuntu 20.04، إليك كيفية تثبيت نواة أحدث:

# إذا كان هذا يعيد إصدارًا >= 5.6، فلست بحاجة إلى فعل أي شيء
uname -r

# تثبيت نواة تمكين الأجهزة الرسمية لأوبونتو
sudo apt install --install-recommends linux-generic-hwe-20.04

لتثبيت جميع تبعيات المشروع:

bun install

سيؤدي تشغيل bun install إلى:

• تثبيت جميع dependencies و devDependencies و optionalDependencies. سيقوم Bun بتثبيت peerDependencies افتراضيًا.
• تشغيل نصوص {pre|post}install و {pre|post}prepare الخاصة بمشروعك في الوقت المناسب. لأسباب أمنية لا ينفذ Bun نصوص دورة حياة التبعيات المثبتة.
• كتابة ملف قفل bun.lock إلى جذر المشروع.

---

التسجيل

لتعديل مستوى تفصيل التسجيل:

bun install --verbose # تسجيل تصحيح
bun install --silent  # بدون تسجيل

---

نصوص دورة الحياة

على عكس عملاء npm الآخرين، لا ينفذ Bun نصوص دورة حياة عشوائية مثل postinstall للتبعيات المثبتة. يمثل تنفيذ نصوص عشوائية خطر أمان محتمل.

لإخبار Bun بالسماح بنصوص دورة الحياة لحزمة معينة، أضف الحزمة إلى trustedDependencies في package.json الخاص بك.

{
  "name": "my-app",
  "version": "1.0.0",
  "trustedDependencies": ["my-trusted-package"] 
}

ثم أعد تثبيت الحزمة. سيقرأ Bun هذا الحقل ويشغل نصوص دورة الحياة لـ my-trusted-package.

ستعمل نصوص دورة الحياة بالتوازي أثناء التثبيت. لضبط الحد الأقصى لعدد النصوص المتزامنة، استخدم العلامة --concurrent-scripts. الافتراضي هو ضعف عدد وحدات المعالجة المركزية المبلغ عنها أو GOMAXPROCS.

bun install --concurrent-scripts 5

يقوم Bun تلقائيًا بتحسين نصوص postinstall للحزم الشائعة (مثل esbuild و sharp وما إلى ذلك) عن طريق تحديد النصوص التي تحتاج إلى التشغيل. لتعطيل هذه التحسينات:

BUN_FEATURE_FLAG_DISABLE_NATIVE_DEPENDENCY_LINKER=1 bun install
BUN_FEATURE_FLAG_DISABLE_IGNORE_SCRIPTS=1 bun install

---

مساحات العمل

يدعم Bun "workspaces" في package.json. للحصول على التوثيق الكامل راجع مدير الحزم > مساحات العمل.

{
  "name": "my-app",
  "version": "1.0.0",
  "workspaces": ["packages/*"], 
  "dependencies": {
    "preact": "^10.5.13"
  }
}

---

تثبيت التبعيات لحزم محددة

في monorepo، يمكنك تثبيت التبعيات لمجموعة فرعية من الحزم باستخدام العلامة --filter.

# تثبيت التبعيات لجميع مساحات العمل باستثناء `pkg-c`
bun install --filter '!pkg-c'

# تثبيت التبعيات لـ `pkg-a` فقط في `./packages/pkg-a`
bun install --filter './packages/pkg-a'

لمزيد من المعلومات حول التصفية مع bun install، راجع مدير الحزم > التصفية

---

التجاوزات والحلول

يدعم Bun "overrides" الخاص بـ npm و "resolutions" الخاص بـ Yarn في package.json. هذه آليات لتحديد نطاق إصدار لـ التبعيات الفرعية - تبعيات تبعياتك. راجع مدير الحزم > التجاوزات والحلول للحصول على التوثيق الكامل.

{
  "name": "my-app",
  "dependencies": {
    "foo": "^2.0.0"
  },
  "overrides": { 
    "bar": "~4.4.0"
  } 
}

---

الحزم العالمية

لتثبيت حزمة عالميًا، استخدم العلامة -g/--global. يُستخدم هذا عادةً لتثبيت أدوات سطر الأوامر.

bun install --global cowsay # أو `bun install -g cowsay`
cowsay "Bun!"

 ______
< Bun! >
 ------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

---

وضع الإنتاج

للتثبيت في وضع الإنتاج (أي بدون devDependencies أو optionalDependencies):

bun install --production

للتثبيتات القابلة للتكرار، استخدم --frozen-lockfile. سيقوم هذا بتثبيت الإصدارات الدقيقة لكل حزمة محددة في ملف القفل. إذا اختلف package.json الخاص بك مع bun.lock، سيخرج Bun بخطأ. لن يتم تحديث ملف القفل.

bun install --frozen-lockfile

لمزيد من المعلومات حول ملف قفل Bun bun.lock، راجع مدير الحزم > ملف القفل.

---

حذف التبعيات

لحذف تبعيات dev أو peer أو optional استخدم العلامة --omit.

# استبعاد "devDependencies" من التثبيت. سينطبق هذا على
# الحزمة الجذر ومساحات العمل إذا كانت موجودة. التبعيات العابرة لن
# تحتوي على "devDependencies".
bun install --omit dev

# تثبيت التبعيات من "dependencies" فقط
bun install --omit=dev --omit=peer --omit=optional

---

تجربة جافة

لإجراء تجربة جافة (أي عدم تثبيت أي شيء فعليًا):

bun install --dry-run

---

تبعيات غير npm

يدعم Bun تثبيت التبعيات من Git و GitHub و tarballs المستضافة محليًا أو عن بُعد. راجع مدير الحزم > تبعيات Git و GitHub و tarball للحصول على التوثيق الكامل.

{
  "dependencies": {
    "dayjs": "git+https://github.com/iamkun/dayjs.git",
    "lodash": "git+ssh://github.com/lodash/lodash.git#4.17.21",
    "moment": "git@github.com:moment/moment.git",
    "zod": "github:colinhacks/zod",
    "react": "https://registry.npmjs.org/react/-/react-18.2.0.tgz",
    "bun-types": "npm:@types/bun"
  }
}

---

استراتيجيات التثبيت

يدعم Bun استراتيجيتين لتثبيت الحزم تحددان كيفية تنظيم التبعيات في node_modules:

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

نهج npm/Yarn التقليدي الذي يسطح التبعيات في مجلد node_modules مشترك:

bun install --linker hoisted

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

نهج مشابه لـ pnpm ينشئ عزل تبعيات صارم لمنع تبعيات الوهم:

bun install --linker isolated

تنشئ التثبيتات المعزولة مخزن حزم مركزي في node_modules/.bun/ مع روابط رمزية في node_modules على المستوى الأعلى. يضمن هذا أن الحزم لا يمكنها الوصول إلا إلى تبعياتها المعلنة.

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

يعتمد سلوك الربط الافتراضي على ما إذا كنت تبدأ من جديد أو لديك مشروع موجود:

• مساحات عمل/monorepos جديدة: isolated (يمنع تبعيات الوهم)
• مشاريع أحادية الحزمة جديدة: hoisted (سلوك npm التقليدي)
• المشاريع الموجودة (المصنوعة قبل v1.3.2): hoisted (يحافظ على التوافق الخلفي)

يتم التحكم في الافتراضي بواسطة حقل configVersion في ملف القفل الخاص بك. للحصول على شرح مفصل، راجع مدير الحزم > التثبيتات المعزولة.

---

الحد الأدنى لعمر الإصدار

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

# تثبيت إصدارات الحزم التي تم نشرها قبل 3 أيام على الأقل
bun add @types/bun --minimum-release-age 259200 # ثواني

يمكنك أيضًا تكوين هذا في bunfig.toml:

[install]
# تثبيت إصدارات الحزم التي تم نشرها قبل 3 أيام على الأقل
minimumReleaseAge = 259200 # ثواني

# استبعاد الحزم الموثوقة من بوابة العمر
minimumReleaseAgeExcludes = ["@types/node", "typescript"]

عندما يكون مرشح الحد الأدنى للعمر نشطًا:

• يؤثر فقط على حل الحزم الجديدة - تظل الحزم الموجودة في bun.lock دون تغيير
• يتم تصفية جميع التبعيات (المباشرة والعابرة) لتلبية متطلبات العمر عند حلها
• عندما يتم حظر الإصدارات بواسطة بوابة العمر، يكتشف فحص الاستقرار أنماط إصلاح الأخطاء السريعة
  • إذا تم نشر إصدارات متعددة معًا خارج بوابة العمر، يمتد المرشح لتخطي تلك الإصدارات غير المستقرة المحتملة ويحدد إصدارًا أقدم وأكثر نضجًا
  • يبحث حتى 7 أيام بعد بوابة العمر، ومع ذلك إذا كان لا يزال يجد إصدارات سريعة فإنه يتجاهل فحص الاستقرار
  • طلبات الإصدار الدقيقة (مثل package@1.1.1) لا تزال تحترم بوابة العمر لكن تتجاوز فحص الاستقرار
• الإصدارات بدون حقل time تُعامل على أنها تجتاز فحص العمر (يجب أن يوفر سجل npm دائمًا طوابع زمنية)

لمسح الأمان المتقدم، بما في ذلك التكامل مع الخدمات والتصفية المخصصة، راجع مدير الحزم > واجهة برمجة تطبيقات ماسح الأمان.

---

التكوين

تكوين bun install مع bunfig.toml

يتم البحث عن bunfig.toml في المسارات التالية على bun install و bun remove و bun add:

1. $XDG_CONFIG_HOME/.bunfig.toml أو $HOME/.bunfig.toml
2. ./bunfig.toml

إذا تم العثور على كليهما، يتم دمج النتائج معًا.

التكوين مع bunfig.toml اختياري. يحاول Bun أن يكون بدون تكوين بشكل عام، لكن هذا ليس ممكنًا دائمًا. يمكن تكوين السلوك الافتراضي لـ bun install في bunfig.toml. القيم الافتراضية موضحة أدناه.

[install]

# ما إذا كان سيتم تثبيت optionalDependencies
optional = true

# ما إذا كان سيتم تثبيت devDependencies
dev = true

# ما إذا كان سيتم تثبيت peerDependencies
peer = true

# يعادل العلامة `--production`
production = false

# يعادل العلامة `--save-text-lockfile`
saveTextLockfile = false

# يعادل العلامة `--frozen-lockfile`
frozenLockfile = false

# يعادل العلامة `--dry-run`
dryRun = false

# يعادل العلامة `--concurrent-scripts`
concurrentScripts = 16 # (عدد وحدات المعالجة المركزية أو GOMAXPROCS) ×2

# استراتيجية التثبيت: "hoisted" أو "isolated"
# الافتراضي يعتمد على configVersion لملف القفل ومساحات العمل:
# - configVersion = 1: "isolated" إذا كان يستخدم مساحات العمل، وإلا "hoisted"
# - configVersion = 0: "hoisted"
linker = "hoisted"


# تكوين الحد الأدنى للعمر
minimumReleaseAge = 259200 # ثواني
minimumReleaseAgeExcludes = ["@types/node", "typescript"]

التكوين بمتغيرات البيئة

لدى متغيرات البيئة أولوية أعلى من bunfig.toml.

الاسم	الوصف
BUN_CONFIG_REGISTRY	تعيين سجل npm (الافتراضي: https://registry.npmjs.org)
BUN_CONFIG_TOKEN	تعيين رمز مصادقة (لا يفعل شيئًا حاليًا)
BUN_CONFIG_YARN_LOCKFILE	حفظ yarn.lock بأسلوب Yarn v1
BUN_CONFIG_LINK_NATIVE_BINS	الإشارة إلى bin في package.json إلى تبعية خاصة بالمنصة
BUN_CONFIG_SKIP_SAVE_LOCKFILE	عدم حفظ ملف قفل
BUN_CONFIG_SKIP_LOAD_LOCKFILE	عدم تحميل ملف قفل
BUN_CONFIG_SKIP_INSTALL_PACKAGES	عدم تثبيت أي حزم

يحاول Bun دائمًا استخدام أسرع طريقة تثبيت متاحة للمنصة المستهدفة. على macOS، هذا clonefile وعلى Linux، هذا hardlink. يمكنك تغيير طريقة التثبيت المستخدمة باستخدام العلامة --backend. عند عدم التوفر أو عند حدوث خطأ، يعود clonefile و hardlink إلى تنفيذ خاص بالمنصة لنسخ الملفات.

يخزن Bun الحزم المثبتة من npm في ~/.bun/install/cache/${name}@${version}. لاحظ أنه إذا كان إصدار semver يحتوي على علامة build أو pre، يتم استبدالها بتجزئة من تلك القيمة بدلاً من ذلك. هذا لتقليل فرص الأخطاء من مسارات الملفات الطويلة، لكن للأسف يعقد معرفة مكان تثبيت الحزمة على القرص.

عندما يوجد مجلد node_modules، قبل التثبيت، يتحقق Bun مما إذا كان "name" و "version" في package/package.json في مجلد node_modules المتوقع يطابق الاسم والإصدار المتوقعين. هكذا يحدد ما إذا كان يجب التثبيت. يستخدم محلل JSON مخصص يتوقف عن التحليل بمجرد العثور على "name" و "version".

عندما لا يوجد bun.lock أو غيرت package.json التبعيات، يتم تنزيل واستخراج tarballs بحماس أثناء الحل.

عندما يوجد bun.lock ولم تتغير package.json، ينزل Bun التبعيات المفقودة بشكل كسول. إذا كانت الحزمة مع name و version متطابقة موجودة بالفعل في الموقع المتوقع داخل node_modules، فلن يحاول Bun تنزيل tarball.

CI/CD

استخدم إجراء oven-sh/setup-bun الرسمي لتثبيت bun في خط أنابيب GitHub Actions:

name: bun-types
jobs:
  build:
    name: build-app
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
      - name: Install bun
        uses: oven-sh/setup-bun@v2
      - name: Install dependencies
        run: bun install
      - name: Build app
        run: bun run build

لبيئات CI/CD التي تريد فرض عمليات بناء قابلة للتكرار، استخدم bun ci لفشل البناء إذا كان package.json غير متزامن مع ملف القفل:

bun ci

هذا يعادل bun install --frozen-lockfile. يقوم بتثبيت الإصدارات الدقيقة من bun.lock ويفشل إذا لم يتطابق package.json مع ملف القفل. لاستخدام bun ci أو bun install --frozen-lockfile، يجب التزامن bun.lock في التحكم في الإصدار.

وبدلاً من تشغيل bun install، قم بتشغيل bun ci.

name: bun-types
jobs:
  build:
    name: build-app
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
      - name: Install bun
        uses: oven-sh/setup-bun@v2
      - name: Install dependencies
        run: bun ci
      - name: Build app
        run: bun run build

تبعيات خاصة بالمنصة؟

يخزن Bun قيم cpu و os الطبيعية من npm في ملف القفل، جنبًا إلى جنب مع الحزم المحلولة. يتخطى تنزيل واستخراج وتثبيت الحزم المعطلة للهدف الحالي وقت التشغيل. هذا يعني أن ملف القفل لن يتغير بين المنصات/الهندسات المعمارية حتى لو تغيرت الحزم المثبتة في النهاية.

علامتا --cpu و --os

يمكنك تجاوز المنصة المستهدفة لاختيار الحزمة:

bun install --cpu=x64 --os=linux

هذا يثبت الحزم للمنصة المحددة بدلاً من النظام الحالي. مفيد لبناءات متعددة المنصات أو عند إعداد عمليات نشر لبيئات مختلفة.

القيم المقبولة لـ --cpu: arm64 و x64 و ia32 و ppc64 و s390x

القيم المقبولة لـ --os: linux و darwin و win32 و freebsd و openbsd و sunos و aix

تبعيات النظير؟

يتم التعامل مع تبعيات النظير بشكل مشابه لـ yarn. سيقوم bun install تلقائيًا بتثبيت تبعيات النظير. إذا تم تمييز التبعية كاختيارية في peerDependenciesMeta، سيتم اختيار تبعية موجودة إذا أمكن.

ملف القفل

bun.lock هو تنسيق ملف قفل Bun. راجع منشور المدونة الخاص بنا حول ملف القفل النصي.

قبل Bun 1.2، كان ملف القفل ثنائيًا ويسمى bun.lockb. يمكن ترقية ملفات القفل القديمة إلى التنسيق الجديد عن طريق تشغيل bun install --save-text-lockfile --frozen-lockfile --lockfile-only، ثم حذف bun.lockb.

الذاكرة المؤقتة

لحذف الذاكرة المؤقتة:

bun pm cache rm
# أو
rm -rf ~/.bun/install/cache

الخلفيات الخاصة بالمنصة

يستخدم bun install استدعاءات نظام مختلفة لتثبيت التبعيات اعتمادًا على المنصة. هذا تحسين للأداء. يمكنك فرض خلفية محددة باستخدام العلامة --backend.

hardlink هي الخلفية الافتراضية على Linux. أظهرت المعايرة أنها الأسرع على Linux.

rm -rf node_modules
bun install --backend hardlink

clonefile هي الخلفية الافتراضية على macOS. أظهرت المعايرة أنها الأسرع على macOS. وهي متاحة فقط على macOS.

rm -rf node_modules
bun install --backend clonefile

clonefile_each_dir مشابه لـ clonefile، باستثناء أنه ينسخ كل ملف بشكل فردي لكل دليل. وهو متاح فقط على macOS ويميل إلى الأداء الأبطأ من clonefile. على عكس clonefile، لا يستنسخ الأدلة الفرعية بشكل متكرر في استدعاء نظام واحد.

rm -rf node_modules
bun install --backend clonefile_each_dir

copyfile هو الاحتياط المستخدم عند فشل أي مما سبق، وهو الأبطأ. على macOS، يستخدم fcopyfile() وعلى Linux يستخدم copy_file_range().

rm -rf node_modules
bun install --backend copyfile

symlink يُستخدم عادةً فقط لتبعيات file: (وفي النهاية link:) داخليًا. لمنع الحلقات اللانهائية، يتخطى ربط مجلد node_modules.

إذا قمت بالتثبيت باستخدام --backend=symlink، فلن يحل Node.js مجلدات node_modules للتبعيات ما لم يكن لكل تبعية مجلد node_modules الخاص بها أو تمرر --preserve-symlinks إلى node أو bun. راجع توثيق Node.js حول --preserve-symlinks.

rm -rf node_modules
bun install --backend symlink
bun --preserve-symlinks ./my-file.js
node --preserve-symlinks ./my-file.js # https://nodejs.org/api/cli.html#--preserve-symlinks

بيانات وصفية لسجل npm

يستخدم Bun تنسيقًا ثنائيًا لتخزين استجابات سجل NPM مؤقتًا. يتم تحميل هذا بشكل أسرع بكثير من JSON ويميل إلى أن يكون أصغر على القرص. سترى هذه الملفات في ~/.bun/install/cache/*.npm. نمط اسم الملف هو ${hash(packageName)}.npm. إنها تجزئة حتى لا تحتاج إلى إنشاء أدلة إضافية للحزم ذات النطاق.

يتجاهل استخدام Bun لـ Cache-Control لـ Age. هذا يحسن الأداء، لكن يعني أن bun قد يكون قديمًا بحوالي 5 دقائق لتلقي أحدث بيانات وصفية لإصدار الحزمة من npm.

هجرة pnpm

يهاجر Bun تلقائيًا المشاريع من pnpm إلى bun. عند اكتشاف ملف pnpm-lock.yaml وعدم وجود ملف bun.lock، سيقوم Bun تلقائيًا بترحيل ملف القفل إلى bun.lock أثناء التثبيت. يظل ملف pnpm-lock.yaml الأصلي دون تعديل.

bun install

ملاحظة: تعمل الهجرة فقط عندما يكون bun.lock غائبًا. لا يوجد حاليًا علم opting out لهجرة pnpm.

تتعامل عملية الهجرة مع:

ترحيل ملف القفل

• يحول pnpm-lock.yaml إلى تنسيق bun.lock
• يحافظ على إصدارات الحزم ومعلومات الحل
• يحافظ على علاقات التبعيات وتبعيات النظير
• يتعامل مع التبعيات المصححة مع تجزئات النزاهة

تكوين مساحة العمل

عندما يوجد ملف pnpm-workspace.yaml، يهاجر Bun إعدادات مساحة العمل إلى package.json الجذر:

packages:
  - "apps/*"
  - "packages/*"

catalog:
  react: ^18.0.0
  typescript: ^5.0.0

catalogs:
  build:
    webpack: ^5.0.0
    babel: ^7.0.0

يتم نقل قائمة حزم مساحة العمل والكتالوجات إلى حقل workspaces في package.json:

{
  "workspaces": {
    "packages": ["apps/*", "packages/*"],
    "catalog": {
      "react": "^18.0.0",
      "typescript": "^5.0.0"
    },
    "catalogs": {
      "build": {
        "webpack": "^5.0.0",
        "babel": "^7.0.0"
      }
    }
  }
}

تبعيات الكتالوج

يتم الحفاظ على التبعيات التي تستخدم بروتوكول catalog: الخاص بـ pnpm:

{
  "dependencies": {
    "react": "catalog:",
    "webpack": "catalog:build"
  }
}

ترحيل التكوين

يتم ترحيل تكوين pnpm التالي من كل من pnpm-lock.yaml و pnpm-workspace.yaml:

• التجاوزات: يتم نقلها من pnpm.overrides إلى overrides على المستوى الجذر في package.json
• التبعيات المصححة: يتم نقلها من pnpm.patchedDependencies إلى patchedDependencies على المستوى الجذر في package.json
• تجاوزات مساحة العمل: يتم تطبيقها من pnpm-workspace.yaml إلى package.json الجذر

المتطلبات

• يتطلب إصدار ملف قفل pnpm 7 أو أعلى
• يجب أن تحتوي حزم مساحة العمل على حقل name في package.json الخاص بها
• Workspace packages must have a name field in their package.json
• All catalog entries referenced by dependencies must exist in the catalogs definition

After migration, you can safely remove pnpm-lock.yaml and pnpm-workspace.yaml files.

---