避坑指南｜鸿蒙大赛三方库PR提交5个致命错误踩坑实录 🚫

标签：#鸿蒙积分赛 #Git踩坑 #PR规范 #OpenHarmonyPC

前言 📝

本次适配 CDO 2.4.0 库时，连续踩中PR提交规范大坑，首次提交直接选择main主线、分支命名不规范、缺少真机验证说明，AI评审直接驳回关闭PR。本文整理5个高频致命错误，附带完整修复代码与操作流程，帮大家一次性避开全部坑点。

坑1：PR目标分支直接选择main主线 ❌

错误现象

PR页面显示：从 feat-adapt-cdo 合入到 main
评审驳回意见：main分支为稳定上线分支，仅接收验收完成代码，新增三方库适配禁止提交至main，请更换独立feat分支重提PR。

根本原因

仓库main分支受保护，仅定期合入全部验证通过的适配代码；新增适配必须创建独立版本分支，源分支与目标分支同名。

完整修复代码

# 1. 切回干净主线
git checkout main
# 2. 删除本地错误旧分支
git branch -D feat-adapt-cdo
# 3. 删除个人fork远程错误分支
git push origin --delete feat-adapt-cdo

# 4. 创建仓库规范命名分支
git checkout -b feat/cdo-2.4.0
# 添加适配文件
git add code/cdo/
# 标准化提交
git commit -s -m "feat(cdo): 2.4.0 鸿蒙PC适配，关联#56
1. 静态交叉编译脚本完善
2. hnp.json依赖配置完整
3. Mac编译+鸿蒙真机验证通过"
# 推送个人fork分支
git push origin feat/cdo-2.4.0
# 推送同名分支到官方仓库，作为PR目标分支
git push upstream feat/cdo-2.4.0

网页配套操作：打开旧PR页面滑至底部，点击【关闭合并请求】，备注：目标分支选择main不符合规范，作废重提。

坑2：分支命名使用 feat-adapt-xxx，与仓库规范不统一 ❌

错误命名示例

feat-adapt-cdo、feat-adapt-ent

仓库标准命名格式（参考已有分支）

feat/cdo-2.4.0、feat/jansson-2.14、feat/snappy-1.1.10
统一规范：feat/库名-版本号，斜杆分隔，清晰区分库与版本。

坑3：build_ohos.sh 无执行权限，CI构建直接失败 ❌

CI报错日志

code/cdo/build_ohos.sh: Permission denied

修复完整命令

# 本地赋予脚本可执行权限
chmod +x code/cdo/build_ohos.sh
# 追加修改至本次提交，无需新增commit
git commit --amend --no-edit
# 强制推送更新分支
git push origin feat/cdo-2.4.0 --force-with-lease

坑4：commit提交缺少 -s 签名、未关联Issue工单 ❌

不合格提交信息示例

feat:适配cdo库

大赛强制标准提交格式

git commit -s -m "feat(cdo): 2.4.0 适配 HarmonyOS PC
Closes #56
开发工具：AtomCode
1. autotools静态交叉编译脚本
2. hnp.json完整依赖配置
3. 鸿蒙真机192.168.0.174运行验证正常"

规范说明：

1. -s：添加开发者签名，仓库强制校验；
2. Closes #xxx：关联对应需求工单，PR合入后系统自动关闭工单。

坑5：仅Mac编译自测，PR无真机验证说明，测试人员驳回 ❌

PR缺失内容

未填写真机IP、验证命令、运行结果，评审判定适配未完成。

PR正文标准自测模板（直接复制粘贴）

## 自测验证说明
1. 本地编译环境：MacOS + AtomCode aarch64-ohos交叉工具链
2. 真机测试环境：OpenHarmony PC，局域网IP：192.168.0.174
3. 真机验证执行命令：
/data/service/hnp/bin/cdo --version
/data/service/hnp/bin/cdo --help
4. 验证结果：程序正常启动，完整输出版本2.4.0与帮助文档，无动态依赖缺失、段错误、权限报错。

通用避坑总结 📝

1. 新建分支严格遵循 feat/库名-版本号 格式，禁用 feat-adapt-xxx；
2. PR源分支、目标分支保持同名，绝对不选择main主线；
3. 所有.sh脚本执行 chmod +x，提前规避CI权限报错；
4. Git提交必须携带 -s 签名，通过Closes关联对应Issue；
5. PR正文完整填写真机自测流程，提供完整运行凭证，大幅降低驳回概率。

拓展补充

文中所有错误都是我适配CDO库时真实踩过的雷，每一条都会直接导致PR被关闭、CI构建失败，浪费大量排队等待CI的时间。后续适配ent、snappy、jansson等库时，提前对照本文检查分支、脚本、提交信息、PR描述，能一次性通过评审。