# Vercel Development Best Practices ## 概述该技能提供了在 Vercel 上开发和部署应用程序的全面指南，重点关注 Next.js、React 服务器组件、Edge Functions 和 Vercel AI SDK。 ## 核心原则 * 使用准确的示例编写简洁、技术性的 TypeScript 代码 * 使用函数式和声明式编程模式；避免上课 * 最小化“use client”、“useEffect”和“setState”；支持 React 服务器组件 (RSC) * 使用移动优先方法通过 Tailwind CSS 实施响应式设计 * 优化核心网络生命和性能 ## 项目结构我的应用程序/ ├── app/ # App Router 页面和布局 │ ├── (auth)/ # 路由组 │ ├── api/ # API 路由 │ ├──layout.tsx # 根布局 │ └── page.tsx # 主页 ├── Components/ # React 组件 │ ├── ui/ # UI 基元 │ └── features/ # 特征组件 ├── lib/ # 实用函数 ├── hooks/ # 自定义 React 钩子 ├── types/ # TypeScript 类型 ├── public/ # 静态资产 └── vercel.json # Vercel 配置 ## Next.js App Router Guidelines ### 文件命名约定 * 使用小写字母和破折号表示目录（例如，`components/auth-wizard`） * 更喜欢组件和函数的命名导出 * 使用 `page.tsx` 作为路由页面，使用 `layout.tsx` 作为布局 * 使用 `loading.tsx` 表示加载状态，使用 `error.tsx` 表示错误边界 ### 服务器组件（默认） // 应用程序/用户/page.tsx import { getUsers } from '@/lib/data'; 导出默认异步函数 UsersPage() { const 用户 = 等待 getUsers(); 返回（ <主要>

用户

{user.name}

）； } ### 客户端组件（需要时） '使用客户端'；从'react'导入{useState}； export function Counter() { const [count, setCount] = useState(0); 返回（ <按钮 onClick={() => setCount(c => c + 1)}> 计数：{计数} ）； } ## TypeScript 标准 ### 类型定义 // 对对象形状使用接口而不是类型界面用户{ id：字符串；名称：字符串；电子邮件：字符串；创建于：日期； } // Use types for unions and complex types type Status = 'pending' | '活跃' | '不活跃'； // 避免枚举； use const objects instead 常量状态 = { 待处理：“待处理”，活动：'活动'， INACTIVE: '不活跃', 作为常量；类型 StatusValue = STATUS 类型[STATUS 类型键]; ### 组件道具接口 ButtonProps { 孩子：React.ReactNode；变体？： '主要' | '次要' | '鬼'; 尺寸？： 'sm' | 'md' | 'lg'; 禁用？：布尔值； onClick?: () => void; } 导出函数按钮({ 孩子们，变体='主要'，大小='md', 禁用=假，单击时， }: 按钮属性) { // 实现 } ## API 路由 ### 路由处理程序 // 应用程序/api/users/route.ts 从 'next/server' 导入 { NextRequest, NextResponse }; 从 'zod' 导入 { z }； const CreateUserSchema = z.object({ 名称：z.string().min(1), 电子邮件：z.string().email(), }); 导出异步函数 GET(请求: NextRequest) { const 用户 = 等待 getUsers(); 返回 NextResponse.json(用户); } 导出异步函数 POST(request: NextRequest) { 尝试{ const body =等待request.json(); const 已验证 = CreateUserSchema.parse(body); const user =等待createUser（已验证）；返回 NextResponse.json(用户, { 状态: 201 }); } 捕获（错误）{ if (z.ZodError 错误实例) { 返回 NextResponse.json( { error: '验证失败', 详细信息: error.errors }, { 状态：400 } ）； } 返回 NextResponse.json( { error: '内部服务器错误' }, { 状态：500 } ）； } } ### 边缘运行时 // 应用程序/api/edge-function/route.ts 导出常量运行时='边缘'；导出异步函数 GET(请求: 请求) { return new Response(JSON.stringify({ message: '来自边缘的你好！' }), { headers: { 'Content-Type': 'application/json' }, }); } ## Vercel AI SDK Integration ### 流媒体聊天界面 '使用客户端'；从 'ai/react' 导入 { useChat } ；导出函数 Chat() { const { 消息、输入、handleInputChange、handleSubmit、isLoading } = useChat({ api: '/api/聊天', }); 返回（

{messages.map(消息=>(

{消息.内容}

))}

）； } ### AI API路线 // 应用程序/api/chat/route.ts 从'@ai-sdk/openai'导入{openai}； import { streamText } from 'ai'; 导出异步函数 POST(request: Request) { const { messages } = await request.json(); const result = await streamText({ 型号：openai('gpt-4-turbo'), 消息， system: 'You are a helpful assistant.', }); return result.toDataStreamResponse(); } ### AI 错误处理 import { openai } from '@ai-sdk/openai'; import { streamText } from 'ai'; 导出异步函数 POST(request: Request) { 尝试{ const { messages } = await request.json(); const result = await streamText({ 型号：openai('gpt-4-turbo'), 消息， }); return result.toDataStreamResponse(); } 捕获（错误）{ // 处理速率限制 if (error.message?.includes('rate limit')) { return new Response('超出速率限制。请稍后再试。', { 状态：429， }); } // 处理超出配额 if (error.message?.includes('quota')) { return new Response('API 配额超出。', { status: 402 }); } // Fallback to alternative model console.error('Primary model failed:', error); return new Response('服务暂时不可用。', { status: 503 }); } } ## 数据获取 ### Server-Side Data Fetching // 获取服务器组件中的数据异步函数 getData() { const res = 等待 fetch('https://api.example.com/data', { next: { revalidate: 3600 }, // 缓存1小时 }); 如果（！res.ok）{ throw new Error('Failed to fetch data'); } 返回 res.json(); } 导出默认异步函数 Page() { const data = 等待 getData(); return

{/* Render data */}

; } ### URL State Management // Use URL query parameters for server state 从 'next/navigation' 导入 { useSearchParams, useRouter }; 导出函数 Filters() { const searchParams = useSearchParams(); const 路由器 = useRouter(); const updateFilter = (键: 字符串, 值: 字符串) => { const params = new URLSearchParams(searchParams); params.set(key, value); router.push(`?${params.toString()}`); }; return (/* Filter UI */); } ## 性能优化 ### 图像优化 import Image from 'next/image'; export function Hero() { 返回（ <图片 src="/英雄.jpg" alt="英雄形象" 宽度={1200} 高度={600} priority // 立即加载 LCP 占位符=“模糊” 模糊DataURL =“数据：图像/ jpeg;base64，...” /> ）； } ### Dynamic Imports 从“下一个/动态”导入动态； // 延迟加载重组件 const HeavyChart = 动态(() => import('@/components/heavy-chart'), { loading: () =>

Loading chart...

, ssr: false, // Disable SSR if needed }); ### 悬念边界从'react'导入{Suspense}；导出默认函数 Page() { 返回（

仪表板

}> <异步组件/>

）； } ## 错误处理 ### 错误边界 // app/error.tsx '使用客户端'；导出默认函数Error({ 错误，重置， }：{ 错误：错误&{摘要？：字符串}；重置：() => 无效； }) { 返回（

出了点问题！

）； } ### 全局错误处理程序 // app/global-error.tsx '使用客户端'；导出默认函数 GlobalError({ 错误，重置， }：{ 错误：错误&{摘要？：字符串}；重置：() => 无效； }) { 返回（ <正文>

出了点问题！

）； } ## Vercel Configuration ### vercel.json { “框架”：“nextjs”， "regions": ["iad1"], "crons": [ { “路径”：“/api/cron/cleanup”， "schedule": "0 0 * * *" } ], “标题”：[ { "source": "/api/(.*)", “标题”：[ { "key": "Access-Control-Allow-Origin", "value": "*" } ] } ] } ### 环境变量 // Use environment variables for sensitive data const apiKey = process.env.API_KEY; const publicUrl = process.env.NEXT_PUBLIC_APP_URL; // Validate required env vars 如果（！apiKey）{ throw new Error('需要 API_KEY 环境变量'); } ## 部署 ### Preview Deployments * Every pull request gets a preview deployment * Use preview URLs for testing and review * 与利益相关者分享预览链接 ### 生产部署 # Connect repo to Vercel (one-click from GitHub) # Or use Vercel CLI vercel --prod ### 边缘配置从 '@vercel/edge-config' 导入 { get } ；导出异步函数 getFeatureFlag(flag: string) { const flags = wait get('featureFlags'); 返回标志？.[标志] ??错误的; } ## 用户界面和样式 ### Tailwind CSS 设置 // 使用移动优先的响应式设计导出函数 Card({ 孩子 }: { 孩子: React.ReactNode }) { 返回（

{孩子}

）； } ### Shadcn UI 组件从'@/components/ui/button'导入{Button}；从 '@/components/ui/dialog' 导入 { Dialog, DialogContent, DialogTrigger }; 导出函数ConfirmDialog() { 返回（ <对话框> <按钮变体=“破坏性”>删除 <对话内容>

你确定吗？

）； } ## 辅助功能 ### 最佳实践导出函数 AccessibleButton() { 返回（ <按钮 aria-label="关闭对话框" aria-expanded={isOpen} aria-controls="对话框内容" className="焦点:ring-2 焦点:ring-offset-2 焦点:ring-blue-500" >

维塞尔发展

包含技能