lobehub/lobe-ui · 上手攻略

• 仓库：lobehub/lobe-ui
• 链接：https://github.com/lobehub/lobe-ui
• 分类：AIGC Web UI 组件库
• 作者：Tom
• 更新：2026-08-21

这是什么

Lobe UI 是 LobeHub 团队开源的 React 组件库，专为构建 AIGC（AI Generated Content）Web 应用而设计，基于 Ant Design（Antd）深度定制，兼容 Antd 全部组件，并默认集成 antd-style 作为 CSS-in-JS 方案。

该库是 Lobe Chat（开源 ChatGPT/LLM Web 应用）前端经验的沉淀，提供了 90+ 专为 AI 场景优化的 React 组件，涵盖对话 UI、流式 Markdown 渲染、模型图标、Mermaid 图表、主题切换等 AIGC 应用高频需求。

解决什么问题

从头构建 AI 对话类应用时，开发者通常面临两个痛点：一是通用 UI 框架（如 Material UI、Chakra UI）缺少 AI 场景所需的流式渲染、消息气泡、模型选择器等组件；二是基于 Antd 二次开发需要大量样式覆盖，工作量大。

Lobe UI 的核心价值在于：开箱即用的 AIGC 场景专用组件 + 与 Antd 生态完全兼容 + 主题系统原生支持暗色模式，让开发者可以像搭积木一样快速拼出专业级 AI 应用界面，而不用从零写 CSS。

快速安装

# 使用 pnpm（推荐）
pnpm add @lobehub/ui

# 或使用 bun
bun add @lobehub/ui

# 或使用 npm
npm install @lobehub/ui

⚠️ 版本说明：截至 2026-08，npm 最新稳定版约为 1.170.x（2025-03 发布），建议安装后通过 npm info @lobehub/ui version 确认具体版本号。

Next.js SSR 注意事项

若在 Next.js Page Router 中使用（涉及 SSR），需在 next.config.js 中添加 transpilePackages 配置：

// next.config.js
const nextConfig = {
  transpilePackages: ['@lobehub/ui'],
};
module.exports = nextConfig;

⚠️ 注意：Lobe UI 为 ESM only 包，不支持 CommonJS 直接引用。

核心用法

基础引入与主题

import { ThemeProvider, Button } from '@lobehub/ui';
import { Button as AntdButton } from 'antd';

export default () => (
  <ThemeProvider>
    <Button>Hello AIGC</Button>
    {/* 与 Antd 组件完全兼容 */}
    <AntdButton>Native Antd Button</AntdButton>
  </ThemeProvider>
);

流式 Markdown 渲染

AI 对话应用最核心的组件，支持流式输出中的逐字渲染：

import { Markdown } from '@lobehub/ui';

export default () => (
  <Markdown
    content={`## Hello Streaming markdown…

Streaming markdown with \`inline code\`:

- GFM tables and lists
- KaTeX math
- Mermaid charts
    `}
  />
);

国际化（I18n）

import { I18nProvider } from '@lobehub/ui';
import formMessages from '@lobehub/ui/i18n/resources/form';
import hotkeyMessages from '@lobehub/ui/i18n/resources/hotkey';

<I18nProvider resources={[formMessages, hotkeyMessages]}>
  <App />
</I18nProvider>

动效配置（Motion）

AIGC 场景大量使用动画，Lobe UI 要求通过 ConfigProvider 注入 motion 组件：

// 方式一：直接 motion（适合 Next.js App Router）
import { ConfigProvider } from '@lobehub/ui';
import { motion } from 'motion/react';

export default () => (
  <ConfigProvider motion={motion}>
    <App />
  </ConfigProvider>
);

// 方式二：LazyMotion（性能优化方案）
import { ConfigProvider } from '@lobehub/ui';
import { LazyMotion, domAnimation } from 'motion/react';
import * as m from 'motion/react-m';

export default () => (
  <LazyMotion features={domAnimation}>
    <ConfigProvider motion={m}>
      <App />
    </ConfigProvider>
  </LazyMotion>
);

典型适用场景

坑与注意

1. ESM Only：包不导出 CommonJS 格式，若使用 CJS 项目（如较老版本的 Next.js），需通过 transpilePackages 或降级方案处理。
2. Antd 版本依赖：组件基于 Antd 开发，升级 Antd 大版本时建议同步确认 Lobe UI 兼容性（官方文档标注支持 antd 5.x）。
3. Motion 必填：ConfigProvider 必须传入 motion 参数，缺省会导致动画报错。若项目不需要动画，传入 false 或使用 domAnimation 占位。
4. SSR 限制：部分组件依赖浏览器 API（如 window、document），在 Next.js SSR 时需注意动态导入。
5. 主题覆盖：Lobe UI 使用 antd-style 做 CSS-in-JS，主题定制通过 ThemeProvider 的 theme prop 传入，修改前建议阅读 antd-style 文档。

与同类对比

一句话结论：如果你在构建 AI 对话类应用，Lobe UI 是目前开源生态中 AIGC 场景组件最完整、Antd 兼容性最好的选择，比 shadcn/ui 更专注于 AI 场景，比自研 UI 省去 60%+ 的组件开发时间。

相关资源

• 官方文档：https://ui.lobehub.com
• 组件演示场：https://ui.lobehub.com（每个组件均有在线可交互示例）
• GitHub：https://github.com/lobehub/lobe-ui
• 图标库：@lobehub/icons（300+ AI 模型/服务商 SVG 图标）
• 图表库：@lobehub/charts
• TTS 库：@lobehub/tts