vercel-deploy（Vercel 部署）

Vercel Deploy

Zero-auth deployment to Vercel with automatic framework detection. Deploy any web application with a single command and receive preview URLs, claim URLs, and deployment metadata.

When to Apply

Use this skill when:

• Deploying a web application to Vercel for preview or production
• Setting up a deployment pipeline for a new project
• Creating preview deployments for pull request review
• Testing production builds in a live environment
• Demonstrating a prototype or proof of concept

Supported Frameworks

Vercel auto-detects and configures builds for these frameworks:

Deployment Workflow

Step 1: Prerequisites

Ensure the Vercel CLI is installed:

# Install globally
npm install -g vercel

# Or use npx (no install needed)
npx vercel

Step 2: Project Setup (First Time Only)

For new projects not yet linked to Vercel:

# Interactive setup -- creates .vercel/project.json
vercel link

# Or create a new project
vercel --yes

Step 3: Deploy

Preview Deployment (Default)

# Deploy to preview environment
vercel

# Output:
# Vercel CLI 34.x.x
# Linked to username/project-name
# Inspect: https://vercel.com/username/project-name/abcdef
# Preview: https://project-name-abc123.vercel.app

Production Deployment

# Deploy to production
vercel --prod

# Output includes production URL:
# Production: https://project-name.vercel.app

Zero-Auth Deployment (Agent Mode)

For automated deployments without authentication prompts:

# Using VERCEL_TOKEN environment variable
VERCEL_TOKEN=your-token vercel --yes --token=$VERCEL_TOKEN

# Or with npx for zero-install
VERCEL_TOKEN=your-token npx vercel --yes --token=$VERCEL_TOKEN

Step 4: Deployment Output

Successful deployments return JSON-compatible metadata:

{
  "url": "https://project-name-abc123.vercel.app",
  "inspectUrl": "https://vercel.com/team/project/deployment-id",
  "projectId": "prj_abc123",
  "deploymentId": "dpl_abc123",
  "readyState": "READY"
}

Use --json flag for machine-readable output:

vercel --json

Step 5: Post-Deployment Verification

# Check deployment status
vercel inspect <deployment-url>

# View deployment logs
vercel logs <deployment-url>

# List recent deployments
vercel list

Configuration Options

Environment Variables

# Set environment variables for deployment
vercel env add VARIABLE_NAME production
vercel env add VARIABLE_NAME preview
vercel env add VARIABLE_NAME development

# Or pass inline
vercel -e KEY=value -e KEY2=value2

Build Configuration

Override auto-detected settings in vercel.json:

{
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "installCommand": "npm install",
  "framework": "vite",
  "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
}

Custom Domains

# Add a custom domain
vercel domains add example.com

# Assign domain to project
vercel alias <deployment-url> example.com

Framework-Specific Patterns

Next.js

{
  "framework": "nextjs",
  "buildCommand": "next build",
  "outputDirectory": ".next"
}

Next.js deployments automatically enable:

• Edge Runtime for middleware
• ISR (Incremental Static Regeneration)
• Image Optimization via next/image
• Server Actions

Vite / React SPA

{
  "framework": "vite",
  "buildCommand": "vite build",
  "outputDirectory": "dist",
  "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
}

SvelteKit

{
  "framework": "sveltekit",
  "buildCommand": "vite build",
  "outputDirectory": ".svelte-kit/output"
}

SvelteKit uses the @sveltejs/adapter-vercel adapter for optimal deployment.

Deployment Strategies

Preview per Pull Request

Configure GitHub integration for automatic preview deployments:

1. Connect repository in Vercel dashboard
2. Every PR gets a unique preview URL
3. Comments added to PR with preview link
4. Preview is torn down when PR is closed

Staged Rollouts

# Deploy to staging first
vercel --env ENVIRONMENT=staging

# Promote to production after validation
vercel promote <deployment-url>

Rollback

# List recent deployments
vercel list

# Rollback to a previous deployment
vercel rollback <deployment-url>

Troubleshooting

Build Fails

1. Check build logs: vercel logs <url>
2. Verify buildCommand matches local build
3. Check environment variables are set for the target environment
4. Ensure Node.js version matches (use engines in package.json)

404 on Client-Side Routes

Add rewrites for SPA frameworks:

{
  "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
}

Large Bundle Warnings

1. Enable tree-shaking in bundler config
2. Use dynamic imports for heavy dependencies
3. Check Vercel's bundle analysis: vercel inspect --logs

Timeout Issues

• Serverless functions: Default 10s timeout (configurable up to 300s on Pro)
• Edge functions: 25ms CPU time limit (wall-clock can be longer with I/O)
• Static generation: 45s default timeout

{
  "functions": {
    "api/heavy-route.ts": {
      "maxDuration": 60
    }
  }
}

Security Considerations

• Never commit VERCEL_TOKEN to version control
• Use environment variables for secrets (not hardcoded)
• Enable Vercel's DDoS protection for production
• Use vercel env pull to sync environment variables locally
• Review deployment protection settings for preview URLs

References

• Vercel CLI Documentation
• Vercel Deployment Documentation
• Framework-Specific Guides

Iron Laws

1. ALWAYS test the build locally before deploying to ensure the deployment will succeed
2. NEVER deploy to production without first creating and validating a preview deployment
3. ALWAYS verify environment variables are configured in the Vercel project before deploying
4. NEVER store sensitive secrets in deployment commands or public URLs
5. ALWAYS check the deployment logs immediately after deployment to confirm the build succeeded

Anti-Patterns

Framework Detection Patterns

Vercel CLI auto-detects frameworks by checking project files in this priority order:

When auto-detection fails, specify framework explicitly:

vercel --build-env FRAMEWORK_PRESET=nextjs

Environment Variable Management

Setting Environment Variables

# Add env var (prompts for value)
vercel env add MY_VAR production

# Add from .env file
vercel env pull .env.local

# List all env vars
vercel env ls

# Remove env var
vercel env rm MY_VAR production

Environment Scopes

Monorepo Configuration

For pnpm/npm/yarn workspaces:

{
  "buildCommand": "cd ../.. && pnpm build --filter=my-app",
  "installCommand": "pnpm install --filter=my-app...",
  "rootDirectory": "packages/my-app"
}

Set root directory in Vercel dashboard or vercel.json:

{
  "framework": "nextjs",
  "buildCommand": "pnpm turbo build --filter=web",
  "outputDirectory": "apps/web/.next"
}

Local Development

vercel dev — runs your project locally with Vercel's edge network simulation

• Supports: serverless functions, edge functions, environment variables
• Port: defaults to 3000, use vercel dev --listen 3001 for custom port
• Hot reload: automatic for Next.js, SvelteKit, Astro, Nuxt

vercel dev                    # Start local dev server on port 3000
vercel dev --listen 3001      # Custom port

vercel.json Configuration Patterns

{
  "rewrites": [{ "source": "/api/(.*)", "destination": "/api/index" }],
  "redirects": [{ "source": "/old", "destination": "/new", "permanent": true }],
  "headers": [{ "source": "/(.*)", "headers": [{ "key": "X-Frame-Options", "value": "DENY" }] }],
  "functions": { "api/heavy.js": { "memory": 3009, "maxDuration": 60 } },
  "crons": [{ "path": "/api/cron", "schedule": "0 * * * *" }]
}

Team & Project Config

vercel teams ls                 # List teams
vercel switch <team-slug>       # Switch active team
vercel link                     # Link local dir to Vercel project
vercel project ls               # List projects in current team

Memory Protocol (MANDATORY)

Before starting: Read .claude/context/memory/learnings.md

After completing:

• New pattern -> .claude/context/memory/learnings.md
• Issue found -> .claude/context/memory/issues.md
• Decision made -> .claude/context/memory/decisions.md