跳到主要内容

故障排查

遇到问题了吗？不用担心！这里收集了最常见的问题和解决方案。大部分问题都能在这里找到答案。

快速诊断​

在深入排查之前，先试试这些通用解决方法：

  1. 检查终端环境 （Windows 用户建议）
    • Windows: 推荐使用 Git Bash，CMD/PowerShell 仅简单兼容
    • macOS/Linux: 任意终端均可
  2. 检查 Node.js 版本: node --version（需要 >= 20）
  3. 查看 CLI 日志: lovrabet logs
  4. 重新登录: lovrabet auth
  5. 检查配置: lovrabet config list

环境兼容性问题​

💻 Windows 终端环境问题​

现象描述：

  • 在 Windows CMD 中部分命令执行异常
  • 在 PowerShell 中遇到路径或环境变量问题
  • 中文显示乱码或编码问题

推荐解决方案：

📝 建议：优先使用 Git Bash

  1. 安装 Git for Windows

    # 访问 https://git-scm.com/download/win 下载安装

  2. 打开 Git Bash

    • 方式一：右键点击文件夹 → “Git Bash Here”
    • 方式二：开始菜单搜索 “Git Bash”

  3. 验证环境

    # 在 Git Bash 中运行，确认输出包含 bash
    echo $0

    # 测试 CLI 命令
    lovrabet --help

  4. 各终端支持情况

    • ✅ Git Bash - 完全测试验证，推荐使用
    • ⚠️ Windows CMD - 基础功能可用，未充分测试
    • ⚠️ PowerShell - 基础功能可用，可能有部分限制
    • ⚠️ Windows Terminal - 取决于具体配置的 shell 类型

安装相关问题​

🙅‍♂️ Node.js 版本太旧​

错误现象：

  • 安装 CLI 时报错
  • 提示语法不支持
  • 命令无法正常执行

解决方法：

# 1. 检查当前 Node.js 版本
node --version

# 2. 如果版本 < 20，需要升级
# 访问 https://nodejs.org/，下载最新 LTS 版本

# 3. 安装完成后重新安装 CLI
npm install --global @lovrabet/cli

Windows 用户特别注意：

  • 安装 Node.js 后，关闭所有 Git Bash 窗口并重新打开
  • 必须在 Git Bash 中验证：node --version
  • 如果在 CMD 中看到 Node.js 但在 Git Bash 中没有，可能需要重启电脑

📦 无法下载 Lovrabet CLI​

错误现象：

  • npm install --global @lovrabet/cli 报 404 错误
  • 提示 package not found
  • 网络连接超时

解决方法：

  1. 检查 npm 源配置

    # 查看 npm 配置
    npm config list

    # 检查 ~/.npmrc 文件
    cat ~/.npmrc

  2. 配置私有仓库

    # 在 ~/.npmrc 中添加（请联系管理员获取正确地址）
    @lovrabet:registry=https://your-private-registry.com/

  3. 网络问题

    • 检查网络连接
    • 关闭 VPN 或代理
    • 联系 IT 支持解决企业防火墙问题

登录认证问题​

🔐 登录一直失败​

错误现象：

  • 每次都提示需要重新登录
  • 浏览器无法打开本地地址
  • 登录后仍然提示未授权

解决方法：

  1. 清理登录缓存

    # 删除登录信息文件
    rm -rf ~/.lovrabet/

    # 重新登录
    lovrabet auth

  2. 浏览器问题

    • Chrome/Edge: 点击“高级” → “继续访问”
    • Firefox: 点击“高级” → “添加例外”
    • Safari: 点击“显示详细信息” → “访问网站”

  3. 系统安全软件

    • 暂时关闭防火墙或杀毒软件
    • 将 CLI 添加到信任列表
    • 在公司网络下可能需要联系 IT 管理员

API 相关问题​

🌐 API 拉取失败​

错误现象：

  • 提示“请先配置应用 Code”
  • 提示 Cookie 无效或过期
  • 网络请求超时或失败

解决方法：

  1. 检查登录状态

    # 重新登录
    lovrabet auth

    # 确认登录成功后再试
    lovrabet api pull

  2. 检查应用配置

    # 查看当前配置
    lovrabet config list

    # 设置应用代码
    lovrabet config set app your-app-code

    # 或者直接传参
    lovrabet api pull your-app-code

  3. 网络问题

    # 检查网络连接
    ping api.lovrabet.com

    # 稍后重试
    lovrabet api pull

开发运行问题​

🚀 开发服务器启动失败​

错误现象：

  • lovrabet start 命令报错
  • Vite 无法启动
  • 端口被占用

解决方法：

  1. 检查项目依赖

    # 检查 package.json 中是否有 vite
    cat package.json | grep vite

    # 如果没有，重新安装依赖
    npm install
    # 或
    yarn install

  2. 端口冲突

    # 查看占用 5173 端口的进程
    lsof -i :5173

    # 终止占用端口的进程
    kill -9 <process-id>

    # 或者指定其他端口
    PORT=3000 lovrabet start

  3. 查看详细日志

    # 查看 CLI 日志
    lovrabet logs

    # 或者直接运行 vite
    npx vite

页面生成问题​

📄 页面创建失败​

错误现象：

  • 路由路径格式不正确
  • 提示目录已存在
  • 模板文件损坏或丢失

解决方法：

  1. 检查路由格式

    # 正确示例
    about
    user/profile
    admin/user/list

    # 错误示例
    /about        # 不能以 / 开头
    about/        # 不能以 / 结尾
    user profile  # 不能包含空格
    user@profile  # 不能包含特殊符号

  2. 处理目录冲突

    # 检查是否已存在
    ls src/pages/user/profile

    # 如果存在，使用不同的路径
    # 或者删除后重新创建
    rm -rf src/pages/user/profile
    lovrabet add page

  3. 模板问题

    # 检查 CLI 模板文件是否完整
    # 如果遇到模板错误，可能需要重新安装 CLI
    npm install --global @lovrabet/cli

配置管理问题​

📁 多项目切换配置​

问题现象：

  • 同时开发多个 Lovrabet 项目
  • 切换项目后配置混乱
  • 不同项目使用不同的 appCode

解决方法：

# 方式一：使用不同工作目录（推荐）
# CLI 配置存储在项目根目录的 .lovrabet/ 中
cd project-a
lovrabet config set app app-a-code

cd project-b
lovrabet config set app app-b-code

# 方式二：环境变量指定
export LOVRABET_APP_CODE=your-app-code
lovrabet api pull

# 方式三：命令行参数
lovrabet api pull --app your-app-code

# 查看当前项目配置
lovrabet config list

🔧 配置文件丢失​

问题现象：

  • CLI 配置突然失效
  • 提示需要重新登录
  • appCode 配置丢失

解决方法：

# 1. 检查配置文件位置
ls -la ~/.lovrabet/
# config.json - 应用配置
# cookies.json - 登录 Cookie
# tokens.json - 认证 Token

# 2. 备份现有配置
cp -r ~/.lovrabet ~/.lovrabet.backup

# 3. 重新配置
rm -rf ~/.lovrabet/
lovrabet auth
lovrabet config set app your-app-code

# 4. 检查项目级配置
ls -la .lovrabet/
cat .lovrabet/config.json

📊 日志管理​

问题现象：

  • 日志文件占用大量空间
  • 需要查看历史日志
  • 日志文件位置不清楚

解决方法：

# 查看当前日志
lovrabet logs

# 查看日志文件位置
# 日志存储在项目根目录，格式：lovrabet-cli-yyyy-mm-dd.log
ls -la lovrabet-cli-*.log

# 清理日志
lovrabet logs --clear

# 手动清理旧日志（保留最近30天）
find . -name "lovrabet-cli-*.log" -mtime +30 -delete

# 查看日志大小
du -sh lovrabet-cli-*.log

菜单同步问题​

🔗 菜单同步失败​

问题现象：

  • lovrabet menu sync 执行失败
  • 提示权限不足
  • 菜单创建后不显示

解决方法：

# 1. 检查登录状态
lovrabet auth

# 2. 确认 appCode 正确
lovrabet config list

# 3. 检查页面文件是否正确
ls src/pages/
# 每个页面文件需要包含 Title 注释
# /**
#  * Title: 页面名称
#  */

# 4. 查看 CDN 资源是否配置
lovrabet config get jsUrl
lovrabet config get cssUrl

# 5. 强制刷新菜单
lovrabet menu sync --force

🔄 菜单更新不生效​

问题现象：

  • 菜单同步成功但工作台没显示
  • 修改菜单名称后不更新
  • CDN 资源更新后菜单未刷新

解决方法：

# 1. 更新已同步菜单的 CDN 资源
lovrabet menu update

# 2. 检查 CDN 资源是否可访问
curl -I https://your-cdn-url/assets/index.js

# 3. 清理浏览器缓存后刷新工作台
# Chrome: Cmd+Shift+R (Mac) / Ctrl+Shift+R (Windows)

# 4. 检查菜单状态
lovrabet menu status

MCP 相关问题​

🤖 MCP 配置不生效​

问题现象：

  • MCP 工具无法使用
  • AI 无法访问数据集信息
  • Cursor/Claude Code 未识别 MCP

解决方法：

# 1. 重新安装 MCP 配置
lovrabet mcp install --cursor

# 2. 检查配置文件
cat ~/.cursor/mcp.json
# 确认包含 lovrabet-dataset 配置

# 3. 验证环境变量
echo $LOVRABET_APP_CODE

# 4. 测试 MCP 连接
# 在 Cursor 中打开 MCP 服务器面板
# 确认 lovrabet-dataset 状态为 "已连接"

# 5. 重启 IDE
# 完全关闭 Cursor/Claude Code 后重新打开

通用解决步骤​

当你遇到任何问题时，可以按以下顺序进行排查：

1️⃣ 收集信息​

# 查看 CLI 版本
lovrabet --version

# 查看 Node.js 版本
node --version

# 查看操作系统
uname -a  # Linux/Mac
ver       # Windows

2️⃣ 查看日志​

# 查看 CLI 日志
lovrabet logs

# 清空日志重新试试
lovrabet logs --clear

3️⃣ 检查配置​

# 查看项目配置
lovrabet config list

# 查看登录状态
ls ~/.lovrabet/

4️⃣ 重置环境​

# 重新登录
rm -rf ~/.lovrabet/
lovrabet auth

# 重新安装 CLI
npm uninstall --global @lovrabet/cli
npm install --global @lovrabet/cli

仍然解决不了？​

如果上面的方法都试过了仍然没解决，你可以：

  1. 查看官方文档：确认你的操作步骤正确
  2. 联系同事：问问其他人是否遇到了相同问题
  3. 联系技术支持：提供详细的错误信息和日志

请在寻求帮助时提供以下信息：

  • CLI 版本号
  • Node.js 版本号
  • 操作系统版本
  • 具体错误信息
  • 操作步骤
  • CLI 日志内容