阿里 AgenUI 开源库实战 —— Day3 附录：Windows 环境构建 Android 项目常见问题

本附录针对 Day 3 中 Android 端集成步骤，补充 Windows（MINGW64 / Git Bash）环境下执行 ./scripts/android/build.sh 时可能遇到的典型错误及修复方案。

一、问题背景

在 Windows 系统下通过 Git Bash 执行 AGenUI Android 构建脚本时，Gradle 配置阶段可能抛出 java.io.IOException: 文件名、目录名或卷标语法不正确。 错误。该问题与 Windows 路径格式及 Gradle 属性文件转义规则有关。

二、错误现象

$ sh build.sh
[INFO] AGenUI SDK version: 1.0.0
[INFO] Build ID generated locally: 1.0.0.67357 (android)
[INFO] Running Gradle task: assembleRelease

> Configure project :
[yoga] No prebuilt configured — will use GitHub FetchContent (built-in)

FAILURE: Build failed with an exception.

* What went wrong:
A problem occurred configuring root project 'AGenUI-Client-Android'.
> java.io.IOException: 文件名、目录名或卷标语法不正确。

BUILD FAILED in 2s

三、排查与定位

执行以下命令获取详细堆栈，定位根因：

./gradlew assembleRelease –stacktrace

通过堆栈可定位到两类核心问题：

问题 1：CMake 路径格式不兼容

堆栈线索：

at com.android.build.gradle.internal.cxx.configure.NdkLocator.findNdkPath

根本原因：
build.gradle 中传递给 CMake 的路径参数使用了 Windows 反斜杠（如 E:\\projects\\…），而 CMake 期望正斜杠格式（E:/projects/…）。

原始代码（platforms/android/build.gradle）：

def cmakeArgs = [
"-DANDROID_STL=" + stlType,
"-DAGENUI_REPO_ROOT=" + rootProject.projectDir.parentFile.parentFile.absolutePath
]
if (resolvedYogaPrebuiltDir) {
cmakeArgs.add("-DYOGA_PREBUILT_DIR=" + resolvedYogaPrebuiltDir)
}

问题 2：local.properties SDK 路径未转义

堆栈线索：

at com.android.build.gradle.internal.SdkLocator$SdkLocationSource.validateSdkPath

根本原因：
local.properties 中的 sdk.dir 包含空格或特殊字符（如 D:\\Program Files\\Android\\Sdk），但未按 Java Properties 格式转义。

原始内容：

sdk.dir=D:\\Program Files\\Android\\Sdk

四、解决方案

修复 1：统一 CMake 路径为正斜杠

修改 platforms/android/build.gradle，将传入 CMake 的所有路径统一转换：

def cmakeArgs = [
"-DANDROID_STL=" + stlType,
"-DAGENUI_REPO_ROOT=" + rootProject.projectDir.parentFile.parentFile.absolutePath.replace(File.separator, '/')
]
if (resolvedYogaPrebuiltDir) {
cmakeArgs.add("-DYOGA_PREBUILT_DIR=" + resolvedYogaPrebuiltDir.replace(File.separator, '/'))
}

原理：
File.separator 在 Windows 下为 \\，通过 replace(File.separator, '/') 统一转换为正斜杠。CMake 在 Windows 上完全兼容 / 格式的路径。

修复 2：转义 local.properties 路径

按照 Gradle 属性文件规范，对反斜杠和冒号进行转义：

sdk.dir=D\\:\\\\Program Files\\\\Android\\\\Sdk

转义规则速查：

五、总结

在 Windows 上构建包含 CMake / NDK 的 Android 原生项目时，需特别注意路径兼容性：

完成上述修复后，重新执行 ./scripts/android/build.sh 即可正常构建。

关联阅读：Day 3 正文中的三种 Android 集成方式（手动 AAR / Maven / Gradle 自动化）均依赖此构建脚本，建议 Windows 用户先完成本附录的配置修复，再继续 Day 3 的主流程。