ContextQMD
Back to Lobehub

技术开发上手指南

docs/development/start.zh-CN.mdx

2.2.106.7 KB
Original Source

技术开发上手指南

欢迎来到 LobeHub 技术开发上手指南。LobeHub 是一款基于 Next.js 框架构建的 AI 会话应用，它汇集了一系列的技术栈，以实现多样化的功能和特性。本指南将详细介绍 LobeHub 的主要技术组成，以及如何在你的开发环境中配置和使用这些技术。

基础技术栈

LobeHub 的核心技术栈如下：

  • 框架：Next.js 16 + React 19，为项目提供服务端渲染、Router Handler 等关键功能。
  • 组件库：Ant Design (antd) 作为基础组件库，@lobehub/ui 作为业务组件库。
  • 状态管理：zustand，一款轻量级且易于使用的状态管理库。
  • 数据获取：SWR 用于客户端数据获取。
  • 路由：采用混合路由架构 —— Next.js App Router 处理静态页面（如认证页），React Router DOM 承载主应用 SPA。
  • API：tRPC 实现端到端类型安全的 API 通信。
  • 数据库：Drizzle ORM + PostgreSQL。
  • 国际化：react-i18next 实现多语言支持。
  • 样式：antd-style，与 Ant Design 配套的 CSS-in-JS 库。
  • 单元测试：Vitest 进行单元测试。

文件夹目录架构

LobeHub 采用 Monorepo 架构（@lobechat/ 命名空间），顶层目录结构如下：

bash
lobehub/
├── apps/
│   ├── cli/               # LobeHub CLI
│   ├── desktop/           # Electron 桌面应用
│   └── server/            # 独立服务端（tRPC routers、services、modules）
├── packages/              # 共享包（@lobechat/*）
│   ├── database/          # 数据库 schemas、models、repositories
│   ├── agent-runtime/     # Agent 运行时
│   ├── model-runtime/     # 模型运行时
│   ├── app-config/        # 应用配置文件，包含客户端与服务端环境变量
│   ├── env/               # 环境变量定义和校验（分析、认证、LLM 等）
│   ├── locales/           # 国际化默认语言文件
│   ├── builtin-tools/     # 内置工具注册表（inspectors、interventions 等）
│   └── ...                # 更多共享包
├── src/                   # 主应用源码
│   ├── app/               # Next.js App Router：后端 API 路由 + SPA/认证页 HTML 外壳服务
│   ├── components/        # 可复用的 UI 组件
│   ├── const/             # 应用常量和枚举
│   ├── features/          # 业务功能模块，如 Agent 设置、插件开发弹窗等
│   ├── helpers/           # 工具辅助函数
│   ├── hooks/             # 全应用复用的自定义 Hooks
│   ├── layout/            # 布局组件（AuthProvider、GlobalProvider 等）
│   ├── libs/              # 第三方集成（better-auth、OIDC、tRPC 等）
│   ├── routes/            # SPA 页面片段，按平台分组（(main)/(mobile)/(desktop)/(popup)）
│   ├── server/            # 尚未迁移到 apps/server 的剩余服务端模块
│   ├── services/          # 客户端服务接口
│   ├── spa/               # SPA 入口和 React Router 配置
│   ├── store/             # zustand 状态管理
│   ├── styles/            # 全局样式和 CSS-in-JS 配置
│   ├── types/             # TypeScript 类型定义
│   └── utils/             # 通用工具函数
├── locales/               # 国际化翻译文件（zh-CN、en-US 等）
└── e2e/                   # E2E 测试（Cucumber + Playwright）

有关目录架构的详细介绍，详见： 文件夹目录架构

本地开发环境设置

请参考 开发环境设置指南 了解完整的环境搭建流程， 包括软件安装、项目配置、Docker 服务启动和数据库迁移等步骤。

代码风格与贡献指南

在 LobeHub 项目中，我们十分重视代码的质量和一致性。为此，我们制定了一系列的代码风格规范和贡献流程，以确保每位开发者都能顺利地参与到项目中。以下是你作为开发者需要遵守的代码风格和贡献准则。

  • 代码风格：我们使用 @lobehub/lint 统一代码风格，包括 ESLint、Prettier、remarklint 和 stylelint 配置。请遵守我们的代码规范，以保持代码的一致性和可读性。
  • 贡献流程：我们采用 gitmoji 和 semantic release 作为代码提交和发布流程。请使用 gitmoji 标注您的提交信息，并确保遵循 semantic release 的规范，以便我们的自动化系统能够正确处理版本控制和发布。

所有的贡献都将经过代码审查。维护者可能会提出修改建议或要求。请积极响应审查意见，并及时做出调整，我们期待你的参与和贡献。

详细的代码风格和贡献指南，请参考 代码风格与贡献指南。

国际化实现指南

LobeHub 采用 react-i18next 实现多语言支持，确保用户全球化体验。

默认语言文件位于 packages/locales/src/default/（英文）， 翻译文件位于 locales/ 目录。 开发时只需编辑 packages/locales/src/default/ 中的 key， CI 会自动生成其他语言的翻译文件。

如果要添加新语种，需遵循特定步骤，详见 新语种添加指南。 我们鼓励你参与我们的国际化努力，共同为全球用户提供更好的服务。

详细的国际化实现指南，请参考 国际化实现指南。

附录：资源与参考

为了支持开发者更好地理解和使用 LobeHub 的技术栈，我们提供了一份详尽的资源与参考列表 —— LobeHub 资源与参考 - 访问我们维护的资源列表，包括教程、文章和其他有用的链接。

我们鼓励开发者利用这些资源深入学习和提升技能，通过 LobeHub GitHub Discussions 或者 Discord 加入社区讨论，提出问题或分享你的经验。

如果你有任何疑问，或者需要进一步的帮助，请不要犹豫，请通过上述渠道与我们联系。