# 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 (
{messages.map(m => (
{m.role}: {m.content}
))}
); } ``` --- ## 十二、分析与监控 ### Web Analytics **功能**： - 访客统计 - 页面浏览量 - 跳出率 - 流量来源 - 用户地理分布 **启用方式**： ```typescript // app/layout.tsx import { Analytics } from '@vercel/analytics/react'; export default function RootLayout({ children }) { return ( {children} ); ``` **隐私特性**： - 不使用 Cookie - 匿名化数据 - 不跟踪跨站用户 ### Speed Insights 监控 Core Web Vitals 性能指标。 ```typescript // app/layout.tsx import { SpeedInsights } from '@vercel/speed-insights/next'; export default function RootLayout({ children }) { return ( {children} ); } ``` ### 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 ( Hero ); } ``` ```tsx // 远程图片 export default function Page() { return ( Remote ); } ``` ### 配置远程图片 ```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 # 使用令牌认证 --scope # 指定团队范围 --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: 'Hello', }, ], 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
{post.content}
; } ``` #### 2. 图片优化 ```tsx // 使用响应式图片 Hero ``` #### 3. 字体优化 ```tsx // 使用 next/font import { Inter } from 'next/font/google'; const inter = Inter({ subsets: ['latin'] }); export default function RootLayout({ children }) { return ( {children} ); } ``` ### 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'; ``` --- **文档结束**