技术开发上手指南
先按目标选择入口:修改 LobeHub 源码、从终端操作现有实例,以及通过 API 集成应用,需要不同的准备工作。本页后续内容面向源码开发与贡献。
选择开发路径
| 目标 | 入口 | 边界 |
|---|---|---|
| 修改界面、服务端或运行时 | 开发环境设置,再阅读下方技术栈和目录结构 | 需要源码开发环境;仅使用 CLI 或 API 不必搭建完整开发环境。 |
| 从终端操作现有 LobeHub 实例 | CLI README,任务示例见任务工具 | README 包含源码构建、链接命令和服务器配置。使用已安装的 CLI 前,核对版本、目标服务器及账户权限。 |
| 基于公开 API 开发 | 公开 API 指南:鉴权、scope、错误、流式、Webhook 与 SDK 示例 | 每项能力标明「已可用」或「即将推出」;目标部署支持哪些接口,以它自己的 /api/v1/openapi.json 为准。 |
| 用 HTTP 集成应用 | OpenAPI 规范 | 按目标部署支持的公开 REST API、认证方式和参数调用;应用内部路由不等于公开 API 契约。 |
| 用 TypeScript 集成应用 | 官方 SDK README | @lobehub/sdk 基于 OpenAPI 生成;方法、认证和流式处理以对应版本的 README 与规范为准。不要假定所有界面或 CLI 功能都有 SDK 方法。 |
| 理解应用内部聊天调用 | Chat API 内部实现 | 供源码阅读和调试,不是外部应用的接口接入教程。 |
CLI 与执行环境
已安装 CLI 时,可先运行 lh --help 查看命令。CLI README 中的本地构建命令面向 apps/cli 开发,不应当作所有用户通用的安装流程。
2026-05-04 更新描述的是当时仅桌面端可用的 Claude Code / Codex 调度,并不是定时任务表单的发布依据。2026-05-11 更新随后说明云端异构 Agent 和 lh hetero exec;2026-06-22 更新说明 lh update。这些记录不能用来推断所有部署都具备相同工具、命令或执行环境。
以上入口依据 2026-09-14 核对的仓库快照。接入前核对实际安装版本;不要将 /webapi/chat/[provider] 或内部 tRPC 路由当作稳定的公开接口。
基础技术栈
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 实现多语言支持。
- 样式:
@lobehub/ui,组件自带样式;业务代码使用其createStaticStyles+cssVartoken。 - 单元测试:Vitest 进行单元测试。
文件夹目录架构
LobeHub 采用 Monorepo 架构(@lobechat/ 命名空间),顶层目录结构如下:
有关目录架构的详细介绍,详见: 文件夹目录架构
本地开发环境设置
请参考 开发环境设置指南 了解完整的环境搭建流程, 包括软件安装、项目配置、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 加入社区讨论,提出问题或分享你的经验。
如果你有任何疑问,或者需要进一步的帮助,请不要犹豫,请通过上述渠道与我们联系。