vercel-deploy（Vercel 部署）

Vercel Deployment

Deploy and configure a project on Vercel. If target specifies a particular concern (domains, env vars, etc.), focus there. Otherwise, do the full setup.

Step 1: Install and Authenticate

pnpm add -g vercel
vercel login

If already installed, verify with vercel --version.

Step 2: Link the Project

From the project root:

vercel link

Follow the prompts to connect to an existing Vercel project or create a new one. This creates a .vercel/ directory locally (already in .gitignore by default).

Step 3: Configure vercel.json

Create vercel.json in the project root only if you need non-default settings. Next.js projects usually need minimal config.

{
  "framework": "nextjs",
  "buildCommand": "pnpm build",
  "installCommand": "pnpm install",
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        { "key": "X-Content-Type-Options", "value": "nosniff" },
        { "key": "X-Frame-Options", "value": "DENY" },
        { "key": "Referrer-Policy", "value": "strict-origin-when-cross-origin" }
      ]
    }
  ],
  "redirects": [],
  "rewrites": []
}

Step 4: Environment Variables

Set via CLI

# Add for all environments
vercel env add NEXT_PUBLIC_APP_URL

# Add for specific environments
vercel env add DATABASE_URL production
vercel env add DATABASE_URL preview
vercel env add DATABASE_URL development

Environment Types

Pull env vars to local

vercel env pull .env.local

This syncs your Vercel development env vars to .env.local. Never commit this file.

Common env var issues

Step 5: Custom Domains

Add a domain

vercel domains add yourdomain.com

Configure DNS

Vercel provides DNS records to set. Common patterns:

Redirect www to root (or vice versa)

Configure in Vercel Dashboard > Domains, or in vercel.json:

{
  "redirects": [
    {
      "source": "/:path((?!api/).*)",
      "has": [{ "type": "host", "value": "www.yourdomain.com" }],
      "destination": "https://yourdomain.com/:path",
      "permanent": true
    }
  ]
}

Step 6: Build Settings

Framework presets

Vercel auto-detects Next.js. Override only when needed:

Monorepo setup

Set the root directory in Vercel project settings to the app's subdirectory:

Root Directory: apps/web

Or use vercel.json at the repo root:

{
  "ignoreCommand": "npx turbo-ignore"
}

Step 7: Preview Deployments

Every push to a non-production branch creates a preview deployment automatically.

Branch-based previews

• Each PR gets a unique URL: <project>-<branch>-<team>.vercel.app
• Comment bots post the preview URL on PRs
• Preview deployments use "Preview" environment variables

Protect preview deployments

In Vercel Dashboard > Settings > General > Password Protection, enable password or Vercel Authentication for preview URLs.

Skip deployments for non-code changes

Add to vercel.json:

{
  "ignoreCommand": "git diff --quiet HEAD^ HEAD -- . ':!docs' ':!*.md'"
}

Step 8: Serverless and Edge Functions

Serverless function config

Next.js API routes and Server Actions deploy as serverless functions by default.

Set runtime and region in the route file:

export const runtime = 'nodejs' // or 'edge'
export const maxDuration = 30   // seconds (default 10, max depends on plan)
export const preferredRegion = 'iad1'

Edge vs. Serverless

Step 9: Deploy

Preview deploy (from any branch)

vercel

Production deploy

vercel --prod

Via Git (recommended)

Connect the Git repo in Vercel Dashboard. Every push to main auto-deploys to production. Every PR branch gets a preview.

Troubleshooting

Deployment Checklist