Vercel 部署故障排查指南：构建失败、函数超时、路由错误与性能优化

# 1. 本地完整构建（development 会跳过类型检查）
npm run build

# 2. 单独检查类型
npx tsc --noEmit

# 3. 如果确认类型检查过于严格，临时放宽（不推荐长期使用）

// tsconfig.json
{
  "compilerOptions": {
    "strict": false,  // 临时关闭严格模式
    "noEmit": true
  }
}

// next.config.js
module.exports = {
  typescript: {
    ignoreBuildErrors: true,  // ⚠️ 仅临时用
  },
  eslint: {
    ignoreDuringBuilds: true, // ⚠️ 仅临时用
  },
};

# 1. 删除 lock 文件和 node_modules，重新安装
rm -rf node_modules package-lock.json
npm install

# 2. 如果使用 pnpm
rm -rf node_modules pnpm-lock.yaml
pnpm install

# 3. 检查 Node.js 版本（Vercel 默认使用 package.json engines 或项目设置）
# 在 Vercel Dashboard → Settings → General → Node.js Version 中设置

// tsconfig.json / jsconfig.json
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./*"]  // 或 ["./src/*"]，对应你的目录结构
    }
  }
}

// package.json — 确认没有漏装依赖
{
  "dependencies": {
    "@prisma/client": "^5.0.0"
  }
}

// package.json
{
  "scripts": {
    "build": "prisma generate && next build",
    "postinstall": "prisma generate"  // 确保 npm install 时自动执行
  }
}

# 确认 prisma/schema.prisma 存在
ls prisma/schema.prisma

# 确认生成后文件存在
ls node_modules/.prisma/client/

# 1. 本地检查 .env
env | grep DATABASE_URL

# 2. Vercel Dashboard → Settings → Environment Variables
#    确认 Production 和 Preview 环境都配置了

# 3. 如果本地 .env 有但生产没有，重新添加并 Redeploy
vercel env add DATABASE_URL

# 增大 Node.js 堆内存
export NODE_OPTIONS="--max-old-space-size=4096"
npm run build

// next.config.js
module.exports = {
  // 减少并发，降低内存峰值
  experimental: {
    workerThreads: false,
    cpus: 2,
  },
  // 或关闭静态优化
  images: {
    unoptimized: true, // 如果构建卡在图片优化
  },
};

# 使用 Turborepo 远程缓存，避免每次全量构建
# vercel.json
{
  "buildCommand": "turbo run build --remote-cache"
}

# 在 Vercel Dashboard → Settings → Environment Variables 添加
TURBO_TOKEN=your_token
TURBO_TEAM=your_team_slug
TURBO_REMOTE_CACHE_SIGNATURE_KEY=your_signature_key

# 强制使用 lock 文件，避免解析耗时
# package.json 中添加 engines
{
  "packageManager": "pnpm@9.0.0",
  "engines": {
    "node": "20.x"
  }
}

# Vercel 构建时自动使用 pnpm 的 frozen-lockfile，显著减少安装时间
# 无需额外配置，只要存在 pnpm-lock.yaml 即可

// next.config.js
module.exports = {
  // 启用实验性增量编译（Next.js 14+）
  experimental: {
    incrementalCacheHandlerPath: require.resolve('./cache-handler'),
  },
  // 只对变更页面重新静态生成
  staticPageGenerationTimeout: 120,
};

# 检查 .next 目录体积
du -sh .next/

# 如果超过 250MB（Hobby 限制），优化方向：
# 1. 将图片迁移至外部 CDN（Cloudflare R2 / AWS S3）
# 2. 禁用不必要的 Source Map
echo "NEXT_TELEMETRY_DISABLED=1" >> .env

// next.config.js
module.exports = {
  productionBrowserSourceMaps: false,
  images: {
    remotePatterns: [
      { protocol: 'https', hostname: 'cdn.yourdomain.com' },
    ],
  },
};

// 1. 添加日志定位慢操作
export default async function handler(req: NextRequest) {
  console.time('db-query');
  const data = await db.query.largeTable();
  console.timeEnd('db-query'); // 查看哪一步最慢

  return Response.json(data);
}

// 2. 使用流式响应避免超时（AI 场景）
import { streamText } from 'ai';

export const runtime = 'edge'; // Edge 函数 30s/60s 限制比 Node.js 更灵活

const result = streamText({
  model: openai('gpt-4'),
  messages,
});
return result.toDataStreamResponse();

// 3. 分页/分批处理大数据
async function getLargeDataSet() {
  const batchSize = 100;
  let cursor = null;
  const allData = [];

  do {
    const batch = await db.findMany({
      take: batchSize,
      skip: cursor ? 1 : 0,
      cursor: cursor ? { id: cursor } : undefined,
    });
    allData.push(...batch);
    cursor = batch[batch.length - 1]?.id;
  } while (cursor);

  return allData;
}

// 1. 用 Edge Functions（冷启动 < 5ms）替代 Node.js Functions
export const runtime = 'edge';

// 2. 在页面级别使用 ISR，让 CDN 服务缓存
export const revalidate = 3600;

// 3. 外部预热服务（如 Pingdom / UptimeRobot）每 5 分钟 ping 一次

# 1. 确认文件位置正确（App Router）
ls src/app/blog/[slug]/page.tsx  # ✅
ls src/app/blog/[slug].tsx       # ❌ App Router 不是这样

# 2. 确认文件位置正确（Pages Router）
ls src/pages/blog/[slug].tsx     # ✅

# 3. App Router + Pages Router 并存时，App Router 优先
# 如果有冲突，重命名 Pages Router 路由

// 4. 确认 generateStaticParams 返回了有效参数
export async function generateStaticParams() {
  const posts = await fetchPosts();
  return posts.map(p => ({ slug: p.slug }));
  // 如果 posts 为空 → build 时不会生成页面
}

// 全局错误处理
// app/error.tsx（App Router 全局错误边界）
'use client';

export default function ErrorBoundary({ error, reset }: { error: Error; reset: () => void }) {
  return (
    <div>
      <h2>Something went wrong!</h2>
      <p>{error.message}</p>
      <button onClick={reset}>Try again</button>
    </div>
  );
}

// app/global-error.tsx（根级错误处理）
export default function GlobalError({ error, reset }: { error: Error; reset: () => void }) {
  return (
    <html>
      <body>
        <h2>Global Error</h2>
        <button onClick={reset}>Reload</button>
      </body>
    </html>
  );
}

# 1. 测试数据库连通性（本地）
psql "$DATABASE_URL" -c "SELECT 1"

# 2. 确认 DATABASE_URL 在 Vercel 环境变量中配置正确
#    特别注意：部分云数据库的连接 URL 有 IP 白名单限制

# 3. Prisma 连接串格式检查
# 正确：postgresql://user:password@host:5432/db?schema=public
# 错误：postgresql://user:password@host/db（缺少端口）

// 4. Prisma Client 单例模式
// lib/prisma.ts
import { PrismaClient } from '@prisma/client';

const globalForPrisma = global as unknown as { prisma: PrismaClient };
export const prisma = globalForPrisma.prisma || new PrismaClient();
if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma;

// 5. 如果连接频繁断开，添加连接池参数
// DATABASE_URL 中添加参数：
// postgresql://...?connection_limit=5&pool_timeout=10

// ❌ 以下模块在 Edge Runtime 中不可用
import fs from 'fs';
import { createServer } from 'net';
import crypto from 'crypto'; // 部分 API 缺失

// ✅ 使用 Web 标准 API 替代
// fs → 使用 fetch 从外部存储读取
// crypto → 使用 Web Crypto API
const encoder = new TextEncoder();
const data = encoder.encode('hello');
const hashBuffer = await crypto.subtle.digest('SHA-256', data);

// ✅ 条件性导入（同一文件兼容两种 Runtime）
import { NextRequest } from 'next/server';

export const runtime = 'edge';

export async function GET(req: NextRequest) {
  // 只在 Edge Runtime 中运行
  const { searchParams } = new URL(req.url);
  return Response.json({ ok: true });
}

# 检查打包后体积
ls -la .vercel/output/functions/_func.func/index.js
# 如果 > 1MB → 需要瘦身

// next.config.js
module.exports = {
  // 将重型依赖拆分为 Node.js Function
  // 在路由级别指定 runtime
};

// app/api/heavy-task/route.ts
export const runtime = 'nodejs'; // 需要重型库时用 Node.js Runtime

# Edge Function 日志与 Node.js Function 日志查看方式相同
vercel logs --all | grep "edge"

# 常见异常：
# - Error: Dynamic code evaluation is not allowed → 避免 eval/new Function
# - Error: Module not found → 检查依赖是否兼容 Edge

# 1. DNS 是否解析到 Vercel
dig www.yourdomain.com +short
# 应该返回 cname.vercel-dns.com 或 Vercel 的 IP

# 2. SSL 证书状态
# Vercel Dashboard → Domains → 查看 SSL 状态
# 可能需要 24 小时自动签发

# 3. CNAME 是否正确
dig CNAME www.yourdomain.com +short
# 预期：cname.vercel-dns.com

# 1. 检查默认域名是否被污染
nslookup your-project.vercel.app
# 如果返回异常 IP → 使用自定义域名

# 2. Ping 测试（从国内）
ping www.yourdomain.com
# 期望 < 100ms（如果 Cloudflare Proxy 已配置）

# 3. 检查 Cloudflare 配置
# 确保橙云代理已开启
# DNS 记录：CNAME www cname.vercel-dns.com Proxied

# 如果 Webhook 频繁失效，检查是否因为仓库转移或改名
git remote -v
# 确认 remote URL 与 Vercel 中配置的仓库一致

# 查看当前部署队列
vercel ls

# 取消不必要的部署（如已废弃的 PR 预览）
vercel remove <deployment-url> --yes

# 1. 使用 Vercel CLI 本地运行（最接近生产环境）
npm i -g vercel
vercel dev

# 2. 带环境变量运行
vercel --prod  # 部署到 production（谨慎使用）

# 3. 查看远程日志
vercel logs --all

# Vercel CLI 查日志
vercel logs your-project.vercel.app

# 筛选特定时间段
vercel logs --since "2025-11-20T10:00:00Z"

# 只看错误
vercel logs --all | grep ERROR

# 每个 PR 自动生成 Preview URL
# 在 PR 的 Checks 中找到 "Visit Preview" 链接

# 用 Preview 环境测试不会污染 Production
# Preview 环境使用 Preview 环境变量

# Chrome DevTools → Lighthouse → 分析
# 常见优化点：
# 1. Image format：使用 WebP/AVIF
# 2. Lazy loading：非首屏图片延迟加载
# 3. Preconnect：添加 DNS 预解析
# 4. Font display：使用 font-display: swap

# 1. 确保 .env 在 .gitignore 中
grep env .gitignore

# 2. 检查提交历史是否泄露过密钥
git log --all --full-history -S "sk-" # 搜索 OpenAI API Key 模式

# 3. 如果泄露，立即轮换密钥
# 并在 Vercel Dashboard 更新环境变量

// app/api/cors-example/route.ts
export async function GET(request: Request) {
  return new Response(JSON.stringify({ message: 'OK' }), {
    headers: {
      'Access-Control-Allow-Origin': 'https://yourdomain.com',
      'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
      'Access-Control-Allow-Headers': 'Content-Type, Authorization',
    },
  });
}

# 1. 在 Vercel Dashboard → Project Settings → Webhooks 添加 Endpoint
# URL: https://hooks.slack.com/services/your/webhook/url

# 2. 选择事件类型：
# - deployment.succeeded
# - deployment.failed
# - deployment.canceled

// 3. 自建 Webhook 接收端（如 Next.js API Route）
// app/api/webhooks/vercel/route.ts
import { NextRequest } from 'next/server';

export async function POST(req: NextRequest) {
  const payload = await req.json();

  if (payload.type === 'deployment.failed') {
    // 发送到 Slack / PagerDuty / 飞书
    await fetch('https://hooks.slack.com/services/...', {
      method: 'POST',
      body: JSON.stringify({
        text: `❌ 部署失败: ${payload.payload.url}\n项目: ${payload.payload.name}\n错误: ${payload.payload.error}`,
      }),
    });
  }

  return Response.json({ ok: true });
}

# 使用 Vercel Deploy Status API 检查部署状态
# 获取 Deployment ID
vercel ls --meta gitCommitRef=main

# 检查特定部署状态
curl -s "https://api.vercel.com/v13/deployments/<deployment-id>?teamId=<team>" \
  -H "Authorization: Bearer $VERCEL_TOKEN" | jq '.readyState'

# 预期返回: READY / ERROR / CANCELED / BUILDING

# 结合 Cron 定期检查（可用 GitHub Actions / Vercel Cron）
# vercel.json
{
  "crons": [
    {
      "path": "/api/health-check",
      "schedule": "*/5 * * * *"
    }
  ]
}

#!/bin/bash
# deploy-check.sh - 在 CI/CD 中集成

DEPLOY_URL=$(vercel deploy --yes --no-wait)
echo "Deployment URL: $DEPLOY_URL"

# 等待部署完成
while true; do
  STATUS=$(vercel inspect $DEPLOY_URL --timeout=1 2>/dev/null | grep "Ready" || echo "pending")
  if echo "$STATUS" | grep -q "Ready"; then
    echo "✅ 部署成功"
    exit 0
  fi
  echo "⏳ 等待中..."
  sleep 5
done

# .github/workflows/deploy-check.yml
name: Check Vercel Deployment

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: vercel/action-deploy@v1
        id: vercel_deploy
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}

      - name: Wait for Deployment
        run: |
          DEPLOY_URL="${{ steps.vercel_deploy.outputs.deployment-url }}"
          for i in {1..30}; do
            STATUS=$(curl -s "$DEPLOY_URL/api/health" -o /dev/null -w "%{http_code}")
            if [ "$STATUS" = "200" ]; then
              echo "✅ 部署正常"
              exit 0
            fi
            sleep 10
          done
          echo "❌ 部署检查超时"
          exit 1

# 1. 查看实时构建日志（可能卡在某个步骤）
vercel logs <deployment-url> --all

# 2. 常见原因：
# - 大型依赖安装（如 Sharp、Puppeteer）
# - 静态生成页数过多（上千页）
# - 外部 API 在构建时调用超时
# - 内存不足导致 Node.js GC 频繁

// 如果卡在图片优化 → 关闭静态图片优化
// next.config.js
module.exports = {
  images: {
    unoptimized: true,
  },
};

# 如果是 Puppeteer/PhantomJS 依赖导致安装慢 → 改用外部截图服务
# 如果是静态生成页数过多 → 改用 ISR，延迟生成

// 添加简单的 Rate Limiting
import {NextRequest} from 'next/server';

export async function middleware(req: NextRequest) {
  const ip = req.ip ?? '127.0.0.1';
  const key = `rate-limit:${ip}`;

  // 使用 Redis / Upstash Redis 计数
  // 超过 100 次/分钟 → 返回 429
}

// 1. 如果文件 < 4.5MB → 确保 Body Parser 配置正确
// app/api/upload/route.ts
export const config = {
  api: {
    bodyParser: {
      sizeLimit: '4.5mb',
    },
  },
};

# 1. 每个人都通过 PR 部署，禁止直接 push 到 main
git branch feature/my-feature
git push origin feature/my-feature
# 在 GitHub 发起 PR，通过 Preview 验证后再合并

# 基础请求测试
curl -I https://your-project.vercel.app/

# 测试缓存行为
curl -I -H "Cache-Control: no-cache" https://your-project.vercel.app/

# 测试不同区域（通过 VPN 或 Cloudflare Worker）
# 检查 x-vercel-id 中的区域代码

# 测试 API 超时阈值
curl -w "@curl-format.txt" -o /dev/null -s https://your-project.vercel.app/api/slow-endpoint

# curl-format.txt 内容：
# time_namelookup: %{time_namelookup}\n
# time_connect: %{time_connect}\n
# time_total: %{time_total}\n

# 查看实时日志（按项目）
vercel logs <project-url> --all --follow

# 查看特定函数的日志
vercel logs <project-url> --all | grep "/api/users"

# 查看部署详情（包含构建时间、环境变量等）
vercel inspect <deployment-url>

# 列出环境变量
vercel env ls

# 添加环境变量（交互式）
vercel env add DATABASE_URL

# 导出环境变量到本地
echo $(vercel env ls | grep DATABASE_URL | awk '{print $2}')

# 查看部署历史
vercel ls --meta gitCommitRef=feature/my-branch

# 回滚到某个部署
vercel --version <deployment-url>