---
title: 技术开发上手指南
description: 了解 LobeHub 的技术栈和开发环境设置，快速上手开发。
tags:
  - LobeHub
  - 技术开发
  - Next.js
  - 国际化
  - 状态管理
---

# 技术开发上手指南

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

## 基础技术栈

LobeHub 的核心技术栈如下：

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

## 文件夹目录架构

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

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

有关目录架构的详细介绍，详见： [文件夹目录架构](/zh/docs/development/basic/folder-structure)

## 本地开发环境设置

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

## 代码风格与贡献指南

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

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

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

详细的代码风格和贡献指南，请参考 [代码风格与贡献指南](/zh/docs/development/basic/contributing-guidelines)。

## 国际化实现指南

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

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

如果要添加新语种，需遵循特定步骤，详见 [新语种添加指南](/zh/docs/development/internationalization/add-new-locale)。 我们鼓励你参与我们的国际化努力，共同为全球用户提供更好的服务。

详细的国际化实现指南，请参考 [国际化实现指南](/zh/docs/development/internationalization/internationalization-implementation)。

## 附录：资源与参考

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

我们鼓励开发者利用这些资源深入学习和提升技能，通过 [LobeHub GitHub Discussions](https://github.com/lobehub/lobehub/discussions) 或者 [Discord](https://discord.com/invite/AYFPHvv2jT) 加入社区讨论，提出问题或分享你的经验。

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