从命令行构建 Lightbuild 项目

Lightbuild CLI 是 Lightbuild 的官方命令行工具。使用 lightbuild 命令构建和测试项目、查找其构建目标并解析其依赖项。AI 智能体也可以运行相同的命令。您通过 Lightbuild 模板创建的项目包含一个 AGENTS.md 文件，该文件会告知 AI 智能体如何使用 Lightbuild 和 Lightbuild CLI。

如需详细了解 Lightbuild CLI 的命令和选项，请参阅 Lightbuild CLI 参考文档。

安装 Lightbuild CLI

Lightbuild CLI 以 Android SDK 软件包的形式分发，您可以使用 Android CLI 进行安装。您可以使用单个命令安装和设置它，也可以手动安装。

一步完成安装和设置

如需安装 Lightbuild CLI，请运行适用于您操作系统的命令。该命令会在 Android SDK 中安装 Lightbuild CLI 软件包，然后运行该软件包的设置脚本，该脚本会将 Lightbuild CLI 复制到 macOS 和 Linux 上的 ~/.local/bin 或 Windows 上的 $HOME\AppData\LightbuildCLI，并确保该目录位于 PATH 中：

  • macOS 和 Linux：

    android sdk install build/lightbuild/0.0.30 && bash "$(android info sdk)/build/lightbuild/0.0.30/cli/install.sh"

  • Windows (PowerShell)：

    android sdk install build/lightbuild/0.0.30; if ($LASTEXITCODE -eq 0) { & "$(android info sdk)\build\lightbuild\0.0.30\cli\install.cmd" }; if ($LASTEXITCODE -eq 0) { $env:Path += ";$HOME\AppData\LightbuildCLI"; setx LIGHTBUILD_REFRESH 1 | Out-Null; reg delete HKCU\Environment /v LIGHTBUILD_REFRESH /f | Out-Null }

  • Windows（命令提示符）：

    android sdk install build/lightbuild/0.0.30 && for /f "delims=" %p in ('android info sdk') do call "%p\build\lightbuild\0.0.30\cli\install.cmd" && setx LIGHTBUILD_REFRESH 1 >nul && reg delete HKCU\Environment /v LIGHTBUILD_REFRESH /f >nul

命令完成后，验证安装。

手动安装

或者，如需自行安装 Lightbuild CLI 并将其添加到 PATH，请按以下步骤操作：

  1. 如果您没有 Android CLI，请进行安装。

  2. 安装 Lightbuild 软件包：

    android sdk install build/lightbuild/0.0.30

  3. 将 Lightbuild CLI 复制到 PATH 中的某个目录，以便您可以从任何目录运行 lightbuild。您可以将其复制到 PATH 中已有的任何目录，也可以使用设置脚本所用的同一目录：

    • macOS 和 Linux：将 lightbuild 文件复制到 ~/.local/bin：

      mkdir -p ~/.local/bin
cp "$(android info sdk)/build/lightbuild/0.0.30/cli/lightbuild" ~/.local/bin/

      如果 ~/.local/bin 不在 PATH 中，请将以下行添加到 shell 的启动文件（例如 ~/.zshrc 或 ~/.bashrc）中：

      export PATH="$PATH:$HOME/.local/bin"

    • Windows：在 PowerShell 中运行以下命令。它们会将 lightbuild.exe 复制到 $HOME\AppData\LightbuildCLI，将该目录添加到您的用户 Path（如果尚未添加），然后使更改在当前会话和您稍后打开的终端中生效：

      $dir = "$HOME\AppData\LightbuildCLI"
New-Item -ItemType Directory -Force $dir | Out-Null
Copy-Item "$(android info sdk)\build\lightbuild\0.0.30\cli\lightbuild.exe" $dir
$userPath = (Get-ItemProperty HKCU:\Environment).Path
if (($userPath -split ";") -notcontains $dir) { Set-ItemProperty HKCU:\Environment Path "$userPath;$dir" -Type ExpandString }
setx LIGHTBUILD_REFRESH 1 | Out-Null; reg delete HKCU\Environment /v LIGHTBUILD_REFRESH /f | Out-Null
$env:Path += ";$dir"

  4. 验证安装

验证安装

如需验证 Lightbuild CLI 是否已安装，请检查其版本：

lightbuild --version

如果您的终端找不到 lightbuild 命令，请打开一个新的终端窗口，以便 PATH 更改生效。

查找项目的 build 目标

Lightbuild CLI 命令接受一个目标，该目标用于标识要构建、测试或检查的项目部分。目标可以是模块的名称（例如 app），也可以是更具体的内容（例如 app:app-debug.apk）。如需匹配模块中的所有目标，请使用模块名称后跟 /...，例如 app/...。如需匹配项目中的所有目标，请使用 ...。

如需列出项目中的所有目标，请从项目的根目录中查询这些目标：

lightbuild query ...

如需列出目标生成的文件，请添加 --output=files。例如，对于 app 目标，请运行：

lightbuild query app --output=files

如需列出可用于项目的命令，请运行 lightbuild help。

构建应用

如需构建目标，请运行 lightbuild build 并指定目标。例如，如需构建 app 模块，请运行：

lightbuild build app

如需构建项目中的所有目标，请运行以下命令：

lightbuild build

如需构建可上传到 Google Play 的已签名发布版 app bundle，请参阅发布 Lightbuild 应用。

如需移除项目的 build 输出和缓存，请运行以下命令：

lightbuild clean

运行应用

Lightbuild CLI 会构建您的应用，但不会安装或运行它。如需在已连接的设备或正在运行的模拟器上运行应用，请构建应用，然后在 Android CLI 中使用 android run 命令运行应用：

lightbuild build app
android run --apks=app/build/app-debug.apk

如需查看模块的每个目标将其输出写入何处，请运行 lightbuild query app/... --output=files。这些位置是相对于模块目录而言的。

运行测试

如需运行项目中的所有测试，请运行以下命令：

lightbuild test

此命令会运行本地测试（在开发机器上运行）和插桩测试（在已连接的设备或正在运行的模拟器上运行）。

如需在一个模块中运行测试，请添加该模块的目标，例如 app-core。如需仅运行一种类型的测试，请将 :hostTest（针对本地测试）或 :deviceTest（针对插桩测试）添加到模块的目标。例如：

lightbuild test app-core:hostTest
lightbuild test app-core:deviceTest

解决依赖项问题

每个模块都会在 resolved.deps 文件中记录其已解析的依赖项。如需为模块生成 resolved.deps 文件，请使用模块的目标运行 lightbuild resolve。例如，对于 app 模块，请运行：

lightbuild resolve app

如需解析项目中的所有目标，请运行以下命令：

lightbuild resolve

如需了解详情，请参阅已解析的依赖项。