updating-android-sdk

更新 Flutter Android SDK 和 CIPD 软件包

本技能将逐步指导 Agent 如何在 packages.txt 中配置新的 Android SDK 组件、验证标签唯一性，以及运行仓库的自动化脚本，将跨平台归档上传到 Chrome Infrastructure Package Deployment（CIPD）。

先决条件与权限验证

在修改软件包或触发 CIPD 上传之前，请确认本地环境和凭据配置正确：

1. 验证 Depot Tools：确保环境中已提供 depot_tools（其中包含 cipd CLI）。
2. 验证 CIPD 写入权限：此操作需要对 flutter/android/sdk/all/ CIPD 前缀拥有写入权限。请在继续之前验证权限：

   cipd acl-check flutter/android/sdk/all/ -writer
   

   如果访问被拒绝，请申请 flutter-cipd-writers 角色，并通过 cipd auth-login 进行身份验证。

---

第 1 步：配置目标 SDK 软件包（packages.txt）

脚本 create_cipd_packages.sh 会从 packages.txt 中读取目标 SDK 组件和版本。

• 位置：src/flutter/tools/android_sdk/packages.txt
• 格式：<package_name>:<subdirectory_to_upload>（多目录上传时以 : 分隔）

查询官方软件包标识符

始终查询本地或远程 Android SDK 仓库，以确认准确的软件包标识符：

sdkmanager --list --include_obsolete

重要

Canary / Preview 与 Stable API 级别 使用预发行版或 Canary Android 版本（例如 Android 37 / Cinnamon Bun）时，sdkmanager 通常会使用 .0 后缀发布平台组件（例如 platforms;android-37.0）。 如果 sdkmanager 明确要求使用 platforms;android-37.0，不要假设或强制使用整数 API 级别字符串（platforms;android-37）。使用错误的软件包字符串会导致后续下载失败。

packages.txt 更新示例

要添加 Android 37 平台和 build-tools：

platforms;android-37.0,platforms;android-36,platforms;android-35,platforms;android-34:platforms
cmdline-tools;latest:cmdline-tools
build-tools;37.0.0,build-tools;36.1.0,build-tools;36.0.0,build-tools;35.0.0:build-tools
platform-tools:platform-tools
tools:tools
cmake;3.22.1:cmake
ndk;28.2.13676358:ndk

---

第 2 步：验证标签唯一性并运行上传脚本

说明

统一 CIPD 版本标签 使用简洁的版本描述符（例如 37v1、37v2）。现在 create_cipd_packages.sh 已成为标准上传流程，不要再添加 unmodified 等旧式的推测性后缀。

CIPD 标签和 refs 不可更改。执行脚本之前，请确认拟用的版本标签（例如 37v1）尚未注册：

cipd describe flutter/android/sdk/all/mac-arm64 -version version:<VERSION_TAG>

• 如果标签未被使用：命令会返回退出代码 1，并显示 Error: no such tag.。你可以继续。
• 如果标签已存在：命令会输出现有的 Package: 和 Instance ID:。你必须选择一个新的唯一版本标签。

确认标签唯一后，执行脚本：

cd src/flutter/tools/android_sdk
./create_cipd_packages.sh <VERSION_TAG> <PATH_TO_LOCAL_SDK>

脚本执行机制

1. 清理工作区：脚本会创建一个干净的临时工作目录（mktemp -d），以防止重复使用缓存。
2. 跨平台软件包：脚本会使用 REPO_OS_OVERRIDE 获取 linux、macosx（amd64 和 arm64）以及 windows 的软件包。
3. 接受许可证：所有必需的 Android SDK 许可证都会自动接受，并打包到上传目录中。
4. 创建 CIPD 软件包：脚本会调用 cipd create，将软件包复制并标记到 flutter/android/sdk/all/<cipd_name> 下。

---

第 3 步：验证 CIPD 上传和标签

在更新 Engine 依赖项之前，请验证软件包已在所有架构目标中成功注册：

# macOS Apple Silicon (arm64)
cipd describe flutter/android/sdk/all/mac-arm64 -version version:<VERSION_TAG>

# macOS Intel (amd64)
cipd describe flutter/android/sdk/all/mac-amd64 -version version:<VERSION_TAG>

# Linux (amd64)
cipd describe flutter/android/sdk/all/linux-amd64 -version version:<VERSION_TAG>

# Windows (amd64)
cipd describe flutter/android/sdk/all/windows-amd64 -version version:<VERSION_TAG>

确保输出显示有效的 Instance ID，并确认所请求的标签已绑定到该 ref。

---

故障排查与失败处理

如果在选择软件包、授权或执行脚本时发生任何故障，请采取以下针对性措施：

1. 权限被拒绝（cipd acl-check 或 cipd create 失败）

• 症状：cipd acl-check 报告没有角色，或上传因授权错误而中止。
• 缓解措施：请用户申请 flutter-cipd-writers 角色（通过 MDB/Grants 8h/flutter-cipd-writers）。获批后，运行 cipd auth-login 刷新本地访问凭据，然后重试。

2. 软件包解析失败（sdkmanager 在下载期间中止）

• 症状：create_cipd_packages.sh 退出，并显示 Warning: Failed to find package '<package_name>'。
• 缓解措施：不要猜测或强制采用严格的整数规则（例如 platforms;android-37）。运行 sdkmanager --list --include_obsolete 检查已发布的远程标签，并在 packages.txt 中更正确切的软件包字符串（例如保留 platforms;android-37.0 这样的 .0 预览版后缀）。

3. 上传中断与标签弃用

• 症状：网络中断导致多平台上传中途停止，或上传了错误的软件包集合。
• 缓解措施：CIPD 上传不可撤销，无法覆盖。如果标签仅上传了一部分或需要弃用，请引导用户参阅内部 LuCI Playbook 中有关移除标签的指南（移除重复的 CIPD 标签）。上传失败后重试时，必须选择新的唯一版本标签（例如将 v1 升级为 v2）。

4. 缺少命令行工具

• 症状：脚本输出 SDK directory does not contain cmdline-tools。
• 缓解措施：确保提供的路径指向有效的 Android SDK 根目录，其中包含 cmdline-tools/latest/bin/sdkmanager（在 macOS 上通常为 ~/Library/Android/sdk）。