limrun-gradle

远程 Gradle 构建

在 Limrun 的远程 Gradle 沙箱中构建 Android 项目，适用于任意环境（Linux、Windows、macOS、VM、容器）。lim gradle build 会将源代码同步到远程实例，在那里运行项目自带的 Gradle wrapper，并流式输出构建结果。此工作流在远程实例上构建；不会使用本地 Gradle、本地 Android SDK 或本地模拟器。运行完成后，应用会在 Limrun 模拟器中运行，或将构建产物交付给你。

构建 iOS 项目时，请改用 limrun-xcode。如需在任一平台上使用 Expo 开发客户端循环（Metro、热重载），请使用 limrun-expo-development；该工作流会在 Android Debug 构建时回到此处。

身份验证和 CLI

如有需要，请安装：npm install --global lim。身份验证方式为 lim login 或 LIM_API_KEY（即使 .env 和 shell 中未显示，用户环境中也可能已经设置；索取之前请先检查）。CLI 是准确信息的来源： 此技能中的命令已经过验证，但如果某个标志报错，或你需要此处未列出的标志，请查看 --help，不要猜测：

lim gradle --help
lim gradle build --help

构建 APK

请使用以下命令构建，而不是 ./gradlew：

lim gradle build .

此命令会创建或复用已记住的 Gradle 实例，同步当前目录，并默认运行 assembleDebug。使用 --task 显式选择任务（可重复指定）：

lim gradle build . --task :app:assembleRelease

当 Gradle 根目录位于子目录中，且自动发现存在歧义时，请使用 --project-path（例如，Gradle 位于 android/ 目录中的纯 React Native 仓库；服务端通常可以自行找到它）：

lim gradle build . --project-path android

系统会自动检测 Expo 托管工作流项目（没有 android/ 目录）：沙箱会安装依赖并在 Gradle 之前运行 expo prebuild。设置 --expo-app-dir（monorepo）或 --abi 会强制使用该流水线；如果未检测到 Expo 应用，则会报错：

lim gradle build ./my-monorepo --expo-app-dir apps/mobile

如需通过 Metro 和热重载迭代开发 Expo 应用，而不是仅进行常规构建，请使用 limrun-expo-development。

私有依赖凭据

使用 --additional-file 复制现有凭据文件；sync 也支持此标志：

lim gradle build . \
  --additional-file "$HOME/.npmrc=~/.npmrc" \
  --additional-file "$HOME/.netrc=~/.netrc"

远程路径中的 ~/ 指向沙箱主目录；其他目标路径均相对于工作区。后续同步时请重复指定这些标志，以保留这些文件。对于配置中引用的环境变量，请传递 --env。

分离运行的构建和日志

使用 --detach 可在构建被接受后立即返回；Webhook 可选。无需指定 exec ID，logs 即可读取最新构建的日志，包括实例删除后仍持久保存的日志；添加 --follow 可等待构建完成。

lim gradle build . --detach
lim gradle logs
lim gradle logs --follow

工具版本和 shell 命令

同步后，lim gradle use 会选择沙箱中的工具，并安装缺少的版本。运行 lim gradle tools install 以安装已同步项目中选择的工具版本（详情）。构建会继续使用项目的 gradlew；Android SDK/NDK/CMake 使用 sdkmanager。

lim gradle tools
# Node includes npm/npx.
lim gradle use node@24 pnpm@10 yarn@4 bun@1 java@temurin-17 bundletool@1
lim gradle tools install
lim gradle run -- mise use --pin [email protected]
lim gradle run --env APP_ENV=staging -- npm run generate
lim gradle build . --env APP_ENV=staging

下载沙箱文件

使用 lim gradle pull-file <remote-path> [destination] --id <instance-ID>。 路径可以是绝对路径，也可以是相对于已同步项目根目录的路径。 切勿使用构建或运行日志传输文件，包括文本、二进制或 base64 内容。 请等待写入文件的命令完成。先归档目录，并在删除实例之前完成下载。

在模拟器上运行

将构建好的 APK 作为具名资源上传，然后在 Android 实例上安装：

lim gradle build . --upload myapp.apk
lim android create --install-asset=myapp.apk

构建上传的默认 TTL 为 14 天：每次构建上传都会将资源的过期时间延长至从该次上传起 14 天。传递 Go 时长（例如 720h；1d 无效）给 --upload-ttl 可更改此设置。

请将创建输出中的已签名流 URL 作为 Markdown 链接分享给用户，例如 [Live emulator](<signed-stream-url>)。迭代重建时，请原地更新已安装的 APK，而不是重新创建实例：

lim android sync ./path/to/app-debug.apk

如需在设备上执行其他操作（点击、输入、查看元素树、截屏、录制视频、通过 adb 查看 logcat），请使用 limrun-android-emulator。

为 release AAB 签名

默认签名流程无需用户提供凭据：

lim gradle build . --sign --upload myapp.aab

首次使用时，Limrun 会生成一个上传密钥库，将其托管为该应用在组织中的签名密钥，并使用它签名。此后，无论在哪台机器或 CI 上构建同一应用，使用 --sign 的构建都会使用同一个密钥，因此上传到 Play Store 的内容始终匹配。密钥以 Android 应用 ID 命名，该 ID 会从 app.json（Expo）或 app/build.gradle(.kts) 中检测；如果检测失败或选错了 flavor，请传入 --application-id <id>。

--sign 会将 bundleRelease 设为默认任务；如果显式指定的 --task 列表中没有 bundle 任务，构建会在启动前失败。构建成功（SUCCEEDED）表示 AAB 已带有签名（服务器会在上传前验证签名），因此除非用户提出要求，否则不要再次验证构建产物。

请留意构建开始前出现的以下提示之一，并转述其含义：

• Signing with the organization's upload key for <app> (newly generated).：这是该应用的首次构建；该密钥现已供整个组织使用。
• Signing with the organization's upload key for <app> (existing).：正在按预期复用已托管的密钥。

使用自己的上传密钥

如果应用已有注册的上传密钥（例如已有 Play listing），用户可以改用自己的密钥库签名。密钥库路径、密钥别名和两个密码由用户在自己的机器上通过 --keystore、--key-alias、--keystore-password 和 --key-password 标志，或 LIM_KEYSTORE_PASSWORD 和 LIM_KEY_PASSWORD 环境变量提供（lim gradle build --help 会列出这些选项）。在对话中绝不要询问或处理这些值；如果缺少某项，请指出需要设置的标志或变量。四项必须一起提供。添加 --save-key 可托管提供的密钥，之后的构建便可省略这些标志，直接使用 --sign。--save-key 不会覆盖已有密钥：如果该应用已托管了不同的密钥，就会在创建任何实例之前失败。

密钥库文件本身必须留在用户的机器上：绝不要提交该文件，也不要将其字节粘贴到文件中。如果用户不知道别名，可运行 keytool -list -keystore <file> 查看。

使用自带密钥时，需要识别以下失败提示：

• The organization already has a different upload key escrowed for <app>：--save-key 冲突。使用 --sign 的构建会使用已托管的密钥；移除 --save-key 可仅在本次构建中使用所提供的密钥库签名，也可以询问用户哪个才是真正的上传密钥。
• Signing with your own key requires ... as well：自带密钥标志组不完整；提示会准确列出缺少的标志。
• signing <field> contains an unsupported character：密码或别名包含 ISO-8859-1 之外的字符。使用 keytool 在原处将其更改为 Latin-1 值（-storepasswd、-keypasswd 或 -changealias）。绝不要重新生成密钥本身，否则会改变上传密钥。

发布到 Play 商店

当用户已在自己的机器上配置 Play 凭据（服务账号 JSON 文件或访问令牌，通过 --playstore-service-account 或 --playstore-access-token 标志传入）时，构建会直接发布已签名的 Release AAB，无需使用浏览器。绝不要在对话中索要这些凭据：

lim gradle build . --sign --upload-to-playstore --playstore-service-account sa.json --auto-version-code

--auto-version-code 会让服务在构建前从 Google Play 获取下一个可用的 versionCode，并将其写入工作区副本（对于 Expo 项目，写入 app.json 中的 expo.android.versionCode；对于原生 Gradle 项目，写入常规 app/ 模块构建脚本中的唯一字面量 versionCode），因此重复发布不会发生冲突。如果不使用此选项，或者项目使用计算得出或按 flavor 拆分的 versionCode（服务会在收到请求时拒绝此类项目），请按下文自行管理 versionCode。没有 Play 凭据就无法执行发布：发布需要通过浏览器使用 Google 账号登录。请准备好构建产物，将其作为资源上传，然后移交给用户：

lim gradle build . --sign --upload <app>-v<versionCode>.aab

告诉用户打开 https://console.limrun.com，在 Secrets 页面点击 Connect Play Console，使用拥有该应用发布权限的 Google 账号登录（会话仅保存在浏览器中；不会存储任何信息）。然后在 Registry 页面点击已上传 AAB 上的 Publish to Play Store，并输入包名（应用 ID）。Play Console 中必须已存在该应用的条目。Google Play 要求 versionCode 从未使用过：发布构建时，--auto-version-code 会自动处理；如果不使用此选项，请在构建前更新 app/build.gradle(.kts) 中的 versionCode（Expo 项目：更新 app.json 中的 expo.android.versionCode）。

在 --sign 路径中需要识别的失败信息：

• Cannot determine the Android application ID for signing：检测未找到 app.json 中的 android.package，也未找到 app/build.gradle(.kts) 中的 applicationId；请传入 --application-id <id>。
• --sign produces a Play-ready signed AAB; include a bundle task：显式的 --task 列表中没有 bundle 任务；请添加 bundleRelease 或移除 --task。
• the built AAB carries no signature：服务在构建后检查时发现 AAB 未签名，说明签名配置未生效。这不是用户代码的问题；请重试，如果问题持续存在，请报告。

Pull Request 中的 Android 预览

如需在 Pull Request 中生成可重复的预览，建议使用打包好的 Android preview action。它会构建并上传应用、更新 PR 预览评论，并清理构建器；输入参数和工作流示例请参阅仓库。

注意事项

• 构建错误也是工作的一部分。 如果构建失败，请阅读错误输出、修复代码并重新构建，然后再汇报。
• 项目的 mise 文件可能会安装构建根本用不到的工具。 沙盒中的首次构建或运行会对同步的 mise 文件中每个 [tools] 条目运行 mise install，因此，若单体仓库的根目录 mise.toml 列满了数据库和云 CLI 工具，就会拖慢构建或导致失败。只要项目文件能正常工作，就继续使用它。如果无法正常工作，请在同一目录中添加 mise.limrun.toml，仅列出构建所需的工具（例如 node 和 pnpm）；在该目录中，Limrun 会读取此文件，而不是其他 mise 文件。
• 实例按 git 工作树分别复用。 命令会根据当前工作目录所在的工作树查找已记住的实例；传入 --id <gradle-instance-id>（从 lim gradle list 获取）可指定目标实例。
• 每次上传到 Play 时，versionCode 都必须递增。 发布构建时，优先使用 --auto-version-code。如果发布被拒绝，并提示版本代码已存在，请递增版本代码、重新构建并再次发布。如果发布 RETRY 报告此问题，说明之前的尝试已经成功；不要再次发布。
• 应用 ID 检测会读取第一个未注释的 applicationId。 它不支持按 flavor 区分的 ID 和动态 Gradle 逻辑；遇到这些情况时，请使用 --application-id。
• Keystore 密码不能为空，且必须使用 ISO-8859-1 编码。 空密码和 Latin-1 范围之外的字符会在请求时被拒绝，而不是等到构建开始几分钟后才失败。
• 保持同步文件精简，并避免将其放在构建目录中。 根目录级别的 build/、.gradle、.kotlin 以及任何 local.properties 都不会同步，并且会遵循 .gitignore 文件（包括嵌套文件）。对于其他较大的本地产物，请使用 --ignore <regex>；对于构建所需、但被 git 忽略的输入，请使用 --include <regex> 强制同步。