记一次给 Kuikly 贡献 Windows 版本编译鸿蒙脚本的过程

一、背景介绍

1.1 项目简介

Kuikly 是基于 Kotlin Multiplatform 的 UI 与逻辑全面跨端综合解决方案，由腾讯大前端领域 Oteam（公司级）推出，旨在提供一套一码多端、极致易用、动态灵活的全平台高性能开发框架。

支持的平台：

• ✅ Android
• ✅ iOS
• ✅ 鸿蒙（HarmonyOS）
• 🧪 Web（beta）
• 🧪 小程序（beta）
• 🧪 macOS（Alpha）

Kuikly 推出后受到业务广泛认可，已应用于 QQ、QQ 音乐、QQ 浏览器、腾讯新闻、搜狗输入法、应用宝、全民K歌、酷狗音乐、酷我音乐、自选股、ima.copilot、微视等多款产品。

项目地址： https://atomgit.com/Tencent-TDS/KuiklyUI

1.2 问题背景

在 Kuikly 框架中，编译鸿蒙（HarmonyOS）平台的跨端产物需要使用定制版的 Kotlin 工具链（2.0.21-KBA-010），该版本已支持 Mac平台编译。

原有情况：

• 项目提供了 Mac 平台的编译脚本：2.0_ohos_demo_build.sh
• Windows 平台开发者需要手动执行多个命令，流程繁琐且容易出错
• 缺少自动化脚本，影响开发效率

解决方案： 为 Windows 平台贡献一个批处理脚本（.bat），实现与 Linux/Mac 脚本相同的功能，支持一键编译鸿蒙跨端产物并自动拷贝到 Ohos App 目录。

二、贡献流程

2.1 Fork 仓库

首先，访问 Kuikly 官方仓库并 Fork 到自己的账户：

仓库地址： https://atomgit.com/Tencent-TDS/KuiklyUI

2.2 Clone Fork 后的仓库

将 Fork 后的仓库克隆到本地：

git clone git@gitcode.com:nutpi/KuiklyUI.git
cd KuiklyUI

2.3 创建 Windows 编译脚本

参考 Linux/Mac 版本的 2.0_ohos_demo_build.sh 脚本，创建 Windows 批处理脚本 2.0_ohos_demo_build_win.bat。

脚本功能：

1. 临时切换 Gradle 版本到 8.0（鸿蒙编译需要）
2. 使用定制版 Kotlin 工具链（2.0.21-KBA-010）编译 ohosArm64 目标
3. 编译完成后还原 Gradle 版本配置
4. 自动拷贝编译产物（.so 文件和头文件）到 Ohos App 目录

脚本核心代码：

@echo off
setlocal enabledelayedexpansion

echo ========================================
echo Kuikly Ohos Demo Build Script (Windows)
echo ========================================

:: 0. Check and set HarmonyOS SDK environment variables
:: First, try to resolve DEVECO_SDK_HOME if it contains variable references
if defined DEVECO_SDK_HOME (
    :: Expand any nested variables in DEVECO_SDK_HOME
    for /f "delims=" %%A in ('echo %DEVECO_SDK_HOME%') do set "RESOLVED_SDK_HOME=%%A"
    echo [Step 0] Using DEVECO_SDK_HOME: !RESOLVED_SDK_HOME!
) else if defined TOOL_HOME (
    :: Fallback: use TOOL_HOME directly
    set "RESOLVED_SDK_HOME=%TOOL_HOME%\sdk"
    echo [Step 0] DEVECO_SDK_HOME not set, using TOOL_HOME: !RESOLVED_SDK_HOME!
) else (
    echo [Error] Neither DEVECO_SDK_HOME nor TOOL_HOME environment variable is set!
    echo Please set DEVECO_SDK_HOME or TOOL_HOME in your system environment variables
    pause
    exit /b 1
)

:: Set OHOS_SDK_HOME for Kotlin Native
:: Try to find OpenHarmony SDK location
if exist "!RESOLVED_SDK_HOME!\default\openharmony" (
    set "OHOS_SDK_HOME=!RESOLVED_SDK_HOME!\default\openharmony"
) else if exist "!RESOLVED_SDK_HOME!\openharmony" (
    set "OHOS_SDK_HOME=!RESOLVED_SDK_HOME!\openharmony"
) else (
    echo [Error] OpenHarmony SDK not found!
    echo Expected location: !RESOLVED_SDK_HOME!\default\openharmony
    echo Actual resolved path: !RESOLVED_SDK_HOME!
    pause
    exit /b 1
)
echo [Step 0] Using OHOS_SDK_HOME: !OHOS_SDK_HOME!

:: 1. Record original gradle url
echo [Step 1] Backup original gradle version...
for /f "tokens=2 delims==" %%a in ('findstr "distributionUrl" gradle\wrapper\gradle-wrapper.properties') do (
    set "ORIGIN_DISTRIBUTION_URL=%%a"
)
echo Origin gradle url: %ORIGIN_DISTRIBUTION_URL%

:: 2. Backup original file
copy gradle\wrapper\gradle-wrapper.properties gradle\wrapper\gradle-wrapper.properties.bak >nul

:: 3. Switch gradle version
echo [Step 2] Switch gradle version to 8.0...
powershell -Command "(Get-Content gradle\wrapper\gradle-wrapper.properties) -replace 'distributionUrl=.*', 'distributionUrl=https\://services.gradle.org/distributions/gradle-8.0-bin.zip' | Set-Content gradle\wrapper\gradle-wrapper.properties"

:: 4. Start build
echo [Step 3] Building ohos artifact...
set KUIKLY_AGP_VERSION=7.4.2
set KUIKLY_KOTLIN_VERSION=2.0.21-KBA-010
:: Note: Do NOT set KONAN_DATA_DIR here, let Gradle auto-download Kotlin Native toolchain to default location (~/.konan)
:: If you want to use a custom location, ensure the toolchain is already installed there
call gradlew.bat -c settings.2.0.ohos.gradle.kts :demo:linkSharedDebugSharedOhosArm64 --stacktrace

if %ERRORLEVEL% neq 0 (
    echo [Error] Build failed!
    goto :restore
)

echo [Step 4] Build succeeded!

:: 5. Restore gradle config
:restore
echo [Step 5] Restore gradle version...
if exist "gradle\wrapper\gradle-wrapper.properties.bak" (
    move /y "gradle\wrapper\gradle-wrapper.properties.bak" "gradle\wrapper\gradle-wrapper.properties" >nul
    if %ERRORLEVEL% neq 0 (
        echo [Warning] Failed to restore gradle properties, trying alternative method...
        copy /y "gradle\wrapper\gradle-wrapper.properties.bak" "gradle\wrapper\gradle-wrapper.properties" >nul
        del "gradle\wrapper\gradle-wrapper.properties.bak" >nul
    )
) else (
    echo [Warning] Backup file not found at gradle\wrapper\gradle-wrapper.properties.bak
)

:: 6. Copy so file
echo [Step 6] Copying artifact files...

set OHOS_RENDER_PROJECT_DIR=ohosApp
set TARGET_SO_PATH=demo\build\bin\ohosArm64\sharedDebugShared\libshared.so
set OHO_SO_PROJECT_PATH=%OHOS_RENDER_PROJECT_DIR%\entry\libs\arm64-v8a

if not exist "%OHO_SO_PROJECT_PATH%" (
    mkdir "%OHO_SO_PROJECT_PATH%"
)

if exist "%TARGET_SO_PATH%" (
    copy /y "%TARGET_SO_PATH%" "%OHO_SO_PROJECT_PATH%\" >nul
    echo libshared.so: copied to %OHO_SO_PROJECT_PATH%
) else (
    echo [Warning] libshared.so not found at %TARGET_SO_PATH%
)

:: 7. Copy header file
set TARGET_SO_HEADER_PATH=demo\build\bin\ohosArm64\sharedDebugShared\libshared_api.h
set OHO_SO_HEADER_PATH=%OHOS_RENDER_PROJECT_DIR%\entry\src\main\cpp\thirdparty\biz_entry

if not exist "%OHO_SO_HEADER_PATH%" (
    mkdir "%OHO_SO_HEADER_PATH%"
)

if exist "%TARGET_SO_HEADER_PATH%" (
    copy /y "%TARGET_SO_HEADER_PATH%" "%OHO_SO_HEADER_PATH%\" >nul
    echo libshared_api.h: copied to %OHO_SO_HEADER_PATH%
) else (
    echo [Warning] libshared_api.h not found at %TARGET_SO_HEADER_PATH%
)

echo ========================================
echo Build completed!
echo Now open ohosApp in DevEco Studio to run
echo ========================================

endlocal
pause

脚本特点：

• ✅ 使用批处理脚本语法，兼容 Windows 系统
• ✅ 使用 PowerShell 进行文件替换操作
• ✅ 自动创建目标目录（如果不存在）
• ✅ 错误处理和配置还原机制
• ✅ 详细的日志输出，便于调试

2.4 提交代码

完成脚本编写后，提交到 Fork 的仓库：

# 添加新文件
git add 2.0_ohos_demo_build.bat

# 提交（使用 -s 参数添加签名）
git commit -s -m '增加对ohos项目在win平台上的自动编译脚本，支持arm架构真机运行'

# 推送到远程仓库
git push origin main

提交信息说明：

• 使用 -s 参数添加 Signed-off-by 行，符合贡献规范
• 提交信息清晰描述了功能：支持 Windows 平台编译鸿蒙版本

2.5 创建 Issue 和 Pull Request

创建 Issue

在官方仓库创建 Issue，说明贡献的内容和目的：

Issue 地址： https://atomgit.com/Tencent-TDS/KuiklyUI/issues/1

Issue 内容建议：

• 说明问题背景（Windows 平台缺少编译脚本）
• 描述解决方案（提供批处理脚本）
• 说明脚本的功能和使用方法

创建 Pull Request

1. 在 Fork 的仓库页面，点击 "Pull Request" 或 "合并请求"

2. 填写 PR 信息：

   • 标题：清晰描述贡献内容
   • 描述：详细说明修改内容、解决的问题、测试情况等
   • 关联 Issue：关联之前创建的 Issue

3. 确认代码改动无误后，点击提交

4. 等待维护者审查和合并

三、技术实现细节

3.1 脚本功能对比

功能	Linux/Mac (.sh)	Windows (.bat)
Gradle 版本切换	sed 命令	PowerShell 替换
环境变量设置	export	set
文件拷贝	cp	copy
目录创建	mkdir -p	mkdir
路径分隔符	/	\

3.2 关键技术点

3.2.1 Gradle 版本动态切换

由于鸿蒙编译需要 Gradle 8.0，但项目可能使用其他版本，脚本需要：

1. 备份原始配置
2. 临时切换到 Gradle 8.0
3. 编译完成后还原配置

Windows 实现：

REM 备份并替换
copy gradle\wrapper\gradle-wrapper.properties gradle\wrapper\gradle-wrapper.properties.bak
powershell -Command "(Get-Content gradle\wrapper\gradle-wrapper.properties) -replace 'distributionUrl=.*', 'distributionUrl=%NEW_DISTRIBUTION_URL%' | Set-Content gradle\wrapper\gradle-wrapper.properties"

3.2.2 环境变量设置

设置 Kotlin 工具链版本：

set KUIKLY_AGP_VERSION=7.4.2
set KUIKLY_KOTLIN_VERSION=2.0.21-KBA-010

3.2.3 产物拷贝路径

编译产物需要拷贝到 Ohos App 的特定目录：

• libshared.so → ohosApp/entry/libs/arm64-v8a/
• libshared_api.h → ohosApp/entry/src/main/cpp/thirdparty/biz_entry/

3.3 build.2.0.ohos.gradle.kts 配置

在 build.2.0.ohos.gradle.kts 文件的 ohosArm64 配置中，需要添加 HarmonyOS SDK 的 include paths（仅 Windows 平台）：

// Add HarmonyOS SDK include paths (Windows only)
if (System.getProperty("os.name").lowercase().contains("windows")) {
    val ohosSdkHome = System.getenv("OHOS_SDK_HOME")
    if (!ohosSdkHome.isNullOrEmpty()) {
        includeDirs(
            "$ohosSdkHome/native/sysroot/usr/include",
            "$ohosSdkHome/native/sysroot/usr/include/aarch64-linux-ohos"
        )
    }
}

代码说明：

• 通过 System.getProperty("os.name") 检测当前操作系统
• 仅在 Windows 平台上添加额外的 include 路径
• 从环境变量 OHOS_SDK_HOME 获取 SDK 路径
• 添加 native sysroot 的头文件目录，确保编译时能找到 HarmonyOS 系统头文件

3.4 错误处理

脚本包含以下错误处理机制：

1. 编译失败检测：使用 if errorlevel 1 检测编译是否失败
2. 文件存在性检查：拷贝前检查源文件是否存在
3. 目录自动创建：目标目录不存在时自动创建
4. 配置还原保证：无论编译成功与否，都会还原 Gradle 配置

四、使用说明

4.1 前置条件

1. 环境变量配置

   • 设置 OHOS_SDK_HOME 环境变量，指向 DevEco Studio SDK 路径
   • 例如：OHOS_SDK_HOME=D:\Program Files\DevEco Studio\sdk\default\openharmony

2. 工具链版本

   • 确保项目使用 Kotlin 2.0.21-KBA-010 版本
   • 该版本支持 Windows/Linux 平台编译

3. 依赖安装

   • 确保已安装 JDK 和 Gradle
   • 确保网络可以访问 Maven 仓库

4.2 使用方法

1. 在项目根目录执行脚本：

   2.0_ohos_demo_build.bat

2. 等待编译完成：

   • 脚本会自动编译 ohosArm64 目标
   • 编译产物会自动拷贝到 Ohos App 目录

3. 在 DevEco Studio 中编译 App：

   • 打开 ohosApp 目录
   • 使用 DevEco Studio 编译和运行

4.3 注意事项

• ⚠️ 脚本会临时修改 gradle-wrapper.properties，编译完成后会自动还原
• ⚠️ 如果编译失败，请检查环境变量和网络连接
• ⚠️ 确保 Ohos App 目录结构正确
• ⚠️ 首次编译可能需要下载依赖，耗时较长

五、贡献总结

5.1 贡献价值

通过这次贡献，为 Windows 平台开发者提供了：

• ✅ 自动化编译流程：一键完成编译和产物拷贝
• ✅ 降低使用门槛：无需手动执行多个命令
• ✅ 提高开发效率：减少操作步骤，避免人为错误
• ✅ 跨平台一致性：Windows 和 Linux/Mac 平台功能对等

5.2 经验总结

1. 理解项目结构：深入了解 Kuikly 的编译流程和产物结构
2. 参考现有实现：参考 Linux/Mac 脚本，保持功能一致性
3. 注意平台差异：Windows 和 Unix 系统在命令和路径上有差异
4. 完善错误处理：确保脚本在各种情况下都能正确执行
5. 遵循贡献规范：使用规范的提交信息和 PR 描述

5.3 后续优化建议

• 🔄 可以考虑添加编译模式选择（Debug/Release）
• 🔄 可以添加编译进度显示
• 🔄 可以添加编译产物验证
• 🔄 可以支持自定义输出路径

六、参考资料

• Kuikly 官方文档
• Kuikly AtomGit 仓库
• 鸿蒙平台开发指南
• Kotlin Multiplatform 官方文档

---

作者：卢庆杰/坚果
日期：2026年1月
贡献类型：功能增强（Windows 平台支持）
状态：待合并

结语

通过这次贡献，不仅解决了 Windows 平台开发者的实际需求，也加深了对 Kuikly 框架的理解。开源贡献是一个学习和成长的过程，希望这篇文章能帮助更多开发者参与到开源项目中，共同推动技术的发展。

让我们一起为开源社区贡献力量！ 🚀