跳到主要内容

安装指南

前置条件​

在安装之前，请确保你的电脑已经安装了：

Node.js 环境​

  • Node.js 20 或更新版本
    • 可以在终端运行 node --version 查看当前版本
    • 如果没有或版本太旧，请到 nodejs.org 下载最新的 LTS 版本

什么是 LTS？ LTS 全称 Long Term Support（长期支持），是 Node.js 的稳定版本，推荐日常使用。

Windows 用户特别说明​

📝 重要推荐：Windows 用户强烈推荐使用 Git Bash 作为命令行终端。我们在 Git Bash 中做了充分验证，而 CMD/PowerShell 仅做了简单兼容支持。

为什么推荐 Git Bash？

  • 提供类 Unix 环境，与 macOS/Linux 体验一致
  • 我们在此环境下进行了完整的功能测试和验证
  • 支持完整的 shell 脚本功能和环境变量
  • 更好的中文支持和编码处理

如何获取 Git Bash？

  1. 访问 git-scm.com
  2. 下载并安装 Git for Windows
  3. 安装完成后，右键点击任意文件夹选择「Git Bash Here」
  4. 或者在开始菜单搜索「Git Bash」

验证 Git Bash 环境：

# 在 Git Bash 中运行，应该看到类似输出
echo $SHELL
# 输出：/usr/bin/bash 或类似路径

which node
# 输出：/c/Program Files/nodejs/node 或类似路径

安装方式​

我们提供两种安装方式，你可以选择其中一种：

方式一：使用 npm（推荐）​

在终端运行以下命令：

npm install --global @lovrabet/cli

什么是 --global？ 全局安装意味着你可以在任何目录下使用 lovrabet 命令，而不仅仅在当前项目中。

方式二：使用 Bun​

如果你使用 Bun（一个更快的 JavaScript 运行时）：

bun install --global @lovrabet/cli

验证安装​

安装完成后，在终端运行以下命令来验证是否安装成功：

lovrabet --help

如果看到类似以下的输出，说明安装成功：

Lovrabet CLI - 前端开发脚手架

用法：
  lovrabet <command> [options]

可用命令：
  create    创建新项目
  auth      登录认证
  ...

升级到最新版本​

当有新版本发布时，你可以重新运行安装命令来升级：

npm install --global @lovrabet/cli

或者如果你使用的是 Bun：

bun install --global @lovrabet/cli

小提示: 定期升级能让你体验到最新的功能和问题修复。

安装问题排查​

问题 1：提示 Node.js 版本过低​

错误信息: Node.js version 18.x.x is not supported

解决方法:

  1. 访问 nodejs.org
  2. 下载最新的 LTS 版本（版本号 20.x 或更高）
  3. 安装完成后重新运行安装命令

Windows 用户注意：

  • 安装 Node.js 后，重新打开 Git Bash 窗口
  • 在 Git Bash 中验证：node --version

问题 2：无法下载包​

错误信息: 404 Not Found - GET https://registry.npmjs.org/@lovrabet%2fcli

解决方法:

  1. 检查网络连接是否正常
  2. 检查 npm 源配置，确保能访问私有 npm 仓库
  3. 联系管理员获取正确的 .npmrc 配置

问题 3：没有全局安装权限​

错误信息: permission denied

解决方法:

  • macOS/Linux: 在命令前加上 sudo 
    sudo npm install --global @lovrabet/cli
  • Windows: 以管理员身份运行 Git Bash
    • 右键点击 Git Bash 图标
    • 选择「以管理员身份运行」
    • 再次尝试安装命令

问题 4：Windows 终端环境选择​

现象: 在不同 Windows 终端中可能出现不同的体验

建议方案:

  1. 最佳选择 - Git Bash：完全测试验证，体验最佳

    # 在 Git Bash 中执行，功能完整
    lovrabet --help

  2. 备选方案 - CMD/PowerShell：基础功能可用，但未充分测试

    REM 在 CMD 中可能需要额外设置
    lovrabet --help
    # 在 PowerShell 中可能遇到部分限制
    lovrabet --help

  3. 遇到问题时的建议：

    • 先在 Git Bash 中尝试相同操作
    • 如果 Git Bash 中正常，说明是终端环境问题
    • 可以继续使用其他终端，但可能需要手动处理部分问题

仍然无法解决？​

请查看 故障排查 文档，或联系技术支持。

联系支持时请提供：

  • 操作系统版本
  • Node.js 版本
  • 使用的终端类型（特别注明是否为 Git Bash）
  • 完整的错误信息