التثبيت وهيكل المشروع
تريد Alice تشغيل MegaShop محليًا لكنها مرتبكة بسبب اصطلاحات مجلدات Nuxt 3—إذا وُضعت الملفات في المكان الخطأ، لن تُستورد المكونات تلقائيًا. مشروع Bob فوضوي الإعداد، مما يسبب مشاكل مع كل بناء. يحتاج Charlie إلى هيكل مجلدات واضح لتوحيد تطوير الفريق.
1. ما ستتعلمه
- npx nuxi@latest init: إنشاء مشروع واختيار مدير حزم
- اصطلاحات المجلدات الأساسية: pages/components/composables/server وغيرها
- شرح مفصل لـ nuxt.config.ts
- كيف يعمل الاستيراد التلقائي
- دليل عملي لتهيئة مشروع MegaShop
2. قصة حقيقية لمطور
(1) نقطة الألم: هيكل مجلدات فوضوي يجعل المكونات "تختفي"
وضعت Alice ملف ProductCard.vue تحت src/components/shop/، مما أدى إلى خطأ على الصفحة: "Component ProductCard is not found." لم تكن تعرف اصطلاحات مجلدات Nuxt 3—مسار المكون يحدد اسم المكون. يجب الإشارة إلى components/shop/ProductCard.vue كـ `<ShopProductCard />`. هذه القاعدة الضمنية تربك المبتدئين كثيرًا.
(2) حل لاصطلاح مجلدات Nuxt 3
يستخدم Nuxt 3 اصطلاحات المجلدات بدلاً من الإعداد اليدوي—الملفات تصبح متاحة تلقائيًا عند وضعها في المجلد الصحيح، دون الحاجة لعبارات import. بمجرد فهمها للاصطلاحات، تحتاج Alice فقط لترتيب ملفاتها وفقًا للقواعد:
components/
ProductCard.vue → <ProductCard />
shop/
ProductList.vue → <ShopProductList />
(3) الفوائد: مضاعفة كفاءة التطوير
بمجرد أن فهم الفريق اصطلاحات المجلدات، لم تعد مكونات Alice "تختفي"، وانخفض الوقت اللازم لأعضاء الفريق الجدد للبدء من يومين إلى 4 ساعات.
3. إنشاء مشروع Nuxt 3
(1) أمر التهيئة
# إنشاء مشروع Nuxt 3 جديد
npx nuxi@latest init megashop
# أو مع مدير حزم محدد
npx nuxi@latest init megashop --packageManager pnpm
(2) مقارنة مديري الحزم
| البُعد | npm | pnpm | yarn |
|---|---|---|---|
| سرعة التثبيت | 🐢 بطيء | ⚡ الأسرع | ⚡ سريع |
| استخدام القرص | 🔴 عالي | 🟢 منخفض (روابط صلبة) | 🟡 متوسط |
| Monorepo | ⚠️ يتطلب workspaces | ✅ دعم أصلي | ✅ مدعوم |
| التقييم | ⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ |
(1) ▶ مثال: التهيئة والتشغيل
# الخطوة 1: إنشاء المشروع
npx nuxi@latest init megashop
# الخطوة 2: الدخول إلى مجلد المشروع
cd megashop
# الخطوة 3: تثبيت التبعيات
npm install
# الخطوة 4: تشغيل خادم التطوير
npm run dev
# → Nuxt dev server running at http://localhost:3000
الناتج:
# Command executed successfully
(2) ▶ مثال: السكربتات الأساسية في package.json
{
"name": "megashop",
"private": true,
"scripts": {
"build": "nuxi build",
"dev": "nuxi dev",
"generate": "nuxi generate",
"preview": "nuxi preview",
"postinstall": "nuxi prepare"
},
"dependencies": {
"nuxt": "^3.12.0"
},
"devDependencies": {
"@nuxt/devtools": "latest"
}
}
الناتج:
{
"name": "megashop",
"private": true,
"scripts": {
"build": "nuxi build",
"dev": "nuxi dev",
"generate": "nuxi generate",
"preview": "nuxi preview",
"postinstall": "nuxi prepare"
},
"dependencies": {
"nuxt": "^3.12.0"
},
"devDependencies": {
"@nuxt/devtools": "latest"
}
}
4. اصطلاحات المجلدات الأساسية
(1) نظرة عامة على هيكل المجلدات
graph TB
A[megashop/] --> B[pages/ → المسارات]
A --> C[components/ → استيراد تلقائي للمكونات]
A --> D[composables/ → استيراد تلقائي للدوال]
A --> E[server/ → مسارات API]
A --> F[layouts/ → تخطيطات الصفحة]
A --> G[plugins/ → تسجيل تلقائي للإضافات]
A --> H[middleware/ → حراس المسارات]
A --> I[assets/ → معالجة البناء]
A --> J[public/ → ملفات ثابتة]
A --> K[nuxt.config.ts → إعداد المشروع]
A --> L[app.vue → المكون الجذري]
(2) مسؤوليات وقواعد كل مجلد
| المجلد | المسؤوليات | التسجيل التلقائي | استخدامات MegaShop |
|---|---|---|---|
| pages/ | صفحات المسارات | ✅ توليد تلقائي للمسارات | صفحات المنتجات/صفحات الفئات/الصفحة الرئيسية |
| components/ | مكونات Vue | ✅ استيراد تلقائي | ProductCard/Header/Footer |
| composables/ | دوال composable | ✅ استيراد تلقائي | useCart/useProduct |
| server/api/ | مسارات API | ✅ تسجيل تلقائي | /api/products /api/cart |
| server/middleware/ | وسائط جانب الخادم | ✅ تُطبّق عالميًا | auth/CORS |
| layouts/ | تخطيط الصفحة | ✅ تسجيل تلقائي | default/sidebar |
| plugins/ | إضافات | ✅ تلقائي | stripe/payment |
| middleware/ | وسائط التوجيه | ✅ يمكن الإشارة إليها | auth/admin |
| assets/ | بناء ومعالجة الموارد | ❌ يتطلب إشارة | CSS/خطوط/SCSS |
| public/ | ملفات ثابتة | ❁ وصول مباشر | favicon/robots.txt |
(1) ▶ مثال: هيكل مجلدات MegaShop
megashop/
├── app.vue # المكون الجذري
├── nuxt.config.ts # إعداد المشروع
├── pages/
│ ├── index.vue # الصفحة الرئيسية
│ ├── products/
│ │ ├── index.vue # قائمة المنتجات
│ │ └── [id].vue # تفاصيل المنتج
│ ├── categories/
│ │ └── [slug].vue # صفحة الفئة
│ ├── cart.vue # سلة التسوق
│ └── about.vue # صفحة حول
├── components/
│ ├── AppHeader.vue # → <AppHeader />
│ ├── AppFooter.vue # → <AppFooter />
│ └── product/
│ ├── ProductCard.vue # → <ProductProductCard /> ①
│ └── ProductList.vue # → <ProductProductList /> ①
├── composables/
│ ├── useCart.ts # → مستورد تلقائيًا
│ └── usePriceFormat.ts # → مستورد تلقائيًا
├── server/
│ └── api/
│ ├── products/
│ │ └── index.get.ts # GET /api/products
│ └── cart/
│ └── index.post.ts # POST /api/cart
├── layouts/
│ ├── default.vue # التخطيط الافتراضي
│ └── sidebar.vue # تخطيط الشريط الجانبي
├── middleware/
│ └── auth.ts # وسيط مسمى
├── plugins/
│ └── stripe.client.ts # إضافة من جانب العميل فقط
├── assets/
│ └── css/
│ └── main.css # أنماط عامة
└── public/
├── favicon.ico
└── robots.txt
الناتج:
Execution Successful
components/product/ProductCard.vue هي Product، أي <ProductProductCard />. يمكنك تعطيل البادئة بإعداد pathPrefix في nuxt.config.ts.
5. شرح مفصل لـ nuxt.config.ts
(1) خيارات الإعداد الأساسية
| الخيار | النوع | الوصف | مثال MegaShop |
|---|---|---|---|
| ssr | boolean | مفتاح SSR العام | true |
| modules | array | قائمة الوحدات | @pinia/nuxt |
| runtimeConfig | object | إعداد وقت التشغيل | مفتاح API/رابط قاعدة البيانات |
| app | object | بيانات التطبيق | head/title/templateId |
| vite | object | إعداد Vite | وكلاء/إضافات |
| routeRules | object | سياسة التصيير على مستوى المسار | ISR/CSR/Cache |
| components | object | إعداد استيراد المكونات | بادئة/مسار المسح |
(1) ▶ مثال: الإعداد الأساسي لـ MegaShop
// nuxt.config.ts
export default defineNuxtConfig({
# إعداد SSR العام
ssr: true,
# بيانات التطبيق
app: {
head: {
title: 'MegaShop - Premium E-Commerce',
meta: [
{ name: 'description', content: 'Millions of products, shipped worldwide' }
]
}
},
# إعداد وقت التشغيل (أسرار جانب الخادم فقط)
runtimeConfig: {
# خاص - جانب الخادم فقط
databaseUrl: process.env.DATABASE_URL,
stripeSecretKey: process.env.STRIPE_SECRET_KEY,
# عام - مكشوف للعميل
public: {
apiBase: process.env.API_BASE || 'http://localhost:3000/api',
stripePublishableKey: process.env.STRIPE_PUBLISHABLE_KEY
}
},
# الوحدات
modules: [
'@pinia/nuxt',
'@nuxtjs/tailwindcss'
],
# إعداد بادئة مسار المكونات
components: [
{ path: '~/components', pathPrefix: false }
]
})
الناتج:
// Execution Successful
(2) ▶ مثال: استراتيجية التصيير routeRules
// nuxt.config.ts - قواعد التصيير على مستوى المسار
export default defineNuxtConfig({
routeRules: {
# الصفحة الرئيسية: تصيير مسبق وقت البناء
'/': { prerender: true },
# قائمة المنتجات: ISR مع إعادة تحقق كل 60 ثانية
'/products': { swr: 60 },
# تفاصيل المنتج: ISR مع إعادة تحقق كل 3600 ثانية
'/products/**': { swr: 3600 },
# لوحة الإدارة: جانب العميل فقط
'/admin/**': { ssr: false },
# API: ترويسات CORS
'/api/**': { cors: true }
}
})
الناتج:
// Execution Successful
6. كيف تعمل آلية الاستيراد التلقائي
(1) عملية التسجيل التلقائي
flowchart LR
A[Nuxt Scan Directories] --> B[Generate .nuxt/imports.d.ts]
B --> C[Generate .nuxt/components.d.ts]
C --> D[TypeScript Auto-complete]
A --> E[Generate .nuxt/routes.ts]
E --> F[Vue Router Config]
(2) نطاق الاستيراد التلقائي
| النوع | المجلد | قاعدة البادئة | مثال |
|---|---|---|---|
| مكون | components/ | بادئة مسار المجلد | ProductCard → <ProductCard /> |
| Composable | composables/ | بادئة use | useCart() → مستورد تلقائيًا |
| دوال مساعدة | utils/ | بدون بادئة | formatPrice() → مستورد تلقائيًا |
| APIs مدمجة | نواة Nuxt 3 | بادئة "use" | useFetch/useState/useRouter |
(1) ▶ مثال: الاستيراد التلقائي لـ Composables
// composables/usePriceFormat.ts
// لا حاجة للاستيراد - مستورد تلقائيًا بواسطة Nuxt
export function usePriceFormat(price: number, currency: string = 'USD'): string {
return new Intl.NumberFormat('en-US', {
style: 'currency',
currency
}).format(price)
}
// في أي مكون - استخدم مباشرة
// const formatted = usePriceFormat(2999.99) → "$2,999.99"
الناتج:
// Execution Successful
(2) ▶ مثال: التحقق من الاستيراد التلقائي للمكونات
<!-- pages/index.vue -->
<template>
<!-- جميع المكونات مستوردة تلقائيًا، لا حاجة لعبارات import -->
<div>
<AppHeader />
<ProductCard :product="featured" />
<AppFooter />
</div>
</template>
<script setup lang="ts">
// جميع Composables مستوردة تلقائيًا
const { data: featured } = await useFetch('/api/products/featured')
const price = usePriceFormat(featured.value?.price || 0)
</script>
الناتج:
// Execution Successful
7. مثال شامل: تهيئة مشروع MegaShop
# ============================================
# تهيئة مشروع MegaShop
# إعداد كامل من الصفر إلى تشغيل خادم التطوير
# ============================================
# 1. إنشاء المشروع
npx nuxi@latest init megashop
cd megashop
# 2. تثبيت التبعيات الأساسية
npm install @pinia/nuxt @nuxtjs/tailwindcss
# 3. إنشاء هيكل المجلدات
mkdir -p pages/products pages/categories
mkdir -p components/product
mkdir -p composables
mkdir -p server/api/products server/api/cart
mkdir -p layouts
mkdir -p middleware
mkdir -p plugins
mkdir -p assets/css
mkdir -p public
# 4. تهيئة مستودع Git
git init
git add .
git commit -m "feat: initialize MegaShop with Nuxt 3"
# 5. تشغيل خادم التطوير
npm run dev
❓ أسئلة شائعة
components على بادئة؟components/product/Card.vue هو <ProductCard />. يمكنك تعطيل ذلك بتعيين components: [{ path: '~/components', pathPrefix: false }] في nuxt.config.ts.runtimeConfig؟public.app.vue و pages/ التعايش؟app.vue العنصر <NuxtPage /> لعرض الصفحة. إذا لم يوجد مجلد pages/، فإن app.vue هو الصفحة الوحيدة.assets و public؟assets/ تُبنى بواسطة Vite (يمكن الإشارة إليها وتحسينها وتجزئتها)، بينما الملفات في public/ تُنسخ كما هي إلى مجلد المخرجات ويمكن الوصول إليها مباشرة عبر URL.nuxi prepare أو npm run dev.📖ملخص
- استخدم
npx nuxi@latest initلإنشاء مشروع؛ يُوصى باستخدام pnpm كمدير حزم - مجلدات Nuxt 3 الأساسية: pages (المسارات)، components (المكونات)، composables (الدوال)، server (API)، layouts (التخطيطات)
nuxt.config.tsهو الإعداد الأساسي للمشروع:runtimeConfigيدير الأسرار، وrouteRulesيدير استراتيجيات التصيير- الاستيراد التلقائي يلغي الحاجة لاستيراد المكونات و Composables والدوال المساعدة يدويًا
- يجب أن يتبع هيكل مجلدات MegaShop الاصطلاحات لضمان وضع جميع الملفات في الأماكن الصحيحة
📝تمارين
- تمرين أساسي (الصعوبة: ⭐): أنشئ مشروعًا باستخدام
nuxi init، وارسم شجرة المجلدات لمشروعك. - تمرين متقدم (الصعوبة: ⭐⭐): أنشئ مكونًا بمجلدات فرعية من مستويين تحت
components/للتحقق من اصطلاحات التسمية المستخدمة أثناء الاستيراد التلقائي (مثلاً: ما هو اسم الوسم لـcomponents/shop/product/Card.vue؟). - تحدٍ (الصعوبة: ⭐⭐⭐): إعداد
routeRulesفيnuxt.config.tsبحيث تُصيّر الصفحة الرئيسية مسبقًا، وتستخدم صفحة المنتج ISR لمدة 60 ثانية، وتستخدم صفحة الإدارة CSR، ثم تحقق من عملها كما هو متوقع.
---|



