跳到主要内容

故障排查

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

快速诊断​

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

  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

通用解决步骤​

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

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 日志内容