تطبيقات Node.js وNext.js وNuxt.
كيف تُكتشف مشاريع Node.js وتُشغَّل: إصدار Node، ومدير الحزم، وNext.js وNuxt (خادم أو ثابت)، وSvelteKit وAstro وExpress وغيرها، ومتغير PORT، وترحيلات Prisma.
المستودع الذي يحتوي على package.json هو مشروع Node.js. نختار إطار العمل ومدير الحزم وإصدار Node، ونبنيه ونشغّله — وما عليك إلا الدفع (push).
إصدار Node ومدير الحزم
- Node.js — يؤخذ من
engines.nodeفيpackage.jsonأو من.nvmrc: أحدث إصدار مناسب من 24 أو 22 أو 20 أو 18 أو 16. ودون أيٍّ منهما، Node.js 22. - مدير الحزم — بحسب ملف القفل:
pnpm-lock.yaml← pnpm، وyarn.lock← yarn، وإلا npm (npm ciعند وجودpackage-lock.json). - البناء — سكربت
build، إن وُجد فيpackage.json.
أطر العمل
| إطار العمل | كيف يعمل |
|---|---|
| Next.js | كخادم (next start) — يعمل العرض من جهة الخادم ومسارات API والبرمجيات الوسيطة كالمعتاد |
Next.js مع output: 'export' | كموقع ثابت من out |
| Nuxt | كخادم (.output/server/index.mjs) |
Nuxt مع ssr: false وسكربت generate | كموقع ثابت من .output/public |
| SvelteKit | كخادم مع adapter-node؛ ومع adapter-static كموقع ثابت |
| Astro | كموقع ثابت؛ ومع @astrojs/node كخادم |
| NestJS | dist/main.js بعد البناء |
| Express وFastify وKoa وHono والخوادم الأخرى | الملف في scripts.start (node server.js)، وإلا main، وإلا server.js أو app.js أو index.js أو main.js |
المشاريع التي تقتصر على الواجهة الأمامية — Vite وCreate React App وAngular وVue CLI وغيرها — تُقدَّم كمواقع ثابتة؛ راجع المواقع الثابتة.
الاستماع على PORT
يجب أن يستمع الخادم على المنفذ الموجود في متغير PORT، وعلى جميع الواجهات:
const port = process.env.PORT || 3000
app.listen(port, '0.0.0.0')يفعل Next.js وNuxt ذلك تلقائيًا. إذا كان تطبيقك يستمع على منفذ ثابت، فلن يستقبل الزوار — ويتوقف النشر حينها عند فحص البدء وتستمر النسخة السابقة في العمل.
قيم وقت البناء
تصل المتغيرات من تبويب المتغيرات إلى التطبيق العامل، لا إلى البناء. أما القيم التي يكتبها البناء في شيفرة العميل — مثل NEXT_PUBLIC_… في Next.js أو VITE_… — فتُقرأ من مستودعك، مثلًا من ملف .env.production مُضاف إلى المستودع. وتقرأ الشيفرة من جهة الخادم تبويب المتغيرات كالمعتاد.
أمر البدء الخاص بك
إذا لم يكن البدء المكتشف ما تريده، فاضبط الإعدادات ← إعدادات البناء ← أمر البدء، مثل node dist/server.js أو npm run start:prod. ويمكن تغيير أوامر التثبيت والبناء من هناك أيضًا.
قواعد البيانات وPrisma
أضف PostgreSQL أو MySQL إلى المشروع واقرأ DATABASE_URL — فهو مضبوط لك. وعند وجود Prisma في اعتمادياتك، يكون أمر الإصدار الموصى به npx prisma migrate deploy: يُشغَّل في كل نشر قبل أن تستقبل النسخة الجديدة الزوار. راجع عمليات النشر.
للطوابير مع BullMQ، أضف Valkey واستخدم REDIS_URL. شغّل عامل الطوابير كـ عامل خلفي — في تبويب العمليات، أو كخدمة مستقلة بمواردها الخاصة. راجع خدمات المشروع.
ملفات تبقى بعد النشر
يبدأ كل نشر من نسخة جديدة من مستودعك. الملفات التي يكتبها تطبيقك في /data تُحفظ بين عمليات النشر وتُنسخ احتياطيًا يوميًا؛ وكل ما يُكتب في مكان آخر يختفي بعد النشر التالي. للملفات المرفوعة والوسائط، يكون تخزين الكائنات عادةً الخيار الأفضل.
المستودعات الأحادية (Monorepos)
للمستودع الذي يضم عدة مشاريع، حدّد مجلد المشروع عند إنشاء التطبيق (مثل apps/web). ويمكن تشغيل مجلد آخر من المستودع نفسه كخدمة ويب مستقلة — راجع خدمات المشروع.