用途
该技能是一份面向 Vercel 平台开发与部署的实践指南,聚焦 Next.js、React Server Components(RSC)、Edge Functions 与 Vercel AI SDK。它以 TypeScript 代码示例的形式,给出项目结构、编码规范、数据获取、性能优化、错误处理与部署配置等方面的建议,供开发者在构建和上线 Vercel 应用时参考。
主要能力与内容
核心原则
- 编写简洁、技术性的 TypeScript 代码,示例准确。
- 采用函数式与声明式编程模式,避免使用类。
- 尽量减少 'use client'、'useEffect' 与 'setState',优先使用 React Server Components。
- 使用 Tailwind CSS 以移动优先方式实现响应式设计。
- 针对 Core Web Vitals 与性能进行优化。
项目结构
给出 my-app 目录示例,包含 app/(App Router 页面与布局,含 (auth) 路由组、api 路由、layout.tsx、page.tsx)、components/(ui 与 features)、lib/、hooks/、types/、public/ 以及 vercel.json。
Next.js App Router 约定
- 目录使用小写加连字符(如 components/auth-wizard)。
- 组件与函数优先使用具名导出。
- page.tsx 用于路由页面,layout.tsx 用于布局,loading.tsx 用于加载状态,error.tsx 用于错误边界。
- 默认使用 Server Components(示例展示在页面中直接 await 数据);仅在需要时使用 Client Components(示例为带 useState 的计数器)。
TypeScript 规范
- 对象形状使用 interface,联合与复杂类型使用 type。
- 避免 enum,改用 const 对象(示例为 STATUS 常量与 typeof 派生类型)。
- 给出组件 Props 的 interface 示例(ButtonProps,含 variant、size、disabled、onClick 等)。
API 路由与 Edge Runtime
- Route Handlers 示例:app/api/users/route.ts 中使用 NextRequest、NextResponse 与 zod 做请求校验,区分 GET 与 POST,并对 ZodError 返回 400、其他错误返回 500。
- Edge Runtime 示例:通过 export const runtime = 'edge' 声明,返回 JSON Response。
Vercel AI SDK 集成
- 流式聊天 UI:使用 'use client' 与 ai/react 的 useChat,展示 messages、input、handleInputChange、handleSubmit、isLoading 的用法。
- AI API Route:使用 @ai-sdk/openai 的 openai 与 ai 的 streamText,返回 result.toDataStreamResponse()。
- AI 错误处理:针对 rate limit 返回 429、quota 返回 402,其他情况记录日志并返回 503。
数据获取
- 服务端数据获取:在 Server Components 中 fetch,使用 next: { revalidate: 3600 } 缓存 1 小时,非 ok 响应抛出错误。
- URL 状态管理:使用 next/navigation 的 useSearchParams 与 useRouter,通过 URLSearchParams 更新查询参数。
性能优化
- 图片优化:使用 next/image,设置 width、height、priority(用于 LCP)、placeholder="blur" 与 blurDataURL。
- 动态导入:使用 next/dynamic 懒加载重型组件,可配置 loading 与 ssr: false。
- Suspense 边界:用 Suspense 包裹异步组件并提供 fallback。
错误处理
- 错误边界:app/error.tsx 中接收 error 与 reset,提供重试按钮。
- 全局错误处理:app/global-error.tsx 返回完整 html/body 结构。
Vercel 配置
- vercel.json 示例:framework 为 nextjs、regions 为 ["iad1"]、crons 定时任务(/api/cron/cleanup,schedule "0 0 * * ")、headers 为 /api/(.) 设置 Access-Control-Allow-Origin。
- 环境变量:使用 process.env 读取敏感数据,区分 NEXT_PUBLIC_ 前缀的公开变量,并对必需变量做校验。
部署
- 预览部署:每个 pull request 生成预览部署,使用预览 URL 测试与评审,并与相关方分享链接。
- 生产部署:可从 GitHub 一键连接仓库,或使用 Vercel CLI 执行 vercel --prod。
- Edge Config:使用 @vercel/edge-config 的 get 读取 featureFlags。
UI 与样式
- Tailwind CSS:移动优先响应式设计示例(p-4 md:p-6 lg:p-8)。
- Shadcn UI:使用 @/components/ui/button 与 dialog 组件构建确认对话框。
无障碍访问
- 示例展示 aria-label、aria-expanded、aria-controls、focus ring 以及 aria-hidden 图标。
常见反模式
列出应避免的做法:不必要地使用 'use client'、未实现错误边界、忽略 Core Web Vitals 优化、未严格使用 TypeScript、硬编码环境变量、异步组件缺少 Suspense 边界、未优化图片、忽略无障碍要求。
使用方式
该技能以文档与代码示例形式提供,未提供安装命令或调用方式,具体使用步骤暂未提供。开发者可依据其中的示例与约定,在 Next.js + Vercel 项目中参照实践。
适用场景
适用于在 Vercel 上开发与部署 Next.js 应用、使用 React Server Components 与 Edge Functions、集成 Vercel AI SDK 构建流式 AI 聊天、以及需要性能优化、错误处理与部署配置参考的场景。
限制
资料未说明该技能的运行环境、依赖版本、安装方式、收费情况或平台限制,这些信息暂未提供。