ByteNoteByteNote
字

字节笔记本

2026年2月22日

AI Elements 安装配置完全指南

#前端技术

AI Elements 是 Vercel 推出的基于 shadcn/ui 的 AI 组件库，本文详细介绍如何在项目中完成环境配置和组件安装。

环境要求

在开始安装 AI Elements 之前，请确保你的开发环境满足以下要求：

  • Node.js: 18 或更高版本
  • React: 19
  • Next.js: 14+（推荐使用 App Router）
  • AI SDK: 已安装并配置
  • shadcn/ui: 已在项目中初始化
  • Tailwind CSS: 4

如果你还没有安装 shadcn/ui，运行任何 AI Elements 安装命令时会自动为你设置。

配置 AI Gateway（推荐）

AI Gateway 是 Vercel 提供的模型访问服务，具有以下优势：

  • 单一 API 密钥访问多个模型提供商
  • 内置故障转移支持
  • 统一计费管理
  • 每月提供 $5 的免费使用额度

获取 API Key

  1. 访问 Vercel AI Gateway 页面
  2. 在控制台中生成 API Key
  3. 将密钥添加到项目根目录的 .env.local 文件中：
bash
AI_GATEWAY_API_KEY=your_api_key_here

安装组件

AI Elements 提供两种安装方式：使用专用的 AI Elements CLI 或标准的 shadcn CLI。

方式一：使用 AI Elements CLI（推荐）

bash
# 使用 npm
npx ai-elements@latest add message

# 使用 pnpm
pnpm dlx ai-elements@latest add message

# 使用 yarn
yarn dlx ai-elements@latest add message

# 使用 bun
bunx ai-elements@latest add message

方式二：使用 shadcn CLI

bash
# 使用 npm
npx shadcn@latest add @ai-elements/message

# 使用 pnpm
pnpm dlx shadcn@latest add @ai-elements/message

# 使用 yarn
yarn dlx shadcn@latest add @ai-elements/message

# 使用 bun
bunx shadcn@latest add @ai-elements/message

常用组件安装命令

bash
# 安装对话组件
npx ai-elements@latest add conversation

# 安装消息组件
npx ai-elements@latest add message

# 安装代码块组件
npx ai-elements@latest add code-block

# 安装提示输入组件
npx ai-elements@latest add prompt-input

# 安装推理显示组件
npx ai-elements@latest add reasoning

# 安装来源引用组件
npx ai-elements@latest add sources

组件默认安装到 @/components/ai-elements/ 目录下（或你在 shadcn 配置中设置的组件目录）。

验证安装

安装完成后，按照以下步骤验证组件是否正常工作：

1. 检查组件文件

确认组件文件已正确添加到项目目录中：

text
components/
└── ai-elements/
    ├── message.tsx
    ├── conversation.tsx
    └── ...

2. 在页面中使用组件

创建一个测试页面验证组件渲染：

tsx
// app/page.tsx
import {
  Message,
  MessageContent,
  MessageResponse,
} from "@/components/ai-elements/message";

export default function Page() {
  return (
    <Message from="assistant">
      <MessageContent>
        <MessageResponse>Hello, world!</MessageResponse>
      </MessageContent>
    </Message>
  );
}

3. 启动开发服务器

bash
npm run dev

访问 http://localhost:3000，确认组件正确渲染且无报错。

技术栈说明

AI Elements 基于以下技术栈构建：

  • React 19: 使用最新的 React 特性，不包含 forwardRef
  • Tailwind CSS 4: 样式方案
  • shadcn/ui: 基础组件和设计系统
  • AI SDK: 与 Vercel AI SDK 深度集成
  • TypeScript: 完整的类型支持

常见问题

组件样式不生效

确保你的项目已正确配置 Tailwind CSS，并且在 tailwind.config.ts 中包含了组件路径：

typescript
content: [
  "./components/**/*.{js,ts,jsx,tsx,mdx}",
  // ...其他路径
],

TypeScript 类型错误

确保你的项目使用 React 19 类型定义：

bash
npm install @types/react@latest @types/react-dom@latest

与现有 shadcn/ui 组件冲突

AI Elements 组件使用独立的命名空间（ai-elements 目录），与现有的 shadcn/ui 组件不会冲突。如果发生样式覆盖问题，可以检查 CSS 导入顺序。

下一步

完成安装后，你可以：

  1. 浏览 AI Elements 组件文档 了解所有可用组件
  2. 查看 使用示例 学习如何在实际项目中使用
  3. 阅读 故障排除指南 解决常见问题

相关资源

前端技术
上一篇

NVIDIA DGX Cloud Lepton：统一的 AI 开发与部署平台

下一篇

AI Elements 安装配置完全指南

分享: