vercel-deployments

Vercel 部署

借助预览环境和托管边缘基础设施，快速发布 Web 应用。

何时使用此技能

在以下情况下使用此技能：

• 部署 Next.js、SvelteKit、Nuxt 或静态站点
• 为每个 PR 设置预览环境
• 配置边缘函数和无服务器 API
• 管理预览环境和生产环境中的环境变量
• 设置自定义域名和重定向

前提条件

• Node.js 18+
• Vercel 账号（免费套餐适用于个人项目）
• Git 仓库（GitHub、GitLab 或 Bitbucket）

快速开始

# Install CLI
npm i -g vercel

# Login and link project
vercel login
vercel link

# Deploy to preview
vercel

# Deploy to production
vercel --prod

# Pull environment variables locally
vercel env pull .env.local

项目配置

// vercel.json
{
  "framework": "nextjs",
  "buildCommand": "npm run build",
  "outputDirectory": ".next",
  "installCommand": "npm ci",
  "regions": ["iad1", "sfo1", "cdg1"],
  "headers": [
    {
      "source": "/api/(.*)",
      "headers": [
        { "key": "Cache-Control", "value": "no-store" },
        { "key": "X-Content-Type-Options", "value": "nosniff" }
      ]
    },
    {
      "source": "/(.*)",
      "headers": [
        { "key": "X-Frame-Options", "value": "DENY" },
        { "key": "Strict-Transport-Security", "value": "max-age=63072000; includeSubDomains" }
      ]
    }
  ],
  "redirects": [
    { "source": "/blog/:slug", "destination": "/posts/:slug", "permanent": true }
  ],
  "rewrites": [
    { "source": "/api/v1/:path*", "destination": "https://api.example.com/:path*" }
  ]
}

环境变量

# Add environment variables
vercel env add DATABASE_URL production
vercel env add DATABASE_URL preview
vercel env add NEXT_PUBLIC_API_URL production

# List all env vars
vercel env ls

# Pull to local .env.local
vercel env pull .env.local

# Remove an env var
vercel env rm SECRET_KEY production

环境隔离模式

# Production — real credentials
vercel env add DATABASE_URL production <<< "postgresql://prod-host:5432/app"
vercel env add STRIPE_SECRET_KEY production

# Preview — staging/test credentials
vercel env add DATABASE_URL preview <<< "postgresql://staging-host:5432/app"
vercel env add STRIPE_SECRET_KEY preview   # Use test mode key

# Development — local values
vercel env add DATABASE_URL development <<< "postgresql://localhost:5432/app"

边缘函数

// app/api/geo/route.ts — Edge API route (Next.js App Router)
import { NextRequest } from 'next/server';

export const runtime = 'edge';

export function GET(request: NextRequest) {
  const country = request.geo?.country || 'US';
  const city = request.geo?.city || 'Unknown';

  return Response.json({
    country,
    city,
    region: request.geo?.region,
    timestamp: new Date().toISOString(),
  });
}

// middleware.ts — Edge middleware for auth/redirects
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  // Block non-US traffic from admin
  if (request.nextUrl.pathname.startsWith('/admin')) {
    if (request.geo?.country !== 'US') {
      return NextResponse.redirect(new URL('/blocked', request.url));
    }
  }

  // Add security headers
  const response = NextResponse.next();
  response.headers.set('X-Request-Id', crypto.randomUUID());
  return response;
}

export const config = {
  matcher: ['/admin/:path*', '/api/:path*'],
};

GitHub Actions 集成

# .github/workflows/preview.yml
name: Vercel Preview
on: pull_request

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - run: npm ci
      - run: npm run lint
      - run: npm run test

      - name: Deploy to Vercel Preview
        id: deploy
        run: |
          npm i -g vercel
          URL=$(vercel --token ${{ secrets.VERCEL_TOKEN }} --yes)
          echo "url=$URL" >> "$GITHUB_OUTPUT"

      - name: Comment PR with preview URL
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `Preview deployed: ${{ steps.deploy.outputs.url }}`
            });

CLI 命令参考

# Deployments
vercel                          # Deploy to preview
vercel --prod                   # Deploy to production
vercel rollback                 # Rollback last production deploy
vercel promote <url>            # Promote preview to production

# Domains
vercel domains add example.com
vercel domains ls
vercel certs ls

# Logs
vercel logs <deployment-url>
vercel logs <deployment-url> --follow

# Project management
vercel project ls
vercel project rm <name>

# Inspect deployment
vercel inspect <deployment-url>

生产环境防护措施

• 合并前要求通过预览检查（GitHub 分支保护）
• 分离预览环境和生产环境的环境变量——切勿共用 API 密钥
• 使用分支保护，并要求通过部署状态检查
• 在 Vercel Analytics 中监控函数运行时长和冷启动情况
• 在 Vercel 控制面板中设置支出限额，避免意外费用
• 启用 Vercel Firewall 防范 DDoS 攻击和机器人
• 使用 vercel.json 配置安全标头（CSP、HSTS、X-Frame-Options）

监控与分析

# Enable Speed Insights in Next.js
npm install @vercel/speed-insights

# Enable Web Analytics
npm install @vercel/analytics

// app/layout.tsx
import { Analytics } from '@vercel/analytics/react';
import { SpeedInsights } from '@vercel/speed-insights/next';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Analytics />
        <SpeedInsights />
      </body>
    </html>
  );
}

故障排除

问题	解决方案
构建失败	检查 vercel logs，确认 engines 字段中的 Node.js 版本
缺少环境变量	运行 vercel env pull，检查变量作用域（预览环境还是生产环境）
边缘函数超时	边缘函数有 30s 的限制；将繁重任务移至无服务器环境（不要使用 runtime = 'edge'）
冷启动缓慢	尽可能使用边缘运行时，减小打包体积
域名无法使用	检查 DNS 传播情况，确认 vercel domains 配置

相关技能

• github-actions — 自动化部署门禁
• cloudflare-pages — 可替代的边缘托管方案
• ssl-tls-management — 自定义证书设置