MATIN MOLKARA
SERIES: آموزش Next js — PART 28 OF 28

قسمت بیست و هشتم - استقرار کامل پروژه Next.js روی Vercel

در این قسمت می‌خواهیم پروژه را به‌صورت کامل روی Vercel deploy کنیم. اما قبل از deploy، یک مرحله مهم داریم: آماده‌سازی پروژه و commit کردن آن روی Git.

#استقرار کامل پروژه Next.js روی Vercel

در قسمت قبل، دیتابیس پروژه را روی Neon آماده کردیم و یاد گرفتیم چطور Prisma را به یک دیتابیس PostgreSQL واقعی متصل کنیم.

حالا پروژه ما از نظر دیتابیس production-ready شده و وقت آن رسیده که نسخه آنلاین پروژه را منتشر کنیم.

در این قسمت می‌خواهیم پروژه را به‌صورت کامل روی Vercel deploy کنیم.
اما قبل از deploy، یک مرحله مهم داریم: آماده‌سازی پروژه و commit کردن آن روی Git.

هدف این قسمت

در پایان این قسمت:

  • پروژه را برای commit آماده می‌کنید
  • فایل‌های حساس را از Git خارج نگه می‌دارید
  • پروژه را روی GitHub قرار می‌دهید
  • پروژه را به Vercel متصل می‌کنید
  • envهای production را در Vercel تنظیم می‌کنید
  • migrationهای Prisma را برای production اعمال می‌کنید
  • deploy نهایی را تست می‌کنید

چرا قبل از Vercel باید Git را آماده کنیم؟

Vercel معمولاً پروژه را مستقیم از یک repository مثل GitHub, GitLab یا Bitbucket deploy می‌کند.

یعنی روند معمول این است:

Local Project → Git Repository → GitHub → Vercel

پس قبل از اینکه سراغ Vercel برویم، باید مطمئن شویم پروژه به شکل درست commit شده است.

مرحله ۱: بررسی وضعیت پروژه

اول در ریشه پروژه، وضعیت فایل‌ها را بررسی کنید:

git status

اگر پروژه هنوز Git repository نیست، باید Git را initialize کنید:

git init

بعد دوباره وضعیت را ببینید:

git status

مرحله ۲: بررسی .gitignore

قبل از commit کردن، بسیار مهم است که فایل‌های حساس وارد Git نشوند.

فایل .gitignore باید حداقل این موارد را داشته باشد:

node_modules
.next
.env
.env.local
.env.*.local
.vercel

اگر از Prisma استفاده می‌کنید، معمولاً پوشه migrationها باید commit شوند:

prisma/migrations

یعنی migrationها را در .gitignore نگذارید، چون برای production لازم هستند.

نکته امنیتی مهم درباره envها

هیچ‌وقت این فایل‌ها را commit نکنید:

.env
.env.local
.env.production

چون ممکن است داخل آن‌ها اطلاعات حساس باشد، مثل:

DATABASE_URL=...
CLOUDINARY_API_SECRET=...
SESSION_SECRET=...
ADMIN_PASSWORD=...

اگر قبلاً یکی از این فایل‌ها را commit کرده‌اید، فقط حذف کردن فایل کافی نیست.
باید secretهای داخل آن را تغییر دهید، چون ممکن است لو رفته باشند.

مرحله ۳: آماده‌سازی فایل نمونه env

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

.env.example

مثلاً:

DATABASE_URL=""
DIRECT_URL=""

CLOUDINARY_CLOUD_NAME=""
CLOUDINARY_API_KEY=""
CLOUDINARY_API_SECRET=""

SITE_URL=""

SESSION_SECRET=""

ADMIN_EMAIL=""
ADMIN_PASSWORD=""

این فایل مقدار واقعی ندارد و می‌تواند commit شود.

مرحله ۴: نصب و تست local قبل از commit

قبل از اینکه پروژه را commit کنید، بهتر است یک بار نصب و build را بررسی کنید:

npm install
npm run build

اگر پروژه build نشود، احتمالاً روی Vercel هم deploy نمی‌شود.

اگر build درست بود، اجرای production را هم تست کنید:

npm start

بعد routeهای مهم را دستی بررسی کنید:

/
/blog
/projects
/admin/login
/admin
/admin/projects
/admin/posts

مرحله ۵: اضافه کردن فایل‌ها به Git

حالا فایل‌ها را stage کنید:

git add .

بعد دوباره وضعیت را بررسی کنید:

git status

مطمئن شوید فایل‌های حساس مثل .env یا .env.local داخل لیست staged files نیستند.

اگر اشتباهی stage شده بودند، آن‌ها را خارج کنید:

git restore --staged .env
git restore --staged .env.local

مرحله ۶: commit کردن پروژه

حالا اولین commit یا commit جدید را بسازید:

git commit -m "Prepare project for production deploy"

اگر این اولین commit پروژه است، می‌توانید پیام ساده‌تری هم بنویسید:

git commit -m "Initial commit"

مرحله ۷: ساخت repository در GitHub

وارد GitHub شوید و یک repository جدید بسازید.

مثلاً نام repository:

next-portfolio

هنگام ساخت repository، اگر پروژه را قبلاً در local ساخته‌اید، بهتر است گزینه‌های زیر را فعال نکنید:

  • README
  • .gitignore
  • license

چون این فایل‌ها ممکن است از قبل در پروژه شما وجود داشته باشند.

مرحله ۸: اتصال پروژه local به GitHub

بعد از ساخت repository، GitHub چند دستور به شما می‌دهد.

معمولاً چیزی شبیه این است:

git remote add origin https://github.com/username/next-portfolio.git
git branch -M main
git push -u origin main

بعد از اجرای این دستورات، کد پروژه روی GitHub قرار می‌گیرد.

مرحله ۹: ورود به Vercel

حالا وارد Vercel شوید.

بهترین حالت این است که با همان حساب GitHub وارد شوید تا Vercel بتواند repositoryهای شما را بخواند.

بعد از ورود، روی گزینه import project یا add new project کلیک کنید.

مرحله ۱۰: Import کردن repository در Vercel

در صفحه Import، repository پروژه را انتخاب کنید.

مثلاً:

next-portfolio

Vercel معمولاً خودش تشخیص می‌دهد پروژه Next.js است.

تنظیمات پیش‌فرض معمولاً این‌طور هستند:

Framework Preset: Next.js
Build Command: next build
Output Directory: .next
Install Command: npm install

در بیشتر پروژه‌های Next.js نیازی نیست این موارد را تغییر دهید.

مرحله ۱۱: تنظیم envها در Vercel

قبل از deploy، باید envهای production را در Vercel وارد کنید.

در بخش Environment Variables، مقادیر لازم را اضافه کنید.

برای پروژه ما معمولاً این envها مهم‌اند:

DATABASE_URL=...
DIRECT_URL=...

CLOUDINARY_CLOUD_NAME=...
CLOUDINARY_API_KEY=...
CLOUDINARY_API_SECRET=...

SITE_URL=https://your-domain.vercel.app

SESSION_SECRET=...

ADMIN_EMAIL=...
ADMIN_PASSWORD=...

نکته مهم: مقدار SITE_URL باید آدرس production باشد.

در deploy اول ممکن است هنوز دامنه نهایی را ندانید.
می‌توانید بعد از اولین deploy، دامنه Vercel را بردارید و مقدار SITE_URL را آپدیت کنید.

مرحله ۱۲: تنظیم DATABASE_URL برای Neon

از قسمت قبل می‌دانیم که برای Neon معمولاً دو connection string داریم:

DATABASE_URL="postgresql://...pooler.../neondb?sslmode=require"
DIRECT_URL="postgresql://...neon.tech/neondb?sslmode=require"

پیشنهاد رایج:

  • DATABASE_URL: اتصال pooled
  • DIRECT_URL: اتصال direct

در schema.prisma هم باید چیزی شبیه این داشته باشید:

datasource db {
  provider  = "postgresql"
  url       = env("DATABASE_URL")
  directUrl = env("DIRECT_URL")
}

مرحله ۱۳: نکته مهم درباره Prisma Client در Vercel

برای اینکه Prisma Client در زمان build درست generate شود، بهتر است اسکریپت build را در package.json بررسی کنید.

حالت ساده:

{
  "scripts": {
    "build": "next build"
  }
}

در بسیاری از پروژه‌ها همین کافی است.

اما اگر در Vercel با خطای Prisma Client مواجه شدید، می‌توانید build script را این‌طور تغییر دهید:

json
{
  "scripts": {
    "build": "prisma generate && next build"
  }
}

این کار باعث می‌شود قبل از build، Prisma Client ساخته شود.

مرحله ۱۴: اجرای migration در production

یک نکته مهم:

Vercel به‌صورت خودکار migrationهای Prisma را برای شما اجرا نمی‌کند، مگر اینکه خودتان تنظیم کنید.

برای production باید migrationها با این دستور اعمال شوند:

npx prisma migrate deploy

چند روش برای انجام این کار وجود دارد.

روش ۱: اجرای migration از سیستم local روی دیتابیس production

اگر envهای local شما به دیتابیس Neon production وصل هستند، می‌توانید از سیستم خودتان اجرا کنید:

npx prisma migrate deploy

این دستور migrationهای موجود در prisma/migrations را روی دیتابیس Neon اعمال می‌کند.

بعد از آن، Vercel فقط اپلیکیشن را deploy می‌کند.

این روش برای شروع ساده و قابل فهم است.

روش ۲: اضافه کردن migration به build command

می‌توانید build script را این‌طور بنویسید:

{
  "scripts": {
    "build": "prisma migrate deploy && prisma generate && next build"
  }
}

اما این روش همیشه بهترین انتخاب نیست.

چرا؟

چون هر بار deploy اجرا می‌شود، migration هم بررسی می‌شود.
اگر migrationها درست مدیریت نشوند، ممکن است deploy شما به مشکل بخورد.

بهتر این است:

اول migration را دستی روی Neon اجرا کنیم
بعد پروژه را روی Vercel deploy کنیم

یعنی:

npx prisma migrate deploy
git push

بعد Vercel با push جدید deploy را انجام می‌دهد.

مرحله ۱۵: اولین deploy در Vercel

بعد از تنظیم envها، روی Deploy کلیک کنید.

Vercel مراحل زیر را انجام می‌دهد:

  • نصب dependencyها
  • اجرای build
  • ساخت خروجی production
  • انتشار پروژه روی دامنه Vercel

اگر همه‌چیز درست باشد، در پایان یک URL می‌گیرید، مثلاً:

https://next-portfolio.vercel.app

مرحله ۱۶: آپدیت کردن SITE_URL

بعد از اینکه URL پروژه را گرفتید، به تنظیمات پروژه در Vercel برگردید و مقدار SITE_URL را دقیق تنظیم کنید:

SITE_URL=https://next-portfolio.vercel.app

اگر از NEXT_PUBLIC_SITE_URL استفاده کرده‌اید، آن را هم تنظیم کنید:

NEXT_PUBLIC_SITE_URL=https://next-portfolio.vercel.app

بعد از تغییر env، باید redeploy انجام دهید.

مرحله ۱۷: Redeploy بعد از تغییر env

در Vercel بعد از تغییر envها، باید deployment جدید بسازید.

دو روش دارید:

روش ۱

از پنل Vercel گزینه Redeploy را بزنید.

روش ۲

یک commit کوچک بزنید و push کنید:

git commit --allow-empty -m "Trigger redeploy"
git push

مرحله ۱۸: تست سایت بعد از deploy

بعد از deploy، فقط دیدن صفحه اصلی کافی نیست.
باید مسیرهای مهم را تست کنید.

صفحات عمومی

/
/blog
/projects
/blog/[slug]
/projects/[slug]

صفحات ادمین

/admin/login
/admin
/admin/projects
/admin/posts

عملیات مهم

  • لاگین ادمین
  • ساخت پروژه
  • ویرایش پروژه
  • حذف پروژه
  • ساخت پست
  • ویرایش پست
  • حذف پست
  • آپلود تصویر
  • نمایش تصویر در صفحه عمومی

مرحله مهم

  • لاگین ادمین
  • ساخت پروژه
  • ویرایش پروژه
  • حذف پروژه
  • ساخت پست
  • ویرایش پست
  • حذف پست
  • آپلود تصویر
  • نمایش تصویر در صفحه عمومی

مرحله ۱۹: بررسی Cloudinary در production

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'res.cloudinary.com',
      },
    ],
  },
}

export default nextConfig

مرحله ۲۰: بررسی لاگ‌های Vercel

اگر deploy یا اجرای سایت خطا داد، اولین جایی که باید بررسی کنید logs است.

در Vercel:

Project → Deployments → Select Deployment → Logs

یا برای خطاهای runtime:

Project → Logs

در logs معمولاً می‌توانید خطاهایی مثل این‌ها را ببینید:

  • env missing
  • Prisma connection error
  • build error
  • route handler error
  • image config error

خطاهای رایج در deploy روی Vercel

خطای ۱: env تعریف نشده

مثلاً:

Missing required environment variable: DATABASE_URL

راه‌حل:

  • Environment Variables را در Vercel بررسی کنید
  • نام env را دقیق مطابق کد وارد کنید
  • بعد redeploy بزنید

خطای ۲: Prisma Client ساخته نشده

نمونه خطا:

PrismaClientInitializationError

یا:

@prisma/client did not initialize yet

راه‌حل:

در package.json:

{
  "scripts": {
    "build": "prisma generate && next build"
  }
}

بعد commit و push کنید:

git add package.json
git commit -m "Generate Prisma client before build"
git push

خطای ۳: جدول‌ها در دیتابیس وجود ندارند

نمونه مشکل:

The table `public.Post` does not exist

دلیل:

migrationها روی Neon اعمال نشده‌اند.

راه‌حل:

npx prisma migrate deploy

خطای ۴: تصویر Cloudinary نمایش داده نمی‌شود

دلیل‌های رایج:

  • remotePatterns تنظیم نشده
  • next.config.ts بعد از تغییر redeploy نشده
  • URL تصویر اشتباه ذخیره شده

راه‌حل:

  • config را اصلاح کنید
  • commit و push کنید
  • redeploy بزنید

خطای ۵: لاگین در production کار نمی‌کند

دلیل‌های رایج:

  • SESSION_SECRET در Vercel تعریف نشده
  • cookie برای HTTPS درست تنظیم نشده
  • آدرس redirect اشتباه است
  • env مربوط به auth متفاوت است

راه‌حل:

  • envهای auth را بررسی کنید
  • تنظیمات cookie و session را با production هماهنگ کنید
  • logs را بررسی کنید

مرحله ۲۱: اتصال دامنه اختصاصی

اگر دامنه اختصاصی دارید، می‌توانید در Vercel اضافه کنید:

Project → Settings → Domains

بعد دامنه را وارد می‌کنید و Vercel تنظیمات DNS لازم را نشان می‌دهد.

بعد از اتصال دامنه، مقدار SITE_URL را هم تغییر دهید:

SITE_URL=https://your-domain.com

و دوباره redeploy بزنید.

مرحله ۲۲: روند deploy بعدی چطور است؟

بعد از setup اولیه، روند توسعه خیلی ساده می‌شود:

تغییر کد → commit → push → deploy خودکار در Vercel

مثلاً:

git add .
git commit -m "Update admin projects page"
git push

بعد از push، Vercel به‌صورت خودکار build و deploy جدید را شروع می‌کند.

مرحله ۲۳: چک‌لیست قبل از deploy نهایی

قبل از اینکه پروژه را نهایی بدانید، این موارد را بررسی کنید:

  • .env و .env.local commit نشده‌اند
  • .env.example ساخته شده
  • پروژه روی GitHub push شده
  • repository در Vercel import شده
  • همه envها در Vercel تنظیم شده‌اند
  • DATABASE_URL و DIRECT_URL درست هستند
  • migrationها روی Neon اعمال شده‌اند
  • Prisma Client در build ساخته می‌شود
  • SITE_URL مقدار production دارد
  • Cloudinary envها تنظیم شده‌اند
  • next.config.ts برای Cloudinary تنظیم شده
  • deploy بدون خطا انجام شده
  • routeهای public تست شده‌اند
  • routeهای admin تست شده‌اند
  • CRUD پروژه و پست تست شده‌اند
  • آپلود تصویر تست شده
  • metadata و Open Graph بررسی شده‌اند

فایل‌هایی که در این قسمت مهم هستند

در این قسمت با این فایل‌ها بیشتر سروکار داریم:

.gitignore
.env
.env.example
package.json
prisma/schema.prisma
prisma/migrations/
next.config.ts

نمونه نهایی .gitignore

برای این پروژه، .gitignore می‌تواند چیزی شبیه این باشد:

node_modules
.next
out
.vercel

.env
.env.local
.env.*.local

.DS_Store
npm-debug.log*

نمونه envهای لازم در Vercel

DATABASE_URL=""
DIRECT_URL=""

CLOUDINARY_CLOUD_NAME=""
CLOUDINARY_API_KEY=""
CLOUDINARY_API_SECRET=""

SITE_URL=""

SESSION_SECRET=""

ADMIN_EMAIL=""
ADMIN_PASSWORD=""

مقادیر واقعی را فقط در Vercel و local نگه دارید، نه داخل repository.

جمع‌بندی

در این قسمت، پروژه Next.js را برای انتشار واقعی آماده کردیم و روند کامل deploy روی Vercel را یاد گرفتیم.

کارهایی که انجام دادیم:

  • پروژه را برای Git آماده کردیم
  • .gitignore و .env.example را بررسی کردیم
  • پروژه را commit و روی Git کردیم
  • migrationهای Prisma را روی Vercel import کردیم
  • envهای production را تنظیم کردیم
  • migrationهای Prisma را روی Neon اعمال کردیم
  • deploy را انجام دادیم
  • routeهای اصلی، admin، CRUD و آپلود تصویر را تست کردیم

از اینجا به بعد، هر بار که تغییری در پروژه ایجاد کنید، کافی است:

git add .
git commit -m "Your message"
git push

و Vercel به‌صورت خودکار نسخه جدید پروژه را deploy می‌کند.

// 0 comments
#Next.js#vercel#deploy

نظرات (0)

نظر خود را بنویسید