🎨 BoardUI 详细部署教程

BoardUI 是一个专为 AI 智能体界面 (Agentic Interfaces) 设计的 React 设计系统。它包含了构建 AI 产品所需的全套组件（如聊天、思考指示器、智能体日志）和通用仪表盘组件（如表格、图表），并且全部以源代码形式提供。本教程将指导您部署 BoardUI 自带的完整 AI 聊天应用，并将其组件集成到您的 Next.js 项目中。

📋 部署前准备

Node.js 环境：确保已安装 Node.js，推荐使用最新 LTS（长期支持）版本。
API 密钥：您需要至少一个大语言模型提供商的 API 密钥。BoardUI 支持 OpenAI、Anthropic、Google Gemini、OpenRouter、Groq、xAI 等。
（可选）Vercel 账户：如果您想一键部署到生产环境，建议注册 Vercel 账户。

🚀 第一步：一键部署 AI 聊天应用（推荐）

BoardUI 仓库本身就是一个可直接运行的 AI 聊天应用。您可以通过以下两种方式快速启动。

方式一：部署到 Vercel（最快）

这是项目官方推荐的方式，能让您在几分钟内获得一个在线的 AI 聊天界面。

点击项目 README 中的 “Deploy” 按钮，或直接访问 BoardUI 的 Vercel 部署链接。
授权 Vercel 访问您的 GitHub 账户，并导入此仓库。
设置环境变量：在 Vercel 部署配置页面，找到环境变量设置，添加名为 AI_API_KEY 的变量，并将其值设为您的 API 密钥。
点击 “Deploy”。Vercel 会自动构建并部署应用。部署完成后，您将获得一个可公开访问的 .vercel.app 域名。

方式二：本地运行开发服务器

如果您想在本地测试或开发，可以克隆仓库并运行。

# 克隆仓库
git clone https://github.com/BoardUI/boardui.git
cd boardui

# 安装依赖
npm install

# 创建环境变量文件，并填入您的密钥
cp .env.example .env.local
# 编辑 .env.local 文件，将 AI_API_KEY= 后面的内容替换为您的真实密钥

# 启动开发服务器
npm run dev

现在，在浏览器中打开 http://localhost:3000，您应该能看到一个可以正常对话的 AI 聊天界面。

🧩 第二步：将 BoardUI 组件安装到现有项目

BoardUI 最强大的功能是能将其组件以源码形式安装到您现有的 Next.js 项目中，方便您自由定制。

方式一：使用 MCP 服务器（与 AI 代理协作）

如果您使用 Cursor、Claude Code 等支持 MCP 的 AI 编程助手，可以让代理帮您安装。

添加 MCP 服务器：在您的 AI 代理配置中添加 BoardUI 的 MCP 服务器。

{
  "mcpServers": {
    "boardui": {
      "command": "npx",
      "args": ["-y", "boardui@latest", "mcp"]
    }
  }
}

自然语言安装：配置完成后，您可以直接向代理发出指令，例如：
- “安装所有免费的 BoardUI 组件”
- “在仪表盘中添加一个数据表格和统计卡片”

方式二：使用 CLI 命令行工具

您也可以直接在终端中使用 npx 命令安装特定组件。

# 查看所有可用组件
npx boardui@latest list

# 安装单个组件（例如，安装数据表格组件及其依赖）
npx boardui@latest add data-table

# 安装所有免费组件
npx boardui@latest add --all

⚙️ 第三步：核心配置与环境变量

无论是部署应用还是安装组件，您都需要了解一些关键的环境变量。

AI_API_KEY：您的 API 密钥。BoardUI 会根据密钥格式自动识别提供商（OpenAI、Anthropic 等）。
CHAT_MODEL：（可选）指定使用的模型。默认会根据提供商选择性价比高的模型（如 claude-haiku-4-5）。
AI_PROVIDER：（可选）当使用 Mistral、DeepSeek 等密钥格式不明显的提供商时，需要手动设置，如 AI_PROVIDER=mistral。
AI_BASE_URL：（可选）用于指向任何与 OpenAI 兼容的本地服务器（如 Ollama、LM Studio），设置此项需同时指定 CHAT_MODEL。

安全提示：AI_API_KEY 仅在服务端（app/api/chat/route.ts）使用，不会暴露给浏览器。但聊天应用本身是公开的，请务必为您的 API 密钥设置消费上限，以防他人滥用您的部署链接产生意外费用。

🛠️ 第四步：使用 BoardUI 组件构建页面

安装完成后，您就可以像使用普通 React 组件一样，在项目中导入并使用它们了。

// 示例：在页面中使用数据表格组件
import { DataTable } from '@/components/boardui/data-table';

export default function MyPage() {
  return (
    <div>
      <DataTable columns={...} data={...} />
    </div>
  );
}

BoardUI 的组件源码会被复制到您项目的 components 或 ui 目录下，您可以根据需要直接修改这些源文件，完全控制样式和行为。所有组件都基于 Tailwind CSS v4 构建，并使用了 400+ 个语义化设计令牌，确保界面风格统一且易于维护。

📝 快速上手指南

新手体验：使用 方式一 部署完整的 AI 聊天应用，感受 BoardUI 的完整工作流。
组件探索：访问部署后的应用（或运行 npm run dev），在浏览器中查看不同的组件演示和文档。
集成项目：在您现有的 Next.js 项目中，使用 CLI 命令 npx boardui@latest add [组件名] 安装所需组件。
自定义主题：通过修改 styles/theme.css 和 styles/typography.css 文件中的 CSS 变量，您可以轻松调整整个设计系统的颜色、字体和间距。

🔧 常见问题与排障

问题	解决方法
部署后聊天无响应	检查 Vercel 或本地的 `AI_API_KEY` 环境变量是否正确设置。查看服务端日志（Vercel 的 Function Logs）获取详细错误信息。
安装组件时提示依赖冲突	BoardUI 组件设计为独立安装。如果出现依赖版本冲突，尝试在一个干净的项目中先安装 `--all`，或检查您的 Next.js 版本是否兼容（建议 Next.js 14+）。
无法识别 API 密钥提供商	对于非主流提供商（如 Mistral），请显式设置 `AI_PROVIDER=mistral` 环境变量。
如何控制 API 使用成本？	1. 在您的 API 提供商后台为密钥设置硬性消费限额。2. 在 Vercel 项目设置中开启 “部署保护” (Deployment Protection)，为您的站点添加访问密码。
组件安装后样式不生效	确保您的项目正确配置了 Tailwind CSS v4，并且 `postcss.config.mjs` 和 `globals.css` 中正确引入了 BoardUI 的样式入口文件。