OpenHarmony基线移植实战：从开源仓到定制仓的完整路径-编程实验室

1. 为什么需要移植OpenHarmony基线？

第一次接触OpenHarmony基线移植时，我也很困惑：为什么不能直接用官方开源代码？非要折腾这一套移植流程？直到在实际项目中踩了几个坑才明白，基线移植是产品开发的必经之路。

想象一下这个场景：你拿到一块RK3568开发板，想基于OpenHarmony开发智能家居中控。官方开源代码确实能用，但存在几个现实问题：首先，所有开发团队都在用同一份代码，你的定制修改无法有效管理；其次，官方代码仓有严格的提交规范，直接提交会被拒绝；最重要的是，产品化需要大量硬件适配和功能裁剪，这些都需要独立的代码管理空间。

我遇到过最典型的问题是在LFS大文件处理上。当时直接用开源仓编译，总是莫名其妙报错，后来发现是.gitattributes文件冲突导致LFS文件下载失败。这就是为什么移植过程中要特别处理.git相关文件——它们像是代码的"身份证"，直接混用会导致版本管理混乱。

2. 环境准备与代码获取

2.1 搭建基础开发环境

在RK3568上移植OpenHarmony 5.1.0，建议使用Ubuntu 20.04 LTS系统。这是我实测最稳定的组合，其他版本可能会遇到各种依赖问题。先安装这些基础工具：

sudo apt update sudo apt install git git-lfs repo python3-pip -y

特别注意git-lfs的配置，很多大文件下载失败都是因为它没正确初始化：

git lfs install --skip-repo

2.2 获取官方开源代码

以5.1.0-Release为例，官方仓地址在Gitee。这里有个关键细节：一定要用带v的版本标签（OpenHarmony-v5.1.0-Release），否则可能会下到开发中的不稳定代码。我建议创建专门的工作目录：

mkdir -p ~/work/Release_5.1.0/code cd ~/work/Release_5.1.0/code

初始化仓库时，新手常犯的错误是漏掉--no-repo-verify参数。这个参数跳过了证书验证，在内网环境下特别有用：

repo init -u https://gitee.com/openharmony/manifest -b refs/tags/OpenHarmony-v5.1.0-Release --no-repo-verify

同步代码时建议分两步走，先同步基础代码再处理LFS文件：

repo sync -c # 基础代码同步 repo forall -c 'git lfs pull' # 大文件下载

3. 创建并初始化定制仓

3.1 建立远程代码仓

现在转到你们公司的代码托管平台（比如GitLab），新建一个名为RK3568_OpenHarmony5.1.0_Backup的空仓库。注意保持仓库纯净，不要初始化README或.gitignore文件。

3.2 本地仓克隆与改造

在本地新建工作目录，这个目录结构设计很有讲究。我习惯把原始代码和移植代码分开存放：

mkdir -p ~/work/OpenHarmony/new cd ~/work/OpenHarmony/new git clone <你们公司的仓库地址> RK3568_OpenHarmony5.1.0_Backup

关键操作来了：进入新仓库后，立即备份.git目录。这个操作看似简单，却能避免后续很多麻烦：

cd RK3568_OpenHarmony5.1.0_Backup mv .git .agit_backup # 不能用.git前缀！

4. 代码迁移与清理

4.1 代码拷贝技巧

把官方代码完整拷贝到新仓库，这里要用-ar参数保持文件属性：

cp -ar ~/work/Release_5.1.0/code/* ~/work/OpenHarmony/new/RK3568_OpenHarmony5.1.0_Backup/

特别注意：.gn文件经常被漏掉，因为它是隐藏文件。需要手动拷贝：

cp ~/work/Release_5.1.0/code/.gn ~/work/OpenHarmony/new/RK3568_OpenHarmony5.1.0_Backup/

4.2 清理版本控制痕迹

这是最易出错的环节。先修改特殊目录下的.gitattributes：

mv third_party/typescript/lib/.gitattributes third_party/typescript/lib/oh_gitattributes

然后执行全面清理，分步骤更安全：

# 检查所有git相关文件 find . -name ".git*" -o -name ".repo" # 确认无误后删除 find . -name ".git*" ! -path "./.agit_backup*" | xargs rm -rf find . -name ".repo" | xargs rm -rf

最后恢复.git目录和关键属性文件：

mv .agit_backup .git mv third_party/typescript/lib/oh_gitattributes third_party/typescript/lib/.gitattributes

5. 编译验证与代码提交

5.1 预编译与正式编译

先执行预编译下载工具链，记得加上--skip-ssl避免证书问题：

./build/prebuilts_download.sh --skip-ssl

RK3568的编译命令需要指定product-name：

./build.sh --product-name rk3568

编译成功后，镜像文件在这里：

ls out/rk3568/packages/phone/images/

5.2 代码提交规范

提交前建议先检查变更：

git status git add .

写commit信息时有个技巧：注明原始基线版本，方便后续追溯：

git commit -m "基线移植: OpenHarmony 5.1.0 Release > 原始基线: gitee.com/openharmony/manifest tag OpenHarmony-v5.1.0-Release > 移植平台: RK3568"

最后推送到远程仓，注意refs/for/master是Gerrit的特有语法：

git push origin HEAD:refs/for/master

6. 常见问题排查

6.1 LFS文件下载失败

症状：编译时报缺失文件。解决方法：

检查.gitattributes是否被误删
重新初始化git lfs：
```
git lfs install git lfs pull
```

6.2 编译时头文件缺失

通常是预编译没完成。确保执行过：

./build/prebuilts_download.sh --skip-ssl

6.3 提交被拒绝

检查是否清理干净了原仓信息：

find . -name ".git" | grep -v "\.git$"

7. 效率优化技巧

经过多次实践，我总结出一个快速移植流程：

在原代码目录直接操作：

cd ~/work/Release_5.1.0/code ./build/prebuilts_download.sh --skip-ssl mv third_party/typescript/lib/.gitattributes third_party/typescript/lib/oh_gitattributes find . -name ".git*" ! -path "./.git" | xargs rm -rf find . -name ".repo" | xargs rm -rf mv third_party/typescript/lib/oh_gitattributes third_party/typescript/lib/.gitattributes

拷贝.git目录：

cp -r ~/work/OpenHarmony/new/RK3568_OpenHarmony5.1.0_Backup/.git ~/work/Release_5.1.0/code/

这个方法节省了全量拷贝的时间，特别适合快速验证。不过第一次移植时还是建议走完整流程，理解每个步骤的意义。移植过程中保持耐心很重要，我在RK3568上第一次成功移植花了三天时间，现在熟练后半小时就能完成全套流程。

OpenHarmony基线移植实战：从开源仓到定制仓的完整路径