استقرار Next.js در ابران | مستندات ابران

Next.jsتشخیص با dependency: next

ابران پروژه دارای dependency به next را تشخیص می‌دهد، dependencyها را نصب می‌کند، next build را اجرا می‌کند و برنامه را در حالت server روی runtime اجرا می‌کند.

پیش‌نیازها

یک پروژه Next.js با package.json
lockfile مربوط به npm، pnpm یا Yarn
حساب ابران، CLI نصب‌شده و project انتخاب‌شده

اگر اولین deploy شماست، ابتدا CLI را نصب و وارد حساب شوید.

۱. scriptها را بررسی کنید

حداقل scriptهای build و start را در package.json داشته باشید:


{
  "engines": { "node": "22" },
  "scripts": {
    "build": "next build",
    "start": "next start"
  }
}

وجود package-lock.json، pnpm-lock.yaml یا yarn.lock نصب reproducible را فعال می‌کند. lockfile را commit کنید و فقط یکی از package managerها را در هر build context نگه دارید.

Generated builder فعلی Bun را اجرا نمی‌کند. اگر bun.lock یا packageManager: "bun" دارید، به npm، pnpm یا Yarn مهاجرت کنید یا یک Dockerfile صریح بنویسید.

۲. App را بسازید

پورت پیش‌فرض Next.js برابر 3000 است:


abrun app create my-next-app --plan <plan> --port 3000

در runtime، ابران PORT، HOST و HOSTNAME را تنظیم می‌کند و command تشخیص‌داده‌شده Next.js را روی 0.0.0.0 اجرا می‌کند.

۳. متغیرهای محیطی را تنظیم کنید

مقدارهای runtime را پیش از deploy اضافه کنید:


abrun app env set my-next-app NODE_ENV=production
abrun app env set my-next-app 'DATABASE_URL=<connection-url>'

متغیرهای NEXT_PUBLIC_* معمولاً هنگام build داخل bundle قرار می‌گیرند. مقدارهای ثبت‌شده با abrun app env set در runtime اعمال می‌شوند و generated source build فعلی آن‌ها را به مرحله build تزریق نمی‌کند. برای مقدار public در bundle، از پیکربندی غیرحساس داخل source یا Dockerfile کنترل‌شده استفاده کنید. secret را با پیشوند NEXT_PUBLIC_ منتشر نکنید.

اگر next build به DATABASE_URL نیاز پیدا می‌کند، دسترسی به دیتابیس را تا runtime به تعویق بیندازید یا build را با Dockerfile صریح طراحی کنید. برای رفتار دقیق مقدارهای build و runtime، قرارداد نسخه Next.js خود را بررسی کنید.

۴. deploy کنید

از پوشه دارای package.json اجرا کنید:


abrun deploy my-next-app --logs

ابران باید در مرحله planning، platform را node و framework را next تشخیص دهد. پس از Ready، URL را باز و routeهای server-rendered و API را آزمایش کنید.

monorepo

اگر Next.js در apps/web قرار دارد، build context را صریح انتخاب کنید:


abrun deploy my-next-app . --root-directory apps/web

برای workspaceهایی که dependency داخلی دارند، package ریشه باید workspaces را تعریف کند و package هدف باید name داشته باشد. plan تشخیص‌داده‌شده را در جزئیات deployment بررسی کنید.

standalone و static export

مسیر خودکار عمومی فعلی برای Next.js، server mode است. output: "standalone" و output: "export" artifact متفاوتی تولید می‌کنند، اما schema عمومی abrun.yaml هنوز output mode را انتخاب نمی‌کند.

برای این دو حالت از Dockerfile آزمایش‌شده استفاده کنید و build را صریح کنترل کنید. next start را برای standalone یا export به‌عنوان مسیر معتبر فرض نکنید.

رفع مشکل

next: not found: dependency و lockfile را بررسی کنید؛ Next.js باید در dependencyهای پروژه نصب باشد.
build به env نیاز دارد: مقدار غیرحساس build-time را فراهم یا build را با Dockerfile کنترل کنید.
health check شکست می‌خورد: App باید روی پورت انتخاب‌شده بالا بماند؛ next dev برای production مناسب نیست.
monorepo مبهم است: --root-directory را روی package هدف بگذارید و نام workspace را بررسی کنید.
هشدار standalone می‌بینید: config خروجی را به server mode برگردانید یا Dockerfile مخصوص standalone بنویسید.

لاگ کامل را با abrun deploy my-next-app --verbose و لاگ runtime را با abrun app logs my-next-app --previous --tail 100 ببینید.