SuperAPI AI 工具集

vercel-development

部署与运维

查看项目

更新于 10-15 12:26

技能介绍

用途

该技能是一份面向 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 聊天、以及需要性能优化、错误处理与部署配置参考的场景。

限制

资料未说明该技能的运行环境、依赖版本、安装方式、收费情况或平台限制,这些信息暂未提供。