404 Not Found

404 Not Found


nginx

التثبيت وهيكل المشروع

تريد Alice تشغيل MegaShop محليًا لكنها مرتبكة بسبب اصطلاحات مجلدات Nuxt 3—إذا وُضعت الملفات في المكان الخطأ، لن تُستورد المكونات تلقائيًا. مشروع Bob فوضوي الإعداد، مما يسبب مشاكل مع كل بناء. يحتاج Charlie إلى هيكل مجلدات واضح لتوحيد تطوير الفريق.

1. ما ستتعلمه


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 فقط لترتيب ملفاتها وفقًا للقواعد:

TEXT
components/
  ProductCard.vue     → <ProductCard />
  shop/
    ProductList.vue   → <ShopProductList />

(3) الفوائد: مضاعفة كفاءة التطوير

بمجرد أن فهم الفريق اصطلاحات المجلدات، لم تعد مكونات Alice "تختفي"، وانخفض الوقت اللازم لأعضاء الفريق الجدد للبدء من يومين إلى 4 ساعات.


3. إنشاء مشروع Nuxt 3

(1) أمر التهيئة

BASH
# إنشاء مشروع Nuxt 3 جديد
npx nuxi@latest init megashop

# أو مع مدير حزم محدد
npx nuxi@latest init megashop --packageManager pnpm

(2) مقارنة مديري الحزم

البُعد npm pnpm yarn
سرعة التثبيت 🐢 بطيء ⚡ الأسرع ⚡ سريع
استخدام القرص 🔴 عالي 🟢 منخفض (روابط صلبة) 🟡 متوسط
Monorepo ⚠️ يتطلب workspaces ✅ دعم أصلي ✅ مدعوم
التقييم ⭐⭐ ⭐⭐⭐ ⭐⭐⭐

(1) ▶ مثال: التهيئة والتشغيل

BASH
# الخطوة 1: إنشاء المشروع
npx nuxi@latest init megashop

# الخطوة 2: الدخول إلى مجلد المشروع
cd megashop

# الخطوة 3: تثبيت التبعيات
npm install

# الخطوة 4: تشغيل خادم التطوير
npm run dev
# → Nuxt dev server running at http://localhost:3000

الناتج:

TEXT
# Command executed successfully

(2) ▶ مثال: السكربتات الأساسية في package.json

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"
  }
}

الناتج:

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"
  }
}

4. اصطلاحات المجلدات الأساسية

(1) نظرة عامة على هيكل المجلدات

100%
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

TEXT
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

الناتج:

TEXT
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

TYPESCRIPT
// 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 }
  ]
})

الناتج:

TEXT
// Execution Successful

(2) ▶ مثال: استراتيجية التصيير routeRules

TYPESCRIPT
// 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 }
  }
})

الناتج:

TEXT
// Execution Successful

6. كيف تعمل آلية الاستيراد التلقائي

(1) عملية التسجيل التلقائي

100%
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

TYPESCRIPT
// 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"

الناتج:

TEXT
// Execution Successful

(2) ▶ مثال: التحقق من الاستيراد التلقائي للمكونات

VUE
<!-- 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>

الناتج:

TEXT
// Execution Successful

7. مثال شامل: تهيئة مشروع MegaShop

BASH
# ============================================
# تهيئة مشروع 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 على بادئة؟
ج افتراضيًا، يستخدم Nuxt 3 مسار المجلد كبادئة، لذا يصبح components/product/Card.vue هو <ProductCard />. يمكنك تعطيل ذلك بتعيين components: [{ path: '~/components', pathPrefix: false }] في nuxt.config.ts.
س ما الفرق بين الحقول العامة والخاصة في runtimeConfig؟
ج الحقول الخاصة متاحة فقط على جانب الخادم (مفتاح API/كلمة مرور قاعدة البيانات)، بينما الحقول العامة مكشوفة للعميل. لا تخزّن المفاتيح أبدًا في قسم public.
س هل يمكن لـ app.vue و pages/ التعايش؟
ج نعم، لكن يجب أن يتضمن app.vue العنصر <NuxtPage /> لعرض الصفحة. إذا لم يوجد مجلد pages/، فإن app.vue هو الصفحة الوحيدة.
س ما الفرق بين assets و public؟
ج الملفات في assets/ تُبنى بواسطة Vite (يمكن الإشارة إليها وتحسينها وتجزئتها)، بينما الملفات في public/ تُنسخ كما هي إلى مجلد المخرجات ويمكن الوصول إليها مباشرة عبر URL.
س هل يجب إضافة مجلد .nuxt إلى Git؟
ج لا. مجلد .nuxt هو مجلد مؤقت يُولّد تلقائيًا بواسطة Nuxt ومضمّن بالفعل في .gitignore. سيُعاد توليده تلقائيًا عند تشغيل nuxi prepare أو npm run dev.
س هل يدعم Nuxt 3 هيكل مجلد src؟
ج نعم، يدعم ذلك. يمكنك وضع مجلدات مثل pages/ و components/ تحت src/، وسيتعرف عليها Nuxt 3 تلقائيًا. يمكنك أيضًا تخصيص ذلك باستخدام خيار dir في nuxt.config.ts.

📖ملخص


📝تمارين

  1. تمرين أساسي (الصعوبة: ⭐): أنشئ مشروعًا باستخدام nuxi init، وارسم شجرة المجلدات لمشروعك.
  2. تمرين متقدم (الصعوبة: ⭐⭐): أنشئ مكونًا بمجلدات فرعية من مستويين تحت components/ للتحقق من اصطلاحات التسمية المستخدمة أثناء الاستيراد التلقائي (مثلاً: ما هو اسم الوسم لـ components/shop/product/Card.vue؟).
  3. تحدٍ (الصعوبة: ⭐⭐⭐): إعداد routeRules في nuxt.config.ts بحيث تُصيّر الصفحة الرئيسية مسبقًا، وتستخدم صفحة المنتج ISR لمدة 60 ثانية، وتستخدم صفحة الإدارة CSR، ثم تحقق من عملها كما هو متوقع.

---|

Web-Tutorial.com

فريق Web-Tutorial التقني

منصة دروس برمجية يديرها عدة مطورين. كل درس يتم كتابته ومراجعته بواسطة مطورين متخصصين في المجال. نعمل على ضمان دقة وموثوقية المحتوى — إذا لاحظت أي مشكلة، فيرجى إخبارنا.

100%