Rolldown مع Vite 8: الانتقال إلى المُجمِّع المبني على Rust في 2026

ماذا ستتعلّم

بنهاية هذا الدليل ستعرف كيف:

• تفهم ما هو Rolldown ولماذا وحّدت Vite اعتمادها على مُجمِّع Rust واحد
• تختار بين المسار التدريجي (rolldown-vite على Vite 7) والمسار المباشر (Vite 8)
• تعيد توجيه حزمة vite وتُعدّ تجاوزات مدير الحزم للاعتماديات المتداخلة
• تُحدّث الإعدادات المهجورة مثل manualChunks إلى واجهة advancedChunks الجديدة
• تضبط محرّك الإضافات الأصلية عبر experimental.enableNativePlugin
• تُحسّن أداء الإضافات الخارجية باستخدام المساعد withFilter
• تُشخّص وتُصلح أكثر أعطال الترحيل شيوعاً
• تتحقّق من المكاسب في السرعة وتقيسها داخل مشروعك

المتطلبات المسبقة

قبل البدء، تأكّد من توفّر:

• Node.js 20.19+ أو 22.12+ (الحدّ الأدنى لـ Vite 8)
• مشروع Vite 6 أو 7 قائم، أو استعداد لإنشاء مشروع جديد
• إلمام بملفّ package.json ومدير الحزم لديك وملفّ vite.config.ts
• مدير حزم: pnpm (موصى به) أو npm أو Yarn أو Bun
• فهم أساسي لمفاهيم التجميع (الأجزاء chunks، وهزّ الشجرة tree-shaking، وHMR)

لماذا Rolldown؟

طوال معظم عمرها، اعتمدت Vite على مُجمِّعَين. خلال التطوير كانت تستخدم esbuild للتحزيم المسبق للاعتماديات والتحويلات، وفي بناء الإنتاج كانت تستخدم Rollup. تسبّب هذا الانقسام في تباينات خفيّة بين التطوير والبناء، وعنى أنّ الفريق يحافظ على التوافق مع أداتين مختلفتين تماماً.

يُنهي Rolldown هذا الانقسام. فهو مُجمِّع وحيد مبني على Rust — طوّره فريق Vite نفسه فوق سلسلة أدوات Oxc — مُصمَّم ليكون متوافقاً مع Rollup مع العمل بسرعة المحرّكات الأصلية. تُطلقه Vite 8 كخيار افتراضي، إلى جانب Oxc لتحويلات جافاسكريبت وJSX وLightning CSS لتصغير ملفّات الأنماط. أصبح المسار الحرج بأكمله مكتوباً بلغة Rust.

والعائد هو السرعة والاتساق:

مساران للترحيل

هناك طريقتان للانتقال إلى Rolldown، والصحيحة منهما تعتمد على حجم مشروعك:

1. الترقية المباشرة إلى Vite 8 — الأفضل للتطبيقات الصغيرة والمتوسطة والمشاريع الجديدة. تتولّى طبقة توافق تحويل معظم إعدادات esbuild وRollup القائمة تلقائياً، فتُرقَّى مشاريع كثيرة دون أيّ تعديل في الإعدادات.
2. الترحيل التدريجي عبر rolldown-vite على Vite 7 — الأفضل لقواعد الشيفرة الكبيرة أو الغنية بالإضافات. تبقى على سلوك Vite 7 لكنّك تبدّل المُجمِّع إلى Rolldown، ما يعزل المشكلات الخاصّة بـ Rolldown قبل أن تستوعب كذلك بقيّة تغييرات Vite 8.

سنتناول كلا المسارين. ابدأ بالمسار الذي يلائم مدى تحمّلك للمخاطرة.

الخطوة 1: تأكّد من إصدار Node.js

تتطلّب Vite 8 الإصدار Node.js 20.19+ أو 22.12+. تحقّق أوّلاً:

node --version
# يجب أن يُطبع v20.19.x أو أعلى، أو v22.12.x أو أعلى

إذا كنت تستخدم nvm، فبدّل وثبّت:

nvm install 22
nvm use 22

إصدار Node القديم هو السبب الأكثر شيوعاً لفشل تثبيت Vite 8، لذا عالج هذا قبل المساس بالاعتماديات.

الخطوة 2 (المسار أ): الترحيل التدريجي عبر rolldown-vite على Vite 7

يُبقيك هذا المسار على Vite 7 مع تبديل مُجمِّع Rust. الحيلة هي إعادة توجيه حزمة vite إلى rolldown-vite داخل package.json:

{
  "devDependencies": {
    "vite": "npm:rolldown-vite@7.1.0"
  }
}

إذا كانت Vite اعتمادية نظيرة (peer dependency) لحزم أخرى (وهذا شائع في المستودعات الأحادية والتطبيقات الغنية بالإضافات)، فلن تكفي إعادة التوجيه وحدها — عليك تجاوز التحليل المتداخل أيضاً. استخدم الصياغة الخاصّة بمدير الحزم لديك:

npm:

{
  "overrides": {
    "vite": "npm:rolldown-vite@7.1.0"
  }
}

pnpm:

{
  "pnpm": {
    "overrides": {
      "vite": "npm:rolldown-vite@7.1.0"
    }
  }
}

Yarn:

{
  "resolutions": {
    "vite": "npm:rolldown-vite@7.1.0"
  }
}

Bun:

{
  "overrides": {
    "vite": "npm:rolldown-vite@7.1.0"
  }
}

ثمّ أعد التثبيت وشغّل البناء:

pnpm install
pnpm run build

تبقى السكربتات وملفّ الإعداد والإضافات كما هي. إذا نجح البناء وتصرّف تطبيقك بصورة مطابقة، فقد تحقّقت من Rolldown مقابل قاعدة شيفرتك. الآن يمكنك الانتقال إلى Vite 8 بثقة.

الخطوة 2 (المسار ب): الترقية المباشرة إلى Vite 8

لمشروع جديد، أنشئ مباشرةً:

pnpm create vite@latest my-app
cd my-app
pnpm install
pnpm run dev

يستهدف المشروع المُولَّد Vite 8 بالفعل مع Rolldown كخيار افتراضي — لا شيء إضافي لتفعيله.

ولترقية مشروع قائم، ارفع إصدار Vite وإضافة إطار العمل لديك:

pnpm add -D vite@8
# إضافة إطار العمل، على سبيل المثال:
pnpm add -D @vitejs/plugin-react@latest

أزل أيّ إعادة توجيه متبقّية لـ vite من المسار أ (سطر npm:rolldown-vite@...) قبل الترقية، كي تُثبّت حزمة Vite 8 الحقيقية بدلاً من خطّ المعاينة المستقلّ.

شغّل البناء وراقب التوقيت:

pnpm run build

بفضل طبقة التوافق المدمجة، تحوّل Vite 8 تلقائياً معظم إعدادات esbuild وrollupOptions القائمة إلى مكافئاتها في Rolldown وOxc. لا تحتاج نسبة كبيرة من المشاريع إلى أيّ تعديل في الإعدادات على الإطلاق.

الخطوة 3: حدِّث الإعدادات المهجورة

أكثر تغييرات الإعداد شيوعاً هو التقسيم اليدوي للأجزاء. تُستبدل دالّة manualChunks من Rollup بواجهة advancedChunks التصريحية في Rolldown:

// قبل — أسلوب Rollup
export default {
  build: {
    rollupOptions: {
      output: {
        manualChunks(id) {
          if (/\/react(?:-dom)?/.test(id)) {
            return 'vendor'
          }
        }
      }
    }
  }
}

// بعد — أسلوب Rolldown
export default {
  build: {
    rollupOptions: {
      output: {
        advancedChunks: {
          groups: [
            { name: 'vendor', test: /\/react(?:-dom)?/ }
          ]
        }
      }
    }
  }
}

الواجهة الجديدة تصريحية: لكلّ مجموعة اسم name ونمط test. هي أيسر في الفهم وتتيح لـ Rolldown تخطيط الأجزاء مسبقاً بدل العودة إلى جافاسكريبت عند كلّ وحدة.

إذا كنت تستورد مساعد التحويل من esbuild مباشرةً، فلاحظ أنّ transformWithEsbuild صار مهجوراً. استخدم بدلاً منه المكافئ المبني على Oxc وهو transformWithOxc.

الخطوة 4: اضبط محرّك الإضافات الأصلية

أكبر رافعة سرعة في Vite 8 هي الإضافات الأصلية — إضافات Rolldown المدمجة التي تُنفَّذ بالكامل داخل Rust، دون عبور حدود جافاسكريبت. يتحكّم في ذلك experimental.enableNativePlugin، وقيمته الافتراضية 'v2' في Vite 8:

// vite.config.ts
import { defineConfig } from 'vite'
 
export default defineConfig({
  experimental: {
    // 'v2' هو الافتراضي في Vite 8 — إضافات أصلية كاملة
    enableNativePlugin: 'v2',
  },
})

إذا أساءت إحدى الإضافات التصرّف في الوضع الأصلي، يمكنك خفض درجة المحرّك كحلّ مؤقّت:

• 'v2' — إضافات أصلية كاملة (افتراضي)
• 'v1' — مجموعة الإضافات الأصلية الأقدم
• 'resolver' — يُعطّل بعض الإضافات الأصلية
• false — يُعطّل جميع الإضافات الأصلية، وهو الأقرب للسلوك القديم

عامِل أيّ قيمة أدنى من 'v2' كخطوة تشخيصية لا كوجهة نهائية. أبلِغ عن المشكلة الأساسية واستعد القيمة الافتراضية بعد إصلاحها.

الخطوة 5: حسّن الإضافات الخارجية باستخدام withFilter

الإضافات التي تُشغّل خطّاف transform أو load على كلّ وحدة تفرض ذهاباً وإياباً عبر حدود Rust إلى جافاسكريبت حتى للملفّات التي لا تعنيها. يقصُر المساعد withFilter الإضافة على الملفّات التي ينبغي أن تمسّها فقط، ما يُلغي ذلك العبء:

import { defineConfig, withFilter } from 'vite'
import svgr from 'vite-plugin-svgr'
 
export default defineConfig({
  plugins: [
    withFilter(
      svgr({ /* الخيارات */ }),
      { load: { id: /\.svg\?react$/ } },
    ),
  ],
})

هنا تعمل svgr فقط للاستيرادات المنتهية بـ .svg?react. كلّ ما عداها يبقى داخل Rust. في قواعد الشيفرة الكبيرة قد يقتطع هذا وحده ثوانٍ من زمن البناء.

الخطوة 6: عالِج شؤون مطوّري الإضافات

إذا كنت تتولّى صيانة إضافة Vite خاصّة بك، فهناك تفصيلان مهمّان في ظلّ Rolldown.

أوّلاً، حين يُرجع خطّاف load أو transform شيفرةً ينبغي معاملتها كجافاسكريبت، صرّح بنوع الوحدة بوضوح:

import fs from 'node:fs/promises'
 
const plugin = {
  name: 'txt-loader',
  async load(id) {
    if (id.endsWith('.txt')) {
      const content = await fs.readFile(id, 'utf-8')
      return {
        code: `export default ${JSON.stringify(content)}`,
        moduleType: 'js',
      }
    }
  },
}

ثانياً، يمكنك اكتشاف ما إذا كانت إضافتك تعمل في ظلّ Rolldown لتفرّع السلوك بأمان:

const plugin = {
  name: 'my-plugin',
  resolveId() {
    if (this.meta.rolldownVersion) {
      // مسار خاصّ بـ Rolldown
    } else {
      // مسار Rollup الكلاسيكي
    }
  },
}

أو افحص الصادر على المستوى الأعلى:

import * as vite from 'vite'
 
if (vite.rolldownVersion) {
  // شيفرة خاصّة بـ rolldown-vite
}

الخطوة 7: تحقّق وقِس

لا يكتمل الترحيل قبل أن تقيس النتيجة. قِس زمن بناء إنتاج نظيف قبل وبعد:

# بناء نظيف مع توقيت
rm -rf dist
time pnpm run build

ثمّ شغّل تطبيقك من مُخرَجات الإنتاج وتنقّل عبر المسارات الحرجة:

pnpm run preview

تحقّق من ثلاثة أمور تحديداً:

1. صحّة البناء — كلّ مسار يُعرَض، والأصول تُحمَّل، ولا استيرادات معطوبة.
2. توزيع الأجزاء — افتح dist/assets وتأكّد أنّ مجموعات advancedChunks أنتجت تقسيمات vendor المتوقّعة.
3. إحساس HMR — شغّل pnpm run dev، وعدّل مكوّناً، وتأكّد أنّ التحديث يصل فورياً تقريباً.

إذا لم تطابق أرقامك القياسات الدراماتيكية فهذا طبيعي — تتناسب المكاسب مع حجم المشروع وعدد الوحدات. حتى التطبيق المتواضع ينبغي أن يشهد تحسّناً واضحاً.

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

يفشل البناء بخطأ في إضافة. اخفض enableNativePlugin إلى 'v1' ثمّ 'resolver' ثمّ false لعزل ما إذا كانت إضافة أصلية هي السبب. أبلِغ عن المشكلة في مستودع vitejs/rolldown-vite مع نموذج إعادة إنتاج مصغّر.

اختفاء CSS في الإنتاج. بعض الإضافات تتفاعل بصورة سيّئة مع خطّ أنابيب CSS الأصلي. تأكّد أنّ Lightning CSS يتولّى أنماطك وجرّب تعطيل الإضافات الأصلية مؤقّتاً لتحديد المصدر.

اعتمادية نظيرة ما زالت تجلب Vite الكلاسيكية. لم يُطبَّق تجاوزك. تحقّق من استخدامك المفتاح الصحيح لمدير الحزم لديك (overrides أو pnpm.overrides أو resolutions) وأعد التثبيت من ملفّ قفل نظيف.

transformWithEsbuild غير معرّف. صار مهجوراً في ظلّ Rolldown. انتقل إلى transformWithOxc، أو أضف esbuild كاعتمادية صريحة إن كنت لا تزال تحتاجها فعلاً.

قفز حجم التثبيت. أمرٌ متوقّع — يضيف Rolldown وLightning CSS نحو 15 ميغابايت. هذا ليس خطأً في الإعداد.

الخطوات التالية

• اطّلع على دليل أساسيات Vite 6 لترسيخ معرفتك بالإعداد قبل الترحيل.
• قارن مقاربات التجميع عبر درس Rspack وRsbuild — خيار آخر مبني على Rust.
• أعدّ اختبارات وحدة سريعة مع Vitest وReact Testing Library، التي تشارك خطّ تحويل Vite.
• بعد أن تصبح عمليات البناء سريعة، أعد النظر في خطّ CI لديك للاستفادة من أزمنة البناء الأقصر.

الخاتمة

انتقال Vite 8 إلى Rolldown هو أهمّ تغيير في المشروع منذ الإصدار 2، وقد جاء دون أن يطلب الكثير من معظم الفِرَق. تستوعب طبقة التوافق الجزء الأكبر من العمل، فلا يبقى أمامك سوى قائمة قصيرة: تأكيد Node 20.19+/22.12+، والتحقّق اختيارياً عبر rolldown-vite على Vite 7، وترحيل manualChunks إلى advancedChunks، وحصر الإضافات الثقيلة بـ withFilter، ثمّ القياس.

والمكافأة خطّ بناء موحّد، مكتوب بلغة Rust، وغالباً أسرع بمرتبة قدرية كاملة. وبالنسبة لفِرَق منطقة الشرق الأوسط وشمال إفريقيا التي تشحن ضمن ميزانيات CI ضيّقة وظروف شبكة بطيئة، فإنّ تقليص بناء يستغرق ست دقائق إلى أقلّ من عشرين ثانية ليس ترفاً — بل هو وقتٌ مُستردّ للمطوّر في كلّ دفعة شيفرة.