跳到主要内容

5 分钟快速上手

这是一个完整的教程，带你从零开始创建一个 Lovrabet 项目。整个过程大约需要 5-10 分钟。

前提条件​

  1. 已安装 Lovrabet CLI：按照 安装指南 完成安装
  2. Windows 用户建议：强烈推荐使用 Git Bash 作为命令行终端
    • 在 Git Bash 中经过完整测试，体验最佳
    • CMD/PowerShell 仅简单兼容，可能遇到部分问题
    • 打开方式：右键点击文件夹 → 选择「Git Bash Here」

确认你的环境：在终端中运行 lovrabet --help，如果能看到帮助信息就说明环境正常。

安装演示

步骤一：创建项目​

方式一：交互式创建（推荐）​

在终端输入以下命令：

lovrabet create

CLI 会引导你完成项目创建，按提示操作即可：

创建项目演示

1. 输入项目名称​

* 项目名: my-app
  直接回车确认，或输入自定义名称
  • 默认名称：my-app（直接按回车使用）
  • 自定义名称：输入你想要的项目名，例如 my-awesome-app
  • 命名规则：只能使用字母、数字、连字符 - 和下划线 _，且必须以字母或数字开头

2. 绑定应用 AppCode（可选）​

* 应用AppCode [可选]:
  绑定应用AppCode可自动配置 API，如: app-c4c89304 (直接回车跳过)
  • 什么是 AppCode？ 后端系统为你的项目分配的唯一标识符，通常格式为 app-xxxxxxxx
  • 如何获取？ 可以向后端同事询问，或在后台管理系统中查看
  • 跳过设置：直接按回车，稍后可通过 lovrabet config set appcode <code> 配置

3. 登录认证（如果需要拉取 API）​

如果你输入了 AppCode，CLI 会检查登录状态：

  • 已登录：会提示 √ 检测到有效登录状态
  • 未登录：会询问 * 是否要先登录以便拉取 API 配置？

选择建议：

  • 选择 Yes - 推荐，可以自动拉取 API 配置，省去后续手动操作
  • 选择 No - 跳过登录，项目创建后需要手动配置 API

登录操作：

  1. CLI 会启动本地服务器
  2. 自动打开浏览器，跳转到登录页面
  3. 在浏览器中输入账号密码完成登录
  4. 返回终端继续创建流程

Windows 用户提示：

  • 浏览器可能不会自动打开，请手动复制终端中显示的链接到浏览器
  • 浏览器可能显示"不安全连接"警告，点击"高级"然后选择"继续访问"

4. 拉取 API 配置（如果已登录）​

登录成功后，CLI 会询问：

* 是否要自动拉取 API 配置？
  ▶ Yes  No
  使用 ←→ 选择，回车确认
  推荐选择 Yes，可自动配置 API 接口

选择建议：

  • 选择 Yes - 推荐，自动生成 API 代码，开箱即用
  • 选择 No - 跳过，稍后可通过 lovrabet api pull 手动拉取

5. 自动创建项目​

确认以上选项后，CLI 会自动执行：

  1. ✅ 复制项目文件（从官方模板）
  2. ✅ 更新项目配置（package.json）
  3. ✅ 安装 npm 依赖
  4. ✅ 格式化代码（Prettier）
  5. ✅ 创建配置文件（.lovrabetrc）
  6. ✅ 拉取 API 配置（如果选择了 Yes）

方式二：直接创建（快速）​

如果你已经知道项目名称，可以直接指定：

lovrabet create my-app

这种方式会跳过交互式引导，直接创建一个名为 my-app 的项目，但不会自动配置 AppCode 和拉取 API。

步骤二：启动项目​

创建完成后，进入项目目录并启动开发服务器：

cd my-app
lovrabet start

启动后会发生什么？

  1. 启动 Vite 开发服务器
  2. 自动打开浏览器
  3. 修改代码后，浏览器会自动刷新（热更新）

步骤三：配置 API（如果未在创建时配置）​

如果你在创建项目时跳过了 AppCode 配置，可以稍后手动配置：

1. 设置 AppCode​

lovrabet config set appcode <你的应用代码>

例如：

lovrabet config set appcode app-c4c89304

2. 拉取 API 配置​

lovrabet api pull

CLI 会询问你想用什么名称保存 API 文件，直接按回车使用默认名称 api 即可。

3. 生成的文件​

执行完成后，你会在 src/api/ 目录下看到：

  • src/api/api.ts - 包含所有 API 接口的定义
  • src/api/client.ts - 封装好的客户端，可直接使用

4. 如何使用 API​

在你的 React 组件或其他 TS/JS 文件中：

import { lovrabetClient } from "@/api/client";

// 例子：调用 API 获取数据
const data = await lovrabetClient.someApiMethod();

步骤四：添加新页面​

如果你想在项目中添加新页面：

lovrabet add page

交互过程​

  1. 选择页面模板：

    • blank - 空白页面，只有基本结构
    • hello-world - 示例页面，包含内容和样式

  2. 输入路由路径：

    • 单级路由：about → 创建 src/pages/about/
    • 多级路由：user/profile → 创建 src/pages/user/profile/

步骤五：打包和预览​

打包生产代码​

lovrabet build

生成的静态文件会保存在 dist/ 目录下。

本地预览打包结果​

lovrabet preview

启动一个本地服务器，预览打包后的效果。

实时打包和预览​

lovrabet preview --watch

监听文件变化，自动重新打包并预览。

步骤六：AI 辅助开发配置（可选）v1.2.5+​

如果你使用 Cursor、Claude Code 等 AI IDE，可以配置 MCP 和 skill，让 AI 能够访问数据集并了解开发规范。

配置 MCP​

让 AI IDE 能够直接访问 Lovrabet 数据集：

# 配置 Cursor
lovrabet mcp install --cursor

# 配置 Claude Code
lovrabet mcp install --claude

安装 skill​

为 AI IDE 安装开发规范和指南：

# 安装 Cursor skill
lovrabet skill install --cursor

# 安装所有 IDE skill
lovrabet skill install --all

配置完成后​

重启你的 IDE，AI 就能够：

  • 查看数据集结构和字段定义
  • 按照正确规范生成代码
  • 避免常见的 API 错误

💡 提示：这是可选配置，不影响正常开发。详细说明请参考 MCP 配置 和 skill 安装

🎉 恭喜你！​

你已经成功完成了从创建项目到本地开发的完整流程。

下一步做什么？​

常见问题​

1. 登录状态会过期吗？​

会的，登录信息会保存在本地文件中（~/.lovrabet/cookie），长时间未使用可能需要重新登录。

2. 如果创建项目时跳过了 API 配置，后续还能添加吗？​

可以，使用以下命令：

lovrabet config set appcode <你的应用代码>
lovrabet api pull

3. 如何查看当前项目的配置？​

lovrabet config list

4. 项目模板是固定的吗？​

是的，目前使用官方统一模板（React + Vite + TypeScript）。