Vercel 部署 Nuxt.js (Vue) 实战：SSR / SSG / Nitro 全栈上云指南

# 创建项目
npx nuxi@latest init my-nuxt-app

# 进入目录并安装依赖
cd my-nuxt-app
npm install

# 安装 Vercel 适配器（必须）
npm install -D @nuxtjs/vercel-builder
# 实际 Nuxt Nitro 自带 vercel 预设，通常不需要额外安装

// nuxt.config.ts
export default defineNuxtConfig({
  // 默认开启 SSR
  ssr: true,

  // 静态资源/缓存策略
  routeRules: {
    // 首页 SSR（动态内容）
    '/': { isr: 60 },
    // 博客列表页：ISR 5 分钟刷新一次
    '/blog/**': { isr: 300 },
    // 博客详情页：静态生成 + 按需重新验证
    '/blog/**': { prerender: true, isr: 3600 },
    // 关于页：纯静态，永不重新验证
    '/about': { prerender: true },
    // API 路由：不走缓存
    '/api/**': { cors: true, isr: false },
  },

  nitro: {
    // 显式指定 Vercel 预设
    preset: 'vercel',
    // 为 Vercel Functions 设置内存和超时
    vercel: {
      functions: {
        maxDuration: 10, // 函数最大执行时间（秒）
      },
    },
  },

  // 开发服务器代理（本地开发用）
  devtools: { enabled: true },
  compatibilityDate: '2025-01-01',
});

<!-- 错误示范：SEO 不友好，首屏空白 -->
<script setup>
const posts = ref([]);
onMounted(async () => {
  posts.value = await $fetch('/api/posts');
});
</script>

<!-- 正确示范：SSR 直出数据 -->
<script setup>
const { data: posts } = await useAsyncData('posts', () =>
  $fetch('/api/posts')
);
</script>

// 在页面组件中
const { data } = await useFetch('/api/posts');

const { data } = await useFetch('https://cms.example.com/api/posts');

<template>
  <Suspense>
    <template #default>
      <div>
        <ProfileCard />
        <OrderList />
      </div>
    </template>
    <template #fallback>
      <SkeletonLoader />
    </template>
  </Suspense>
</template>

// composables/useDevice.ts
export function useDevice() {
  // 客户端专有 API
  const isMobile = ref(false);

  if (process.client) {
    isMobile.value = /Android|iPhone/i.test(navigator.userAgent);
  }

  // 服务端：通过请求头推断
  if (process.server) {
    const headers = useRequestHeaders(['user-agent']);
    isMobile.value = /Android|iPhone/i.test(headers['user-agent'] || '');
  }

  return { isMobile };
}

// server/api/hello.get.ts
export default defineEventHandler((event) => {
  return {
    message: 'Hello from Nuxt on Vercel!',
    timestamp: new Date().toISOString(),
  };
});

// server/api/users/[id].get.ts
export default defineEventHandler(async (event) => {
  const id = getRouterParam(event, 'id');

  // 这里可以查询数据库
  // const user = await db.findUserById(id);

  return {
    id,
    name: `User ${id}`,
  };
});

// server/utils/prisma.ts
import { PrismaClient } from '@prisma/client';

const globalForPrisma = globalThis as { prisma?: PrismaClient };
export const prisma = globalForPrisma.prisma ?? new PrismaClient();

if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma;

// server/api/posts/index.get.ts
import { prisma } from '~/server/utils/prisma';

export default defineEventHandler(async () => {
  const posts = await prisma.post.findMany({
    orderBy: { createdAt: 'desc' },
    take: 20,
  });
  return posts;
});

// server/api/upload.post.ts
export default defineEventHandler(async (event) => {
  // 查询参数：?category=tech
  const query = getQuery(event);
  const category = query.category as string;

  // 请求体（JSON）
  const body = await readBody(event);

  // 表单数据
  const formData = await readMultipartFormData(event);

  return { category, body };
});

// server/middleware/01.cors.ts
export default defineEventHandler((event) => {
  setResponseHeaders(event, {
    'Access-Control-Allow-Origin': '*',
    'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
    'Access-Control-Allow-Headers': 'Content-Type, Authorization',
  });

  if (event.method === 'OPTIONS') {
    event.node.res.statusCode = 204;
    event.node.res.end();
  }
});

// server/middleware/02.logger.ts
export default defineEventHandler((event) => {
  const start = Date.now();
  event.context.startTime = start;

  event.node.res.on('finish', () => {
    const duration = Date.now() - start;
    console.log(
      `[${event.method}] ${event.path} - ${event.node.res.statusCode} (${duration}ms)`
    );
  });
});

// server/middleware/03.security.ts
export default defineEventHandler((event) => {
  const csp = [
    "default-src 'self'",
    "script-src 'self' 'unsafe-inline'",
    "style-src 'self' 'unsafe-inline'",
    "img-src 'self' data: https:",
  ].join('; ');

  setResponseHeaders(event, {
    'X-Frame-Options': 'DENY',
    'X-Content-Type-Options': 'nosniff',
    'Referrer-Policy': 'strict-origin-when-cross-origin',
    'Content-Security-Policy': csp,
  });
});

// server/plugins/prisma.ts
import { PrismaClient } from '@prisma/client';

export default defineNitroPlugin((nitroApp) => {
  const prisma = new PrismaClient();
  nitroApp.hooks.hook('request', (event) => {
    event.context.prisma = prisma;
  });

  nitroApp.hooks.hook('close', async () => {
    await prisma.$disconnect();
  });
});

// nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    externals: {
      external: ['@prisma/client', 'pg'],
    },
  },
});

NUXT_DATABASE_URL="postgresql://user:pass@host:5432/db"
NUXT_API_SECRET="your-secret-key"
NUXT_PUBLIC_APP_NAME="My Nuxt App"

// 服务端（Server Route、SSR 组件）
const config = useRuntimeConfig();
console.log(config.databaseUrl);     // 服务端私有
console.log(config.public.appName);  // 客户端也可访问

<!-- 客户端组件 -->
<template>
  <h1>{{ appName }}</h1>
</template>

<script setup>
const appName = useRuntimeConfig().public.appName;
</script>

git init
git add .
git commit -m "Init Nuxt project"
git remote add origin https://github.com/yourname/my-nuxt-app.git
git push -u origin main

# 安装 Vercel CLI
npm i -g vercel

# 登录
vercel login

# 在项目根目录执行
vercel

# 首次会提示配置，后续推送自动部署
# 部署到生产环境
vercel --prod

# 测试首页
curl https://my-nuxt-app.vercel.app

# 测试 API
curl https://my-nuxt-app.vercel.app/api/hello

# 测试带参数 API
curl https://my-nuxt-app.vercel.app/api/users/123

npm install -D @nuxt/image

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/image'],
  image: {
    domains: ['cdn.yourdomain.com'],
    screens: {
      xs: 320,
      sm: 640,
      md: 768,
      lg: 1024,
      xl: 1280,
    },
  },
});

<!-- 自动响应式图片 -->
<NuxtImg
  src="/hero.jpg"
  alt="Hero"
  sizes="xs:100vw sm:50vw md:400px"
  loading="lazy"
  placeholder
/>

// nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    routeRules: {
      '/_nuxt/**': {
        headers: {
          'cache-control': 'public, max-age=31536000, immutable',
        },
      },
      '/images/**': {
        headers: {
          'cache-control': 'public, max-age=604800',
        },
      },
    },
  },
});

// nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    routeRules: {
      // 静态资源：永久缓存，文件名含 hash，变更是新文件
      '/_nuxt/**': {
        headers: {
          'cache-control': 'public, max-age=31536000, immutable',
        },
      },
      // 图片：7 天强缓存 + 7 天静默重验
      '/images/**': {
        headers: {
          'cache-control': 'public, s-maxage=604800, stale-while-revalidate=604800',
        },
      },
      // ISR 页面：由 Nuxt 自动生成 SWR 头，无需手动配置
      '/posts/**': { isr: 3600 },
      // API 响应：浏览器不缓存，CDN 缓存 60 秒
      '/api/public/**': {
        headers: {
          'cache-control': 'public, max-age=0, s-maxage=60',
        },
      },
    },
  },
});

// server/api/public/stats.get.ts
export default defineEventHandler((event) => {
  setResponseHeader(event, 'CDN-Cache-Control', 'public, max-age=300');
  return { visitors: 12345, updatedAt: new Date().toISOString() };
});

// nuxt.config.ts
export default defineNuxtConfig({
  routeRules: {
    // 首页：ISR 60 秒
    '/': { isr: 60 },

    // 内容页：ISR 1 小时
    '/posts/**': { isr: 3600 },

    // 用户页：SSR（不缓存）
    '/user/**': { isr: false },

    // API：CORS + 不缓存
    '/api/**': { isr: false, cors: true },
  },
});

// server/api/revalidate.post.ts
export default defineEventHandler(async (event) => {
  const body = await readBody(event);
  const { path, token } = body;

  // 校验密钥
  const config = useRuntimeConfig();
  if (token !== config.revalidateToken) {
    throw createError({ statusCode: 401, statusMessage: 'Invalid token' });
  }

  // 触发重新验证
  const nitro = useNitroApp();
  await nitio.hooks.callHook(' nitro:cache:invalidate', { path });

  return { revalidated: true };
});

curl -X POST https://my-nuxt-app.vercel.app/api/revalidate \
  -H "Content-Type: application/json" \
  -d '{"path": "/posts/hello-world", "token": "your-secret"}'

// middleware.ts
import { NextRequest, NextResponse } from 'next/server';

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

export default function middleware(request: NextRequest) {
  const country = request.geo?.country || 'UNKNOWN';

  // 地区封禁示例
  if (country === 'XX') {
    return new NextResponse('Access Denied', { status: 403 });
  }

  // 注入请求头供 Nuxt Server 路由读取
  const requestHeaders = new Headers(request.headers);
  requestHeaders.set('x-edge-country', country);

  return NextResponse.next({
    request: { headers: requestHeaders },
  });
}

// server/api/geoip.get.ts
export default defineEventHandler((event) => {
  const headers = getRequestHeaders(event);
  const country = headers['x-edge-country'] || 'UNKNOWN';
  return { country };
});

// middleware.ts
import { jwtVerify } from 'jose';
import { NextRequest, NextResponse } from 'next/server';

export default async function middleware(request: NextRequest) {
  const token = request.cookies.get('auth-token')?.value;
  const requestHeaders = new Headers(request.headers);

  if (token) {
    try {
      const secret = new TextEncoder().encode(process.env.JWT_SECRET);
      const { payload } = await jwtVerify(token, secret);
      requestHeaders.set('x-user-id', payload.sub as string);
      requestHeaders.set('x-user-role', payload.role as string);
    } catch {
      // Token 无效，继续不注入用户信息
    }
  }

  return NextResponse.next({ request: { headers: requestHeaders } });
}

// server/api/admin/dashboard.get.ts
export default defineEventHandler((event) => {
  const headers = getRequestHeaders(event);
  const userId = headers['x-user-id'];
  const role = headers['x-user-role'];

  if (role !== 'admin') {
    throw createError({ statusCode: 403, statusMessage: 'Forbidden' });
  }

  return { message: 'Admin data', userId };
});

// package.json
{
  "scripts": {
    "build": "prisma generate && nuxt build",
    "postinstall": "prisma generate"
  }
}

# 安装 Vercel Analytics
npm install -D @vercel/analytics

// nuxt.config.ts
export default defineNuxtConfig({
  plugins: [
    { src: '~/plugins/analytics.client.ts', mode: 'client' },
  ],
});

// plugins/analytics.client.ts
import { inject } from '@vercel/analytics';

export default defineNuxtPlugin(() => {
  inject();
});

// nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    routeRules: {
      '/**': {
        headers: {
          'X-Frame-Options': 'DENY',
          'X-Content-Type-Options': 'nosniff',
          'Referrer-Policy': 'strict-origin-when-cross-origin',
          'Content-Security-Policy': "default-src 'self'; script-src 'self' 'unsafe-inline'",
        },
      },
    },
  },
});

# 生产环境启用 DevTools（建议只在需要排查时临时开启）
# .env
NUXT_DEVTOOLS_ENABLED=true

// server/api/_.debug.get.ts
export default defineEventHandler(() => {
  const nitro = useNitroApp();
  return {
    routes: Object.keys(nitro.scannedHandlers || {}),
    modules: Object.keys(nitro.modules || {}),
    hooks: nitro.hooks._hooks,
  };
});

# 本地模拟 Vercel 生产环境
npm run build
NUXT_DEVTOOLS_ENABLED=true node .output/server/index.mjs

npm install -D @vercel/analytics

// plugins/analytics.client.ts
import { inject } from '@vercel/analytics';

export default defineNuxtPlugin(() => {
  inject();
});

npm install -D @vercel/speed-insights

// plugins/speed-insights.client.ts
import { injectSpeedInsights } from '@vercel/speed-insights';

export default defineNuxtPlugin(() => {
  injectSpeedInsights();
});

// server/plugins/monitoring.ts
import * as Sentry from '@sentry/node';

export default defineNitroPlugin((nitroApp) => {
  Sentry.init({ dsn: process.env.SENTRY_DSN });

  nitroApp.hooks.hook('error', (error) => {
    Sentry.captureException(error);
  });
});

<script setup>
useHead({
  title: '文章标题 - 我的博客',
  meta: [
    { name: 'description', content: '文章摘要...' },
    { property: 'og:title', content: '文章标题' },
    { property: 'og:image', content: 'https://example.com/cover.jpg' },
  ],
  link: [
    { rel: 'canonical', href: 'https://example.com/posts/hello' },
  ],
});
</script>

<script setup>
const { data: post } = await useFetch('/api/posts/hello');

useHead(() => ({
  title: post.value?.title,
  meta: [
    { name: 'description', content: post.value?.excerpt },
  ],
}));
</script>

# 本地构建并启动预览服务器
npm run build
npx nuxt preview

export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      apiBase: process.env.VERCEL_ENV === 'preview'
        ? 'https://staging-api.example.com'
        : 'https://api.example.com',
    },
  },
});

# .github/workflows/deploy.yml
- uses: actions/cache@v4
  with:
    path: |
      .nuxt
      .output
      node_modules
    key: ${{ runner.os }}-nuxt-${{ hashFiles('**/package-lock.json') }}

- name: Lighthouse CI
  run: |
    npm install -g @lhci/cli
    lhci autorun --upload.target=temporary-public-storage