跳到主要内容

Windows 用户特别指南

本指南专门为 Windows 用户提供使用 Lovrabet CLI 的详细说明和注意事项。

📝 重要建议​

为了获得最佳体验，我们推荐 Windows 用户使用以下环境之一。在不同终端中的支持情况：

  • ✅ WSL (Windows Subsystem for Linux) - 原生 Linux 体验，功能完整，性能优秀
  • ✅ Cmder - 便携美观，功能完整，开箱即用
  • ✅ Git Bash - 完全测试验证，功能完整，体验最佳
  • ⚠️ Windows CMD - 基础功能可用，但未经充分测试
  • ⚠️ PowerShell - 基础功能可用，可能有部分限制
  • ⚠️ Windows Terminal - 取决于具体使用的 shell 类型

环境准备​

你可以选择以下三种环境之一：

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

WSL 提供了原生 Linux 环境，是 Windows 上开发的最佳选择。

1. 安装 WSL​

Windows 10 (版本 2004+) / Windows 11：

  1. 以管理员身份打开 PowerShell
  2. 运行安装命令：
wsl --install
  1. 重启电脑
  2. 首次启动会要求创建用户名和密码

手动安装（如果自动安装失败）：

# 启用 WSL
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

# 启用虚拟机平台
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# 重启电脑后，下载并安装 Linux 发行版
# 访问 Microsoft Store 搜索 "Ubuntu" 并安装

2. 安装 Node.js​

在 WSL 中运行：

# 使用 NodeSource 安装 Node.js 20.x
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# 验证安装
node --version
npm --version

或者使用 nvm 管理 Node.js 版本：

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 重新加载配置
source ~/.bashrc

# 安装 Node.js
nvm install --lts
nvm use --lts

3. 验证环境​

# 检查 WSL 环境
uname -a
# 应该输出 Linux 内核信息

# 检查 Node.js
node --version
# 应该输出 v20.x.x 或更高版本

# 检查 npm
npm --version
# 应该输出版本号

方式二：使用 Cmder​

Cmder 是一个便携、美观的终端模拟器，开箱即用。

1. 下载 Cmder​

  1. 访问 https://cmder.app/
  2. 下载最新版本的 Cmder（推荐下载 Full 版本，包含 Git for Windows）
  3. 解压到任意目录（如 C:\Tools\cmder\ 或 USB 驱动器）
  4. 运行 Cmder.exe 即可使用

特点：

  • 完全便携 - 可以放在 USB 随身携带，配置跟随你走
  • 开箱即用 - 无需安装，解压即用
  • 美观 - 使用 Monokai 配色方案，外观现代
  • Unix 命令支持 - 内置 Git for Windows，支持常用 Unix 命令
  • 多标签页 - 支持多标签页管理和快捷键操作

2. 安装 Node.js​

  1. 访问 https://nodejs.org/
  2. 下载最新的 LTS 版本（版本号 >= 20）
  3. 运行安装程序
  4. 重要：安装完成后重启电脑或重新打开所有终端窗口

3. 验证环境​

打开 Cmder 并运行以下命令：

# 检查 Cmder 环境
echo $SHELL
# 应该输出类似 /usr/bin/bash 或包含 bash 的内容

# 检查 Node.js
node --version
# 应该输出 v20.x.x 或更高版本

# 检查 npm
npm --version
# 应该输出版本号

方式三：使用 Git Bash​

1. 安装 Git for Windows​

这是使用 Lovrabet CLI 的必要步骤：

  1. 访问 https://git-scm.com/download/win
  2. 下载最新版本的 Git for Windows
  3. 运行安装程序，使用默认设置即可
  4. 安装完成后，你就拥有了 Git Bash

2. 安装 Node.js​

  1. 访问 https://nodejs.org/
  2. 下载最新的 LTS 版本（版本号 >= 20）
  3. 运行安装程序
  4. 重要：安装完成后重启电脑或重新打开所有终端窗口

3. 验证环境​

打开 Git Bash 并运行以下命令：

# 检查 Git Bash 环境
echo $0
# 应该输出类似 "-bash" 或包含 "bash" 的内容

# 检查 Node.js
node --version
# 应该输出 v20.x.x 或更高版本

# 检查 npm
npm --version
# 应该输出版本号

安装 Lovrabet CLI​

在你的终端（WSL / Cmder / Git Bash）中运行：

npm install --global @lovrabet/cli

WSL 用户​

如果遇到权限问题，可以：

  1. 使用 sudo（不推荐全局使用）：
sudo npm install --global @lovrabet/cli
  1. 或修改 npm 全局目录权限（推荐）：
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

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

Cmder 用户​

Cmder 通常不需要特殊权限设置，直接运行以下命令即可：

如果遇到权限问题：

  1. 以管理员身份运行 Cmder：

    • 右键点击 Cmder.exe
    • 选择"以管理员身份运行"
    • 重新执行安装命令

  2. 或修改 npm 全局目录权限：

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

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

Git Bash 用户​

如果遇到权限问题，尝试以管理员身份运行 Git Bash：

  1. 右键点击 Git Bash 图标
  2. 选择"以管理员身份运行"
  3. 重新执行安装命令

完整使用示例​

以下是一个完整的 Windows 使用流程（以 WSL 为例，也适用于 Cmder 和 Git Bash）：

# 1. 打开终端（WSL / Cmder / Git Bash）

# 2. 验证环境
node --version
lovrabet --version

# 3. 登录认证
lovrabet auth
# 浏览器会自动打开，完成登录后回到终端按 q 退出

# 4. 创建项目
lovrabet create my-project
cd my-project

# 5. 配置应用
lovrabet config set app my-app-code

# 6. 生成 API
lovrabet api pull

# 7. 启动开发服务器
lovrabet start
# 浏览器会自动打开 http://localhost:5173

WSL 特定提示​

  • 项目文件建议存放在 WSL 文件系统中（如 ~/projects/），性能更好
  • 如需访问 Windows 文件，路径为 /mnt/c/Users/你的用户名/
  • 使用 code . 命令可以在 VS Code 中打开当前目录（需要安装 VS Code 的 WSL 扩展）

Cmder 特定提示​

  • 便携性：可以安装在 USB 驱动器，随身携带你的开发环境
  • 多标签页：使用 Ctrl + T 快速新建标签页，Ctrl + W 关闭标签页
  • 快捷键：Ctrl + Alt + U 向上遍历目录结构，Ctrl + R 历史搜索
  • 别名支持：可以在 config\user-aliases.cmd 中定义常用命令别名
  • 首次运行：建议在首次使用时运行 Cmder.exe /REGISTER ALL 注册右键菜单

Git Bash 特定提示​

  • 右键文件夹选择 "Git Bash Here" 可以快速在当前目录打开终端
  • Windows 路径会自动转换为 Unix 风格（如 /c/Users/...）

获取帮助​

如果遇到其他问题：

  1. 查看故障排查: 故障排查指南
  2. 尝试不同终端:
    • 如果在 CMD/PowerShell 中遇到问题，请尝试在 WSL、Cmder 或 Git Bash 中重复操作
    • WSL、Cmder 和 Git Bash 提供更好的兼容性和用户体验
  3. 收集信息: 提供详细的错误信息和系统信息给技术支持

提供信息时请包含：

  • Windows 版本：运行 winver 查看
  • 终端环境：WSL / Cmder / Git Bash / CMD / PowerShell
  • Git 版本：运行 git --version 查看
  • Node.js 版本：运行 node --version 查看
  • CLI 版本：运行 lovrabet --version 查看
  • 完整的错误信息截图