XCDesktop/docs/vercel/VERCEL_GUIDE.md

# Vercel 完整指南

> 本文档基于 Vercel 官方文档整理，涵盖 Vercel 平台的所有核心功能和使用方法。

---

## 目录

1. [平台概述](#一平台概述)
2. [快速入门](#二快速入门)
3. [模板市场](#三模板市场)
4. [项目与部署](#四项目与部署)
5. [Git 集成](#五git-集成)
6. [Vercel Functions](#六vercel-functions)
7. [路由中间件](#七路由中间件)
8. [环境变量](#八环境变量)
9. [域名管理](#九域名管理)
10. [存储服务](#十存储服务)
11. [AI SDK](#十一ai-sdk)
12. [分析与监控](#十二分析与监控)
13. [安全功能](#十三安全功能)
14. [图片优化](#十四图片优化)
15. [定时任务](#十五定时任务)
16. [CLI 命令行工具](#十六cli-命令行工具)
17. [REST API](#十七rest-api)
18. [框架支持](#十八框架支持)
19. [部署保护](#十九部署保护)
20. [计费与限制](#二十计费与限制)
21. [最佳实践](#二十一最佳实践)

---

## 一、平台概述

### 什么是 Vercel？

Vercel 是 AI 云平台，为开发者提供构建、部署和扩展 AI 驱动应用的统一平台。支持部署 Web 应用、代理工作负载以及介于两者之间的所有内容。

### 核心特性

- **零配置部署**：支持主流框架的零配置部署
- **全球 CDN**：内容分发至全球数据中心
- **自动 HTTPS**：免费 SSL 证书
- **预览环境**：每次 Git 推送自动生成预览 URL
- **Serverless Functions**：无需管理服务器的后端函数
- **边缘网络**：全球低延迟执行

### 订阅计划

| 计划 | 适用场景 | 价格 |
|------|----------|------|
| **Hobby** | 个人项目、学习 | 免费 |
| **Pro** | 专业开发者、团队 | $20/用户/月 |
| **Enterprise** | 大型企业 | 定制 |

---

## 二、快速入门

### 创建账户

1. 访问 [vercel.com/signup](https://vercel.com/signup)
2. 选择 Git 提供商登录或使用邮箱
3. 完成邮箱和手机验证

### 安装 CLI

```bash
# npm
npm i -g vercel

# pnpm
pnpm i -g vercel

# yarn
yarn global add vercel

# bun
bun i -g vercel
```

### 首次部署

```bash
# 进入项目目录
cd your-project

# 部署到生产环境
vercel --prod
```

### 部署流程

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  本地开发   │ ──▶ │  Git 推送   │ ──▶ │  自动构建   │
└─────────────┘     └─────────────┘     └─────────────┘
                                              │
                                              ▼
                    ┌─────────────┐     ┌─────────────┐
                    │  生成 URL   │ ◀── │  部署成功   │
                    └─────────────┘     └─────────────┘
```

---

## 三、模板市场

### 概述

Vercel Templates 是官方提供的模板市场，包含大量预构建的项目模板，帮助开发者快速启动项目开发。所有模板都是**免费**使用的。

**访问地址**：[vercel.com/templates](https://vercel.com/templates)

### 模板分类

#### 按用途分类

| 类别 | 说明 | 适用场景 |
|------|------|----------|
| **AI** | AI 应用模板 | 聊天机器人、AI Agent、语音接口 |
| **Starter** | 入门模板 | 快速启动新项目 |
| **E-commerce** | 电商模板 | 在线商店、商品展示 |
| **SaaS** | SaaS 应用模板 | 多租户平台、企业应用 |
| **Blog** | 博客模板 | 个人博客、技术文章 |
| **Portfolio** | 作品集模板 | 个人简历、作品展示 |
| **Documentation** | 文档模板 | 技术文档、API 文档 |
| **Backend** | 后端模板 | API 服务、微服务 |
| **CMS** | 内容管理模板 | 内容网站、新闻站点 |
| **Marketing Sites** | 营销网站模板 | 产品官网、落地页 |
| **Authentication** | 认证模板 | 登录系统、用户管理 |
| **Admin Dashboard** | 管理后台模板 | 数据管理、控制面板 |
| **Web3** | 区块链模板 | DApp、NFT 市场 |
| **Monorepos** | 单体仓库模板 | 多包项目管理 |

#### 按技术栈分类

| 类别 | 说明 |
|------|------|
| **Framework** | Next.js、Nuxt、SvelteKit、Astro、Remix 等 |
| **CSS** | Tailwind CSS、CSS Modules、Styled Components 等 |
| **Database** | PostgreSQL、MongoDB、Redis、PlanetScale 等 |
| **CMS** | Contentful、Sanity、Prismic、Strapi 等 |
| **Authentication** | NextAuth.js、Auth0、Clerk、Supabase Auth 等 |

### 热门模板详解

#### 1. Next.js Boilerplate

最基础的 Next.js 起手架模板。

```
技术栈：
- Next.js 14+ (App Router)
- TypeScript
- ESLint + Prettier
- Tailwind CSS

适用场景：
- 快速启动新项目
- 学习 Next.js
- 自定义项目基础
```

**使用方式**：
```bash
# CLI 方式
vercel init nextjs-boilerplate

# 或访问 Dashboard
# vercel.com/templates/next.js/nextjs-boilerplate
```

#### 2. AI Chatbot

Vercel 官方出品的完整 AI 聊天机器人模板。

```
技术栈：
- Next.js App Router
- Vercel AI SDK
- OpenAI / Anthropic / 其他 LLM
- Tailwind CSS
- Supabase（可选，用于数据持久化）

功能特性：
- 流式响应
- 多模型支持
- 聊天历史
- 代码高亮
- Markdown 渲染
```

**使用方式**：
```bash
vercel init ai-chatbot
```

**配置环境变量**：
```bash
# OpenAI
OPENAI_API_KEY=sk-xxx

# 或 Anthropic
ANTHROPIC_API_KEY=sk-xxx
```

#### 3. Next.js Commerce

高性能电商网站模板，支持多种电商平台集成。

```
技术栈：
- Next.js 14
- Shopify Storefront API
- Tailwind CSS
- Framer Motion

功能特性：
- 商品列表与详情
- 购物车
- 结账流程
- 商品搜索
- 响应式设计
- SEO 优化
```

**支持的电商平台**：
- Shopify
- BigCommerce
- Saleor
- Swell
- Vendure

**使用方式**：
```bash
vercel init nextjs-commerce
```

**配置 Shopify**：
```bash
SHOPIFY_STORE_DOMAIN=your-store.myshopify.com
SHOPIFY_STOREFRONT_ACCESS_TOKEN=xxx
```

#### 4. Platforms Starter Kit

多租户 SaaS 平台模板，用于构建类似 Vercel 的平台。

```
技术栈：
- Next.js App Router
- Redis (Upstash)
- Tailwind CSS
- Prisma

功能特性：
- 多租户架构
- 自定义域名
- 子域名路由
- 用户认证
- 计费集成
- Dashboard 管理
```

**使用场景**：
- 博客平台（类似 Medium）
- 电商托管平台
- CMS 托管服务
- 任何需要多租户的 SaaS

**使用方式**：
```bash
vercel init platforms-starter-kit
```

#### 5. Nextra: Docs Starter Kit

Markdown 驱动的文档站点模板。

```
技术栈：
- Next.js
- Nextra
- MDX
- Tailwind CSS

功能特性：
- Markdown/MDX 支持
- 自动侧边栏
- 全文搜索
- 深色模式
- 代码高亮
- 版本管理
```

**使用场景**：
- 技术文档
- API 文档
- 知识库
- 教程网站

**使用方式**：
```bash
vercel init documentation-starter-kit
```

#### 6. Blog Starter Kit

静态博客模板，支持 Markdown 写作。

```
技术栈：
- Next.js
- TypeScript
- Tailwind CSS
- Markdown

功能特性：
- Markdown 写作
- 标签分类
- RSS 订阅
- SEO 优化
- 深色模式
```

**使用方式**：
```bash
vercel init blog-starter-kit
```

#### 7. Next.js Enterprise Boilerplate

企业级 Next.js 模板，包含完整的工程化配置。

```
技术栈：
- Next.js
- TypeScript
- Tailwind CSS
- Radix UI
- ESLint + Prettier
- Jest + Playwright
- Storybook
- GitHub Actions

功能特性：
- 企业级代码规范
- 完整的测试配置
- CI/CD 流程
- 组件文档
- 性能监控
```

**适用场景**：
- 企业项目
- 大型团队协作
- 需要完整工程化的项目

#### 8. Portfolio Starter Kit

个人作品集模板。

```
技术栈：
- Next.js
- TypeScript
- Tailwind CSS
- MDX

功能特性：
- Markdown 管理内容
- 响应式设计
- 深色模式
- SEO 优化
- 项目展示
```

#### 9. Express on Bun / Hono on Bun

后端服务模板，使用 Bun 运行时。

```
Express on Bun:
- Express.js
- Bun 运行时
- TypeScript

Hono on Bun:
- Hono 框架
- Bun 运行时
- TypeScript
- Edge-ready
```

**使用方式**：
```bash
vercel init express-on-bun
vercel init hono-on-bun
```

#### 10. Nuxt AI Chatbot

Nuxt.js 版本的 AI 聊天机器人。

```
技术栈：
- Nuxt 3
- Vercel AI SDK
- Nuxt MDC
- Tailwind CSS
```

### 使用模板的方式

#### 方式一：通过 Dashboard（推荐）

```
1. 访问 vercel.com/templates
2. 浏览或搜索模板
3. 点击模板查看详情
4. 点击 "Deploy" 按钮
5. 系统自动 Fork 到你的 GitHub
6. 自动部署到 Vercel
```

#### 方式二：通过 CLI

```bash
# 列出可用模板
vercel init

# 初始化特定模板
vercel init nextjs-boilerplate
vercel init ai-chatbot
vercel init nextjs-commerce

# 查看模板帮助
vercel init --help
```

#### 方式三：克隆 GitHub 仓库

```bash
# 直接克隆模板仓库
git clone https://github.com/vercel/next.js/tree/canary/packages/create-next-app

# 或从模板创建新仓库
# GitHub → Use this template → Create a new repository
```

### 模板筛选

在模板市场可以使用多种条件筛选：

```
按用途筛选：
- AI
- Starter
- Ecommerce
- SaaS
- Blog
- Portfolio
- CMS
- Backend
- ...

按框架筛选：
- Next.js
- Nuxt
- SvelteKit
- Astro
- Remix
- Vue
- React
- ...

按数据库筛选：
- PostgreSQL
- MongoDB
- MySQL
- Redis
- PlanetScale
- Supabase
- Neon
- ...

按 CMS 筛选：
- Contentful
- Sanity
- Prismic
- Strapi
- WordPress
- ...
```

### 创建自定义模板

你可以将自己的项目变成模板供他人使用：

1. **创建示例仓库**
   ```bash
   # 项目结构清晰
   # 包含 README.md
   # 配置好所有必要文件
   ```

2. **添加模板元数据**
   ```json
   // vercel.json
   {
     "name": "My Template",
     "description": "A custom template",
     "public": true
   }
   ```

3. **提交到 Vercel 模板库**
   - 发送 PR 到 [vercel/templates](https://github.com/vercel/templates)
   - 或在 Vercel Dashboard 标记项目为模板

### 模板最佳实践

#### 选择模板时的考虑

```
1. 技术栈匹配
   - 团队熟悉的框架
   - 项目需求的技术支持

2. 功能完整性
   - 是否包含所需功能
   - 是否需要大量修改

3. 维护状态
   - 最近更新时间
   - 社区活跃度
   - Issue 处理情况

4. 文档质量
   - README 是否清晰
   - 配置说明是否完整
```

#### 使用模板后的步骤

```
1. 阅读模板文档
   - README.md
   - 配置要求
   - 环境变量

2. 安装依赖
   npm install
   # 或
   pnpm install

3. 配置环境变量
   cp .env.example .env.local
   # 编辑 .env.local 填入实际值

4. 本地开发
   npm run dev

5. 自定义修改
   - 修改品牌信息
   - 调整样式
   - 添加功能

6. 部署上线
   git push
   # 或
   vercel --prod
```

### 官方模板仓库

Vercel 官方维护的模板仓库：

| 仓库 | 说明 |
|------|------|
| [vercel/next.js](https://github.com/vercel/next.js) | Next.js 官方示例 |
| [vercel/templates](https://github.com/vercel/templates) | Vercel 模板集合 |
| [vercel/examples](https://github.com/vercel/examples) | 示例项目集合 |

### 模板 vs 从零开始

| 对比项 | 使用模板 | 从零开始 |
|--------|----------|----------|
| 启动速度 | ⚡ 分钟级 | 🐢 小时级 |
| 最佳实践 | ✅ 已内置 | ❌ 需自行配置 |
| 学习成本 | 低 | 高 |
| 自由度 | 中等 | 完全自由 |
| 代码质量 | 取决于模板 | 取决于自己 |

**建议**：
- 快速原型 / 学习 / 中小型项目 → 使用模板
- 特殊需求 / 大型定制项目 → 从零开始

---

## 四、项目与部署

### 项目概念

项目是部署到 Vercel 的应用程序，来自单个 Git 仓库。每个项目可以有多个部署：
- 一个生产部署
- 多个预生产部署

### 创建项目

1. **通过 Dashboard**：点击 "New Project" 按钮
2. **通过 CLI**：`vercel project add`
3. **通过 API**：POST 请求到 `/v9/projects`

### 部署方法

#### 1. Git 部署（推荐）

```bash
# 连接 Git 仓库后，每次推送自动部署
git push origin main
```

#### 2. CLI 部署

```bash
# 预览部署
vercel

# 生产部署
vercel --prod
```

#### 3. Deploy Hooks

用于触发部署的唯一 URL：

```bash
# 创建 Deploy Hook 后
curl -X POST https://api.vercel.com/v1/integrations/deploy/xxx
```

#### 4. REST API 部署

```typescript
const response = await fetch('https://api.vercel.com/v13/deployments', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'my-project',
    files: [...],
    projectSettings: {...}
  })
});
```

### 部署环境

| 环境 | 说明 | URL 格式 |
|------|------|----------|
| **Local** | 本地开发 | `localhost:3000` |
| **Preview** | 预览环境 | `project-branch-hash.vercel.app` |
| **Production** | 生产环境 | `your-domain.com` |

### 管理部署

```bash
# 查看部署列表
vercel list

# 查看部署详情
vercel inspect [deployment-url]

# 重新部署
vercel redeploy [deployment-id]

# 回滚生产部署
vercel rollback [deployment-id]

# 删除部署
vercel remove [deployment-url]
```

---

## 五、Git 集成

### 支持的 Git 提供商

- GitHub（免费/团队/企业云）
- GitLab（免费/Premium/Ultimate/企业）
- Bitbucket（免费/标准/高级）
- Azure DevOps Pipelines

### 连接 Git 仓库

1. 在 Dashboard 点击 "New Project"
2. 选择 Git 仓库
3. 配置项目设置
4. 点击 "Deploy"

### 生产分支

默认规则（优先级从高到低）：
1. `main` 分支
2. `master` 分支
3. Git 仓库的默认分支

**自定义生产分支**：
1. 进入项目 Settings → Environments
2. 选择 Production 环境
3. 修改 Branch Tracking

### 预览分支

所有非生产分支自动创建预览部署：

```
main (生产)     → https://your-domain.com
feature/a (预览) → https://project-feature-a-hash.vercel.app
develop (预览)   → https://project-develop-hash.vercel.app
```

### 私有仓库部署

**Pro 团队**：
- 提交作者必须是团队成员
- 非成员提交需要申请加入

**Hobby 团队**：
- 无法从组织私有仓库部署
- 需要升级到 Pro 或公开仓库

---

## 六、Vercel Functions

### 概述

Vercel Functions 允许运行服务器端代码，无需管理服务器。自动扩展、处理 API 和数据库连接。

### 创建函数

#### 标准方式（推荐）

```typescript
// api/hello.ts
export default {
  fetch(request: Request) {
    return new Response('Hello from Vercel!');
  },
};
```

#### HTTP 方法

```typescript
// api/user.ts
export function GET(request: Request) {
  return new Response(JSON.stringify({ name: 'User' }), {
    headers: { 'Content-Type': 'application/json' }
  });
}

export function POST(request: Request) {
  return new Response('Created', { status: 201 });
}
```

#### Next.js App Router

```typescript
// app/api/hello/route.ts
export function GET(request: Request) {
  return new Response('Hello from Vercel!');
}
```

### 函数配置

```typescript
// api/configured.ts
export const config = {
  runtime: 'nodejs', // 'nodejs' | 'edge' | 'python' | 'go' | 'ruby'
  regions: ['iad1', 'sfo1'], // 部署区域
  maxDuration: 60, // 最大执行时间（秒）
  memory: 1024, // 内存（MB）
};

export default function handler(request: Request) {
  return new Response('Configured function');
}
```

### 运行时支持

| 运行时 | 说明 |
|--------|------|
| **Node.js** | 默认运行时，完整 Node.js API |
| **Edge** | 全球边缘执行，低延迟 |
| **Python** | 支持 Python 函数 |
| **Go** | 支持 Go 函数 |
| **Ruby** | 支持 Ruby 函数 |
| **Bun** | Bun 运行时 |

### 流式响应

```typescript
// api/stream.ts
import { streamText } from 'ai';

export default async function handler(request: Request) {
  const result = await streamText({
    model: 'openai/gpt-4',
    prompt: 'Hello',
  });

  return result.toDataStreamResponse();
}
```

### 函数限制

| 限制 | Hobby | Pro | Enterprise |
|------|-------|-----|------------|
| 最大执行时间 | 10秒 | 60秒 | 900秒 |
| 内存 | 1024 MB | 3008 MB | 自定义 |
| 包大小 | 50 MB | 50 MB | 自定义 |

### 定价

基于以下因素计费：
- **Active CPU**：CPU 使用时间
- **Provisioned Memory**：内存分配
- **Invocations**：调用次数

---

## 七、路由中间件

### 概述

路由中间件在请求被处理之前执行代码，用于：
- 重定向
- 重写 URL
- 添加头部
- 认证检查
- A/B 测试

### 创建中间件

```typescript
// middleware.ts
export default function middleware(request: Request) {
  const url = new URL(request.url);

  // 重定向旧路径
  if (url.pathname === '/old-page') {
    return new Response(null, {
      status: 302,
      headers: { Location: '/new-page' },
    });
  }

  // 添加自定义头部
  const response = new Response('Hello');
  response.headers.set('X-Custom-Header', 'value');
  return response;
}
```

### 配置匹配路径

```typescript
// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  return NextResponse.next();
}

// 配置匹配规则
export const config = {
  matcher: [
    '/api/:path*',  // 匹配 /api/* 路径
    '/admin/:path*', // 匹配 /admin/* 路径
  ],
  runtime: 'edge', // 或 'nodejs'
};
```

### 使用 Edge Config

```typescript
// middleware.ts
import { get } from '@vercel/edge-config';

export default async function middleware(request: Request) {
  // 从 Edge Config 读取功能开关
  const featureEnabled = await get('feature-flag');
  
  if (featureEnabled) {
    return new Response('Feature enabled');
  }
  
  return new Response('Feature disabled');
}
```

### 请求限制

| 限制 | 值 |
|------|-----|
| 最大 URL 长度 | 14 KB |
| 最大请求体长度 | 4 MB |
| 最大请求头数量 | 64 |
| 最大请求头长度 | 16 KB |

---

## 八、环境变量

### 创建环境变量

**通过 Dashboard**：
1. 进入项目 Settings → Environment Variables
2. 添加键值对
3. 选择适用的环境

**通过 CLI**：

```bash
# 添加环境变量
vercel env add DATABASE_URL

# 拉取环境变量到本地
vercel env pull .env.local

# 列出所有环境变量
vercel env ls

# 删除环境变量
vercel env rm DATABASE_URL production
```

### 环境类型

| 环境 | 说明 |
|------|------|
| **Production** | 生产部署时使用 |
| **Preview** | 预览部署时使用 |
| **Development** | 本地开发时使用（`vercel dev`） |

### 代码中使用

```typescript
// 服务端
const dbUrl = process.env.DATABASE_URL;

// 客户端（需要 NEXT_PUBLIC_ 前缀）
const apiKey = process.env.NEXT_PUBLIC_API_KEY;
```

### 预览分支特定变量

可以为特定分支设置不同的变量值：

```bash
# 为 feature 分支设置特定变量
vercel env add API_URL preview --branch feature
```

### 系统环境变量

Vercel 自动注入以下变量：

```bash
VERCEL=1
VERCEL_ENV=production|preview|development
VERCEL_URL=project-hash.vercel.app
VERCEL_REGION=iad1
VERCEL_GIT_PROVIDER=github
VERCEL_GIT_REPO_SLUG=my-repo
VERCEL_GIT_COMMIT_SHA=abc123
VERCEL_GIT_COMMIT_MESSAGE="Initial commit"
```

### 限制

- 每个环境最多 **1000** 个变量
- 总大小限制 **64 KB**
- Edge Function 单个变量限制 **5 KB**

---

## 九、域名管理

### 添加域名

**通过 Dashboard**：
1. 进入项目 Settings → Domains
2. 输入域名
3. 选择验证方式

**通过 CLI**：

```bash
# 添加域名
vercel domains add example.com

# 验证域名
vercel domains inspect example.com
```

### DNS 配置

#### A 记录

```
类型: A
名称: @
值: 76.76.21.21
```

#### CNAME 记录

```
类型: CNAME
名称: www
值: cname.vercel-dns.com
```

### 域名类型

| 类型 | 说明 | 示例 |
|------|------|------|
| **根域名** | 主域名 | `example.com` |
| **子域名** | 域名的子集 | `blog.example.com` |
| **通配符** | 匹配所有子域名 | `*.example.com` |

### 分配域名到分支

```bash
# 将域名分配给特定分支
# staging.example.com → staging 分支
```

1. 进入 Domains 设置
2. 添加域名
3. 选择 Git Branch

### SSL 证书

Vercel 自动为所有域名生成 SSL 证书：
- 自动续期
- 免费
- 支持 Let's Encrypt

```bash
# 查看证书
vercel certs ls

# 手动颁发证书
vercel certs issue example.com
```

---

## 十、存储服务

### 存储产品概览

| 产品 | 用途 | 读取速度 | 写入速度 |
|------|------|----------|----------|
| **Vercel Blob** | 大文件存储 | 快 | 毫秒级 |
| **Edge Config** | 全局配置 | 超快（<1ms） | 秒级 |
| **Marketplace** | 数据库（Postgres/Redis/Mongo） | 取决于提供商 | 取决于提供商 |

### Vercel Blob

用于存储图片、视频等大文件。

```typescript
import { put } from '@vercel/blob';

// 上传文件
const blob = await put('profile.jpg', file, {
  access: 'public',
});

console.log(blob.url); // https://xxx.public.blob.vercel-storage.com/profile.jpg
```

```typescript
import { list, del } from '@vercel/blob';

// 列出文件
const { blobs } = await list();

// 删除文件
await del(blob.url);
```

### Edge Config

用于存储频繁读取、很少更改的数据。

```typescript
import { get } from '@vercel/edge-config';

// 读取值
const featureFlag = await get('new-feature');

// 读取多个值
const values = await get(['feature-a', 'feature-b']);
```

**使用场景**：
- 功能开关
- A/B 测试配置
- 关键重定向
- IP 黑名单

### Marketplace 数据库

通过 Vercel Marketplace 直接配置数据库：

| 类型 | 提供商 |
|------|--------|
| **PostgreSQL** | Neon, Supabase, PlanetScale |
| **Redis/KV** | Upstash, Redis |
| **NoSQL** | MongoDB, DynamoDB |
| **Vector** | Pinecone, Weaviate |

---

## 十一、AI SDK

### 概述

Vercel AI SDK 是构建 AI 应用的 TypeScript 工具包，支持：
- React / Next.js
- Vue / Nuxt
- Svelte / SvelteKit
- Node.js

### 安装

```bash
# 安装 AI SDK
npm install ai

# 安装模型提供商
npm install @ai-sdk/openai
# 或
npm install @ai-sdk/anthropic
```

### 文本生成

```typescript
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

const { text } = await generateText({
  model: openai('gpt-4'),
  prompt: '解释量子纠缠的概念。',
});

console.log(text);
```

### 流式文本生成

```typescript
import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';

const result = await streamText({
  model: openai('gpt-4'),
  prompt: '写一首关于春天的诗。',
});

// 流式输出
for await (const textPart of result.textStream) {
  process.stdout.write(textPart);
}
```

### 结构化输出

```typescript
import { generateObject } from 'ai';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';

const { object } = await generateObject({
  model: openai('gpt-4'),
  schema: z.object({
    name: z.string(),
    ingredients: z.array(z.string()),
    steps: z.array(z.string()),
  }),
  prompt: '生成一个意大利面食谱。',
});
```

### 工具调用

```typescript
import { generateText, tool } from 'ai';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';

const { text } = await generateText({
  model: openai('gpt-4'),
  prompt: '旧金山今天的天气如何？',
  tools: {
    getWeather: tool({
      description: '获取指定位置的天气',
      parameters: z.object({
        location: z.string().describe('位置'),
      }),
      execute: async ({ location }) => ({
        location,
        temperature: 22,
        condition: '晴天',
      }),
    }),
  },
});
```

### 聊天界面（React）

```tsx
'use client';
import { useChat } from 'ai/react';

export default function Chat() {
  const { messages, input, handleInputChange, handleSubmit } = useChat();

  return (
    <div>
      {messages.map(m => (
        <div key={m.id}>
          {m.role}: {m.content}
        </div>
      ))}
      <form onSubmit={handleSubmit}>
        <input value={input} onChange={handleInputChange} />
      </form>
    </div>
  );
}
```

---

## 十二、分析与监控

### Web Analytics

**功能**：
- 访客统计
- 页面浏览量
- 跳出率
- 流量来源
- 用户地理分布

**启用方式**：

```typescript
// app/layout.tsx
import { Analytics } from '@vercel/analytics/react';

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

**隐私特性**：
- 不使用 Cookie
- 匿名化数据
- 不跟踪跨站用户

### Speed Insights

监控 Core Web Vitals 性能指标。

```typescript
// app/layout.tsx
import { SpeedInsights } from '@vercel/speed-insights/next';

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

### Observability

**可观测性仪表板**提供：
- Vercel Functions 性能
- 外部 API 调用
- Edge Requests
- 中间件执行
- ISR 缓存状态

**查看方式**：
1. 进入项目 Dashboard
2. 点击 Observability 标签

### 日志

**构建日志**：永久保存

**运行时日志**：
| 计划 | 保留时间 |
|------|----------|
| Hobby | 1 小时 |
| Pro | 1 天 |
| Enterprise | 3 天 |

```bash
# 查看日志
vercel logs [deployment-url]

# 实时日志
vercel logs [deployment-url] --follow
```

---

## 十三、安全功能

### 安全层

```
┌─────────────────────────────────────────┐
│            用户请求                      │
└─────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────┐
│         DDoS 防护（自动）                │
└─────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────┐
│         WAF（可配置）                    │
└─────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────┐
│         Bot 管理                        │
└─────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────┐
│         部署保护                        │
└─────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────┐
│            应用                        │
└─────────────────────────────────────────┘
```

### DDoS 防护

- 自动启用
- 全平台防护
- 无需配置

### Web Application Firewall (WAF)

**功能**：
- 自定义规则
- 托管规则集
- 速率限制
- AI Bot 过滤

**配置规则**：

```json
// vercel.json
{
  "firewall": {
    "rules": [
      {
        "path": "/api/*",
        "rateLimit": {
          "requests": 100,
          "window": "1m"
        }
      }
    ]
  }
}
```

### Bot 管理

- 自动识别恶意 Bot
- 可配置 Bot 白名单/黑名单
- AI Bot 过滤规则

### 加密

- 所有部署自动 HTTPS
- 自动 SSL 证书
- 端到端加密

---

## 十四、图片优化

### 概述

Vercel 自动优化图片：
- 自动格式转换（WebP、AVIF）
- 响应式尺寸
- 智能压缩
- CDN 缓存

### 使用方式

#### Next.js

```tsx
import Image from 'next/image';

// 本地图片
import hero from './hero.png';

export default function Page() {
  return (
    <Image
      src={hero}
      alt="Hero"
      width={1200}
      height={600}
    />
  );
}
```

```tsx
// 远程图片
export default function Page() {
  return (
    <Image
      src="https://example.com/image.jpg"
      alt="Remote"
      width={800}
      height={400}
    />
  );
}
```

### 配置远程图片

```typescript
// next.config.ts
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'example.com',
        pathname: '/images/**',
      },
    ],
  },
};

export default nextConfig;
```

### 图片 URL 格式

```
/_next/image?url=/image.jpg&w=3840&q=75

参数：
- url: 图片地址
- w: 宽度（像素）
- q: 质量（1-100）
```

### 缓存行为

| 状态 | 说明 |
|------|------|
| HIT | 从缓存返回 |
| MISS | 转换后缓存再返回 |
| STALE | 返回缓存同时后台更新 |

### 最佳实践

- 使用响应式尺寸
- 配置正确的 remotePatterns
- 对于小图标（<10KB）使用 `unoptimized`
- SVG 和 GIF 不需要优化

---

## 十五、定时任务

### 概述

Cron Jobs 用于定时执行任务，如：
- 数据备份
- 发送通知
- 更新订阅

### 配置方式

```json
// vercel.json
{
  "crons": [
    {
      "path": "/api/cron/daily-report",
      "schedule": "0 0 * * *"
    },
    {
      "path": "/api/cron/hourly-check",
      "schedule": "0 * * * *"
    }
  ]
}
```

### Cron 表达式

```
┌───────────── 分钟 (0-59)
│ ┌───────────── 小时 (0-23)
│ │ ┌───────────── 日期 (1-31)
│ │ │ ┌───────────── 月份 (1-12)
│ │ │ │ ┌───────────── 星期 (0-6, 0=周日)
│ │ │ │ │
* * * * *

示例：
0 0 * * *    → 每天午夜
0 */2 * * *  → 每2小时
30 9 * * 1-5 → 工作日早上9:30
```

### 创建 Cron 端点

```typescript
// api/cron/daily.ts
export default async function handler(request: Request) {
  // 验证请求来自 Vercel Cron
  const authHeader = request.headers.get('authorization');
  if (authHeader !== `Bearer ${process.env.CRON_SECRET}`) {
    return new Response('Unauthorized', { status: 401 });
  }

  // 执行任务
  await sendDailyReport();
  
  return new Response('OK');
}
```

### 限制

| 计划 | 每项目限制 |
|------|------------|
| Hobby | 2 个 Cron |
| Pro | 100 个 Cron |
| Enterprise | 100 个 Cron |

---

## 十六、CLI 命令行工具

### 常用命令

#### 部署相关

```bash
# 部署
vercel                    # 预览部署
vercel --prod             # 生产部署

# 查看部署列表
vercel list
vercel list [project-name]

# 查看部署详情
vercel inspect [deployment-url]

# 重新部署
vercel redeploy [deployment-id]

# 回滚
vercel rollback [deployment-id]

# 删除部署
vercel remove [deployment-url]
```

#### 项目管理

```bash
# 列出项目
vercel project ls

# 创建项目
vercel project add

# 查看项目详情
vercel project inspect [project-name]

# 删除项目
vercel project rm [project-name]

# 链接本地目录到项目
vercel link
```

#### 环境变量

```bash
# 列出环境变量
vercel env ls

# 添加环境变量
vercel env add [name]

# 更新环境变量
vercel env update [name] [environment]

# 删除环境变量
vercel env rm [name] [environment]

# 拉取环境变量到本地
vercel env pull
```

#### 域名管理

```bash
# 列出域名
vercel domains ls

# 添加域名
vercel domains add [domain]

# 查看域名详情
vercel domains inspect [domain]

# 购买域名
vercel domains buy [domain]

# 删除域名
vercel domains rm [domain]
```

#### DNS 管理

```bash
# 列出 DNS 记录
vercel dns ls [domain]

# 添加 DNS 记录
vercel dns add [domain] [name] [type] [value]

# 删除 DNS 记录
vercel dns rm [record-id]
```

#### 其他命令

```bash
# 本地开发
vercel dev
vercel dev --port 3000

# 查看日志
vercel logs [deployment-url]
vercel logs [deployment-url] --follow

# 登录
vercel login
vercel login [email]

# 登出
vercel logout

# 查看当前用户
vercel whoami

# 切换团队
vercel switch [team-name]

# 打开项目 Dashboard
vercel open
```

### 全局选项

```bash
--token <token>      # 使用令牌认证
--scope <team>       # 指定团队范围
--yes               # 跳过确认
--version           # 显示版本
--help              # 显示帮助
```

---

## 十七、REST API

### 认证

```bash
# 创建访问令牌
# Dashboard → Settings → Tokens

# 使用令牌
curl -H "Authorization: Bearer YOUR_TOKEN" https://api.vercel.com/v9/projects
```

### 常用端点

#### 项目

```bash
# 列出项目
GET /v9/projects

# 获取项目
GET /v9/projects/{id}

# 创建项目
POST /v9/projects

# 更新项目
PATCH /v9/projects/{id}

# 删除项目
DELETE /v9/projects/{id}
```

#### 部署

```bash
# 列出部署
GET /v13/deployments

# 获取部署
GET /v13/deployments/{id}

# 创建部署
POST /v13/deployments

# 删除部署
DELETE /v13/deployments/{id}
```

#### 环境变量

```bash
# 列出环境变量
GET /v9/projects/{id}/env

# 创建环境变量
POST /v9/projects/{id}/env

# 更新环境变量
PATCH /v9/projects/{id}/env/{key}

# 删除环境变量
DELETE /v9/projects/{id}/env/{key}
```

#### 域名

```bash
# 列出域名
GET /v6/domains

# 添加域名
POST /v6/domains

# 验证域名
POST /v6/domains/{domain}/verify

# 删除域名
DELETE /v6/domains/{domain}
```

### 示例代码

```typescript
// 创建部署
const response = await fetch('https://api.vercel.com/v13/deployments', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.VERCEL_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'my-project',
    files: [
      {
        file: 'index.html',
        data: '<html><body>Hello</body></html>',
      },
    ],
    projectSettings: {
      framework: null,
    },
  }),
});

const deployment = await response.json();
console.log(deployment.url);
```

---

## 十八、框架支持

### 支持的框架

| 框架 | 静态资源 | SSR | ISR | 中间件 | 图片优化 |
|------|:--------:|:---:|:---:|:------:|:--------:|
| **Next.js** | ✓ | ✓ | ✓ | ✓ | ✓ |
| **SvelteKit** | ✓ | ✓ | ✓ | ✓ | ✓ |
| **Nuxt** | ✓ | ✓ | ✓ | ✓ | ✓ |
| **Astro** | ✓ | ✓ | ✓ | ✓ | ✓ |
| **Remix** | ✓ | ✓ | ✗ | ✓ | ✗ |
| **Vite** | ✓ | ✗ | ✗ | ✓ | ✗ |
| **TanStack** | ✓ | ✓ | ✗ | ✓ | ✗ |
| **Create React App** | ✓ | ✗ | ✗ | ✓ | ✗ |

### 功能支持矩阵

**✓ 支持 | ✗ 不支持 | N/A 不适用**

### Build Output API

用于自定义框架集成：

```
.vercel/output/
├── config.json
├── static/
│   └── index.html
├── functions/
│   └── api/
│       └── hello.func/
│           └── index.js
└── prerendered-files/
    └── blog/
        └── post.html
```

---

## 十九、部署保护

### 保护方法

| 方法 | 说明 | 计划可用性 |
|------|------|------------|
| **Vercel Authentication** | 限制 Vercel 用户访问 | 所有计划 |
| **Password Protection** | 密码保护 | Pro + $150/月 或 Enterprise |
| **Trusted IPs** | IP 白名单 | Enterprise |

### 保护范围

| 范围 | 说明 | 保护内容 |
|------|------|----------|
| **Standard Protection** | 标准保护 | 所有部署（生产域名除外） |
| **All Deployments** | 全部保护 | 所有 URL，包括生产域名 |
| **Only Production** | 仅生产 | 仅生产部署 |
| **Only Preview** | 仅预览 | 仅预览部署 |

### 配置保护

1. 进入项目 Settings → Deployment Protection
2. 选择保护方法
3. 选择保护范围
4. 保存设置

### 绕过保护

**Protection Bypass for Automation**：

```bash
# 添加绕过密钥
# Settings → Deployment Protection → Bypass for Automation

# 使用密钥访问
curl -H "x-vercel-protection-bypass: YOUR_SECRET" https://preview.example.com
```

---

## 二十、计费与限制

### 计划限制

#### 通用限制

| 限制 | Hobby | Pro | Enterprise |
|------|-------|-----|------------|
| 项目数量 | 200 | 无限 | 无限 |
| 每日部署次数 | 100 | 6000 | 自定义 |
| 每次部署文件数 | 15000 | 15000 | 自定义 |
| 并发构建 | 1 | 12 | 自定义 |
| 构建时间限制 | 45分钟 | 45分钟 | 45分钟 |
| 磁盘空间 | 23 GB | 23-64 GB | 23-64 GB |
| Cron Jobs/项目 | 2 | 100 | 100 |

#### 包含资源（Pro）

| 资源 | 包含量 |
|------|--------|
| Fast Data Transfer | 1 TB |
| Function Invocations | 1,000,000 |
| Edge Requests | 10,000,000 |
| Edge Config Reads | 1,000,000 |
| Image Optimizations | 10,000/月 |
| Blob Storage | 5 GB |
| Web Analytics Events | 100,000 |

### 按需付费（Pro）

| 资源 | 价格 |
|------|------|
| Fast Data Transfer | 按区域定价 |
| Function Invocations | $0.60/百万次 |
| Edge Requests | 按区域定价 |
| Image Cache Reads | 按区域定价 |
| Blob Simple Operations | 按区域定价 |
| Monitoring Events | $1.20/百万次 |

### 环境变量限制

- 每个环境最多 1000 个变量
- 总大小限制 64 KB
- Edge Function 单变量限制 5 KB

### 域名限制

| 计划 | 域名/项目 |
|------|-----------|
| Hobby | 50 |
| Pro | 无限* |
| Enterprise | 无限* |

*软限制：Pro 100,000，Enterprise 1,000,000

### 日志保留

| 计划 | 构建日志 | 运行时日志 |
|------|----------|------------|
| Hobby | 永久 | 1 小时 |
| Pro | 永久 | 1 天 |
| Enterprise | 永久 | 3 天 |

---

## 二十一、最佳实践

### 性能优化

#### 1. 使用 ISR

```typescript
// app/blog/[slug]/page.tsx
export const revalidate = 60; // 每60秒重新生成

export default async function BlogPost({ params }) {
  const post = await fetchBlogPost(params.slug);
  return <div>{post.content}</div>;
}
```

#### 2. 图片优化

```tsx
// 使用响应式图片
<Image
  src={hero}
  alt="Hero"
  sizes="100vw"
  fill
  priority
/>
```

#### 3. 字体优化

```tsx
// 使用 next/font
import { Inter } from 'next/font/google';

const inter = Inter({ subsets: ['latin'] });

export default function RootLayout({ children }) {
  return (
    <html lang="en" className={inter.className}>
      <body>{children}</body>
    </html>
  );
}
```

### SEO 优化

#### 1. Metadata API

```typescript
// app/layout.tsx
export const metadata = {
  title: {
    default: 'My Website',
    template: '%s | My Website',
  },
  description: 'Description of my website',
  openGraph: {
    title: 'My Website',
    description: 'Description',
    images: ['/og-image.jpg'],
  },
};
```

#### 2. Sitemap

```typescript
// app/sitemap.ts
import { MetadataRoute from 'next';

export default function sitemap(): MetadataRoute.Sitemap {
  return [
    {
      url: 'https://example.com',
      lastModified: new Date(),
    },
    {
      url: 'https://example.com/about',
      lastModified: new Date(),
    },
  ];
}
```

### 开发工作流

```
1. 本地开发
   npm run dev

2. 创建分支
   git checkout -b feature/new-feature

3. 提交并推送
   git add . && git commit -m "Add new feature"
   git push origin feature/new-feature

4. Vercel 自动创建预览部署

5. 合并到 main 后自动生产部署
```

### 监控与调试

```bash
# 查看生产日志
vercel logs your-domain.com

# 查看函数日志
vercel logs your-domain.com --output raw | grep "api/"

# 使用 Speed Insights
// 添加组件到 layout.tsx
import { SpeedInsights } from '@vercel/speed-insights/next';
```

---

**文档结束**