پرش به مطلب اصلی

سایت استاتیک

▶
ویدیو: استقرار سایت استاتیک روی ابرکلیکplaceholder — ویدیو را اینجا جایگزین کنید

ابرکلیک از سایت‌های استاتیک به‌صورت کامل پشتیبانی می‌کند. پس از اجرای دستور build، پوشه خروجی از طریق nginx سرو می‌شود و نیازی به سرور Node.js یا زبان دیگری در زمان اجرا ندارید.

تشخیص خودکار​

buildpack ابرکلیک پروژه را به‌عنوان استاتیک تشخیص می‌دهد اگر:

  • فایل static/index.html در ریشه پروژه وجود داشته باشد، یا
  • فیلد outputDir در فایل abrclick.json مشخص شده باشد، یا
  • فریم‌ورک شناخته‌شده‌ای مانند Vite، CRA، Astro یا Next.js با output: 'export' شناسایی شود.

اگر Dockerfile ندارید، buildpack به‌طور خودکار یک Dockerfile مناسب با nginx تولید می‌کند.

پیکربندی اولیه​

ایجاد فایل abrclick.json​

در ریشه پروژه دستور زیر را اجرا کنید:

abrclick init

سپس فایل abrclick.json را ویرایش کنید:

{
  "name": "my-static-site",
  "runtime": "static",
  "buildCommand": "npm run build",
  "outputDir": "dist",
  "port": 80
}
فیلدتوضیح
runtimeباید static باشد
buildCommandدستور build (مثلاً npm run build)
outputDirپوشه خروجی build (مثلاً dist، out، build)
portپورت nginx — معمولاً 80

مثال کامل: اپ Vite React​

۱. ایجاد پروژه​

npm create vite@latest my-app -- --template react
cd my-app
npm install

۲. ساخت abrclick.json​

{
  "name": "my-vite-app",
  "runtime": "static",
  "buildCommand": "npm run build",
  "outputDir": "dist"
}

۳. ایجاد اپ و deploy​

abrclick apps create --name my-vite-app --runtime static
abrclick deploy

پس از اتمام build، اپ روی آدرس زیر در دسترس خواهد بود:

https://my-vite-app.apps.abrclick.cloud

Next.js با خروجی استاتیک​

اگر از Next.js استفاده می‌کنید و می‌خواهید خروجی استاتیک داشته باشید، در فایل next.config.js یا next.config.ts گزینه output: 'export' را تنظیم کنید:

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
};

module.exports = nextConfig;

سپس abrclick.json را اینگونه بنویسید:

{
  "name": "my-nextjs-site",
  "runtime": "static",
  "buildCommand": "npm run build",
  "outputDir": "out"
}
اطلاع

Next.js با output: 'export' خروجی را در پوشه out می‌ریزد، نه dist. حتماً outputDir را درست تنظیم کنید.

هشدار

قابلیت‌های سمت سرور Next.js مانند Server Components، Route Handlers، و getServerSideProps در حالت استاتیک پشتیبانی نمی‌شوند. اگر به این قابلیت‌ها نیاز دارید، از runtime مربوط به Node.js استفاده کنید.

سایر فریم‌ورک‌ها​

Astro​

{
  "name": "my-astro-site",
  "runtime": "static",
  "buildCommand": "npm run build",
  "outputDir": "dist"
}

Create React App​

{
  "name": "my-cra-app",
  "runtime": "static",
  "buildCommand": "npm run build",
  "outputDir": "build"
}

Vue (Vite)​

{
  "name": "my-vue-app",
  "runtime": "static",
  "buildCommand": "npm run build",
  "outputDir": "dist"
}

Hugo​

{
  "name": "my-hugo-site",
  "runtime": "static",
  "buildCommand": "hugo --minify",
  "outputDir": "public"
}

مسیریابی SPA​

برای اپلیکیشن‌های تک‌صفحه‌ای (SPA) که از client-side routing استفاده می‌کنند (مانند React Router، Vue Router)، باید تمام درخواست‌های ۴۰۴ به index.html هدایت شوند. این کار را با فیلد spa در abrclick.json انجام دهید:

{
  "name": "my-spa",
  "runtime": "static",
  "buildCommand": "npm run build",
  "outputDir": "dist",
  "spa": true
}

با این تنظیم، nginx به‌طور خودکار پیکربندی می‌شود تا تمام درخواست‌های ناشناخته به index.html برگردانده شوند.

نکته

اگر spa: true را فعال نکنید، باز کردن مستقیم URL مانند https://my-app.apps.abrclick.cloud/dashboard خطای ۴۰۴ می‌دهد.

صفحه ۴۰۴ سفارشی​

برای نمایش صفحه خطای سفارشی، فایل 404.html را در پوشه خروجی قرار دهید. buildpack این فایل را به‌عنوان صفحه error_page nginx شناسایی می‌کند.

به‌عنوان مثال، در پروژه Vite فایل public/404.html بسازید:

<!DOCTYPE html>
<html lang="fa" dir="rtl">
<head>
  <meta charset="UTF-8" />
  <title>صفحه پیدا نشد</title>
</head>
<body>
  <h1>۴۰۴ — صفحه پیدا نشد</h1>
  <p><a href="/">بازگشت به خانه</a></p>
</body>
</html>
اطلاع

اگر spa: true فعال باشد، فایل 404.html نادیده گرفته می‌شود زیرا تمام درخواست‌ها به index.html می‌روند.

متغیرهای محیطی در build​

متغیرهای محیطی‌ای که در زمان build نیاز دارید (مانند VITE_API_URL) را پیش از deploy تنظیم کنید:

# از طریق CLI
abrclick apps create --name my-app --runtime static
# سپس env var را set کنید (از طریق dashboard یا CLI)
abrclick deploy
هشدار

در پروژه‌های Vite، فقط متغیرهایی که با VITE_ شروع می‌شوند در کد client قابل دسترسی هستند. در Next.js از پیشوند NEXT_PUBLIC_ استفاده کنید.

محدودیت حجم build​

حداکثر حجم tarball آپلودی برای build ۱۰۰ مگابایت است. پوشه node_modules را حتماً در .gitignore و .dockerignore بگذارید.

یک فایل .dockerignore پیشنهادی:

node_modules
.git
.env
*.log

مشاهده لاگ‌های build​

abrclick apps logs my-vite-app

یا برای یک deployment خاص:

abrclick apps logs my-vite-app --deployment <deployment-id>

دستورات پرکاربرد​

# مشاهده وضعیت اپ
abrclick apps info my-vite-app

# deploy مجدد
abrclick deploy

# deploy از مسیر مشخص
abrclick deploy --source ./my-app

# متوقف کردن اپ
abrclick apps stop my-vite-app

# راه‌اندازی مجدد
abrclick apps restart my-vite-app

مشاهده لاگ‌ها​

برای بررسی لاگ‌های سایت استاتیک خود، از دستور زیر استفاده کنید:

abrclick logs <app>

این دستور لاگ‌های nginx (وب‌سرور زمان اجرا) را نمایش می‌دهد. لاگ‌های بیلد نیز در حین اجرای abrclick deploy استریم می‌شوند.

همچنین می‌توانید لاگ‌ها را از داشبورد مشاهده کنید: وارد صفحه برنامه شوید و بر روی تب لاگ‌ها کلیک کنید.

نکته فنی

برای سایت‌های استاتیک، لاگ‌های nginx شامل درخواست‌های HTTP (مانند GET /index.html) و پاسخ‌های آن (کدهای ۲۰۰، ۴۰۴) هستند. اگر لاگ‌ها به درستی جریان ندارند، احتمالاً nginx راه‌اندازی نشده است.

برای اطلاعات بیشتر، راهنمای کامل لاگ‌ها را مطالعه کنید.

رفع خطاهای رایج​

خطای ۴۰۴ هنگام باز کردن مستقیم URL در SPA​

علت: برنامه شما از client-side routing (مثلاً React Router یا Vue Router) استفاده می‌کند، اما فیلد spa: true در abrclick.json فعال نشده است. nginx به‌طور پیش‌فرض برای مسیرهایی که فایل فیزیکی ندارند خطای ۴۰۴ برمی‌گرداند.

راه‌حل: فیلد spa: true را در فایل abrclick.json اضافه کنید تا تمام درخواست‌های ناشناخته به index.html هدایت شوند:

{
  "name": "my-spa",
  "runtime": "static",
  "buildCommand": "npm run build",
  "outputDir": "dist",
  "spa": true
}

بیلد ناموفق / وابستگی‌ها نصب نشدند​

علت: فایل قفل (lockfile) وجود ندارد یا پکیج‌منیجر نمی‌تواند وابستگی‌ها را دانلود کند. در محیط بیلد ابرکلیک، اینترنت عمومی در دسترس نیست و آینه داخلی به‌صورت خودکار استفاده می‌شود.

راه‌حل: مطمئن شوید فایل قفل مناسب (package-lock.json، yarn.lock یا pnpm-lock.yaml) را کامیت کرده‌اید:

npm install --package-lock-only
git add package-lock.json

پوشه خروجی اشتباه / فایل‌ها سرو نمی‌شوند​

علت: فیلد outputDir در abrclick.json به پوشه اشتباهی اشاره می‌کند. فریم‌ورک‌های مختلف خروجی را در پوشه‌های متفاوتی می‌ریزند (مثلاً Vite در dist، Next.js export در out، CRA در build).

راه‌حل: مطمئن شوید outputDir با پوشه خروجی واقعی فریم‌ورک شما مطابقت دارد:

{
  "outputDir": "dist"
}

برای Next.js با output: 'export':

{
  "outputDir": "out"
}

OOMKilled / خطای حافظه در زمان بیلد​

علت: فرآیند بیلد (مثلاً Vite یا Webpack) از حافظه بیشتر از محدودیت تعریف‌شده استفاده کرده است.

راه‌حل: محدودیت حافظه برنامه را از طریق داشبورد افزایش دهید. همچنین می‌توانید تنظیمات بیلد را بهینه کنید (مثلاً کاهش حجم bundle، غیرفعال کردن source maps).