HarmonyKit | 鸿蒙开发Git 工作流与 .gitignore 最佳实践引言版本控制不只是 git add 和 git commitHarmonyKit 从第一个 commit 开始就严格遵循了一套 Git 工作流。这套工作流的形成有它的上下文——这是一个单人主导的开源项目但同时欢迎社区贡献。因此工作流需要在单人开发的高效率和多人协作的可控性之间找到平衡。这篇文章基于 HarmonyKit 近 100 次 commit 的实践经验涵盖鸿蒙项目特有的.gitignore配置、构建产物的版本控制策略、commit message 规范、分支管理策略以及开源项目的 Pull Request 工作流。项目仓库https://atomgit.com/VON-/harmony-kit.gitignore鸿蒙项目特有的忽略规则HarmonyKit 的.gitignore文件/node_modules /oh_modules /local.properties /.idea **/build /.hvigor .cxx /.clangd /.clang-format /.clang-tidy **/.test /.appanalyzer这份.gitignore的核心原则是不提交构建产物、IDE 配置和本地敏感信息。逐条分析/oh_modules鸿蒙的依赖目录oh_modules是鸿蒙项目的依赖安装目录相当于 Node.js 的node_modules。它由ohpm install命令生成包含项目声明的所有 Kit 包的代码。为什么不应提交oh_modules体积巨大oh_modules包含所有依赖包的完整源码可能达到数百 MB。HarmonyKit 的两个依赖hypium 和 hamock体积不大但原则上的原因仍然成立。版本锁定由oh-package-lock.json5管理和package-lock.json一样锁文件记录了精确的依赖版本。任何人 clone 项目后执行ohpm install即可获得与原作者完全一致的依赖版本。不同平台的二进制差异部分 Kit 包可能包含原生库.so文件不同操作系统的二进制不同。提交某个平台的构建产物可能导致其他平台的开发者遇到兼容问题。**/build构建产物**/build使用 globstar 模式忽略项目中所有层级的build目录。这包括entry/build/entry 模块的构建产物未来可能的feature/build/feature 模块的构建产物任何子目录下的build/文件夹构建产物是可重现的——任何时候执行hvigorw assembleHap都会重新生成。提交它们没有意义还会导致以下问题每次构建后 git status 都会显示大量变更merge 冲突时的构建产物合并毫无意义因为你总可以重建不同开发者机器上的构建产物可能存在微小差异SDK 版本、时间戳等/.hvigor构建引擎缓存/.hvigor是 hvigor 的缓存目录包含以下内容.hvigor/ ├── cache/ │ ├── file-cache.json # 文件缓存 │ ├── last-build-info.json # 上次构建信息 │ ├── project-config.json # 项目配置缓存 │ ├── task-cache.json # 任务缓存 │ └── meta.json # 缓存元数据 ├── dependencyMap/ # 模块依赖图缓存 │ ├── oh-package.json5 │ ├── dependencyMap.json5 │ └── entry/ │ └── oh-package.json5 ├── outputs/ │ └── records/ │ └── performance-recorder.json # 性能记录 └── report/ └── report-*.json # 构建报告这些缓存文件有以下几个特征绝对路径硬编码缓存中记录了文件的绝对路径如/Users/wangxinjie/Desktop/harmony/harmonykit/...。不同的开发者路径不同提交到仓库会导致路径不一致。频繁变化每次构建都会更新缓存信息产生持续的 git 变更。可重建删除.hvigor后重新构建即可完全重建。/local.properties本地 SDK 配置local.properties包含当前机器上 SDK 和工具的安装路径例如nodejs.dir/Applications/DevEco-Studio.app/Contents/tools/node hwsdk.dir/Users/wangxinjie/Library/Huawei/Sdk这些路径是特定于开发者机器的绝不能提交到共享仓库。每个开发者通过 DevEco Studio 的引导流程生成自己的local.properties。/.ideaIDE 项目配置.idea目录是 DevEco Studio基于 IntelliJ IDEA的项目配置目录。部分内容适合共享如代码风格配置部分内容不应共享如本地运行配置。HarmonyKit 选择完全不提交.idea原因DevEco Studio 可以根据项目文件build-profile.json5、hvigorfile.ts自动识别项目类型IDE 配置差异不会影响构建流程避免在我 IDE 上打不开的问题——每个开发者可以有自己的 IDE 配置偏好如果你的团队希望共享代码风格配置可以只提交.idea/codeStyles/和.idea/codeStyleSettings.xml在.gitignore中使用 exclude 规则/.idea/* !/.idea/codeStyles/.clang-format、.clang-tidy、.cxx、.clangdC/C 相关文件这些文件与鸿蒙的 Native 开发相关。HarmonyKit 目前是纯 ArkTS 项目但仍保留了这些默认忽略规则——它们是 DevEco Studio 模板生成的对未来可能的 Native 模块扩展有用。如果未来 HarmonyKit 需要 Native 模块相关配置如CMakeLists.txt和 C 源文件应该置于entry/src/main/cpp/下而不在根目录的.cxx中管理。构建产物的版本控制策略除了.gitignore中的忽略规则还有一个更微妙的问题是否应该将 HAP 发布到 Release 页面HarmonyKit 的选择是是但仅在 GitHub/AtomGit 的 Release 功能中不通过 Git LFS 提交到仓库。理由不是所有想使用 HarmonyKit 的人都安装了 DevEco Studio。Release 页面提供可以直接侧载安装的 HAP 文件。Git 仓库不适合存储二进制文件HAP 虽然只有 3MB但每个版本一份会累积仓库体积。GitHub/AtomGit Release 功能是专门用于分发构建产物的支持下载统计和版本管理。Commit Message 规范HarmonyKit 使用简化的 Conventional Commits 规范格式为type: subject类型type及其使用场景Type使用场景HarmonyKit 示例feat新增功能feat: add radix converter toolfix修复 Bugfix: cannot copy empty text to clipboardrefactor代码重构refactor: extract color logic to ColorUtilsstyle样式调整style: adjust tool card shadow and spacingdocs文档变更docs: add contributing guidechore构建/工具配置chore: update hvigor to 6.1.1test测试相关test: add unit tests for HashUtilsHarmonyKit 不强制在 commit message 中关联 issue 编号因为多数变更是自发的功能开发而非对特定 issue 的响应。但如果某个 commit 确实解决了某个 issuecommit message 中应该包含fixes #xx以自动关闭 issue。好的 commit message 示例feat: add UUID generator tool with uppercase and no-dash options Implemented a UUID v4 generator with customizable count (1-50), optional uppercase output, and dash-free format. Uses Math.random for UUID generation.不好的 commit message 示例fixed stuff update code wipCommit message 的目标是让六个月后的自己或其他贡献者能理解当时为什么要做这个变更。对于现在的你来说显而易见的决策细节对于未来的你来说可能完全遗忘。分支管理策略HarmonyKit 使用简化版的 Git Flowmain (默认分支稳定版本) ├── develop (开发分支集成所有 feature) │ ├── feat/uuid-generator │ ├── feat/color-converter │ └── fix/copy-button-crash └── release/v1.0.0main 分支始终处于可发布状态每个 commit 都对应一个已测试、可上架 AppGallery 的版本不允许直接 push只接受来自 develop 或 release 分支的 mergedevelop 分支日常开发的主分支所有 feature 和 fix 分支从这里切出也合并回这里定期如每周合并到 mainfeature 分支命名规范feat/功能简述或fix/问题简述# 创建 feature 分支gitcheckout-bfeat/radix-converter develop# 开发完成后合并回 developgitcheckout developgitmerge --no-ff feat/radix-convertergitbranch-dfeat/radix-converter使用--no-ffno fast-forward确保即使可以快进合并也创建一个 merge commit。保留的 merge commit 提供了清晰的feature 开始/结束标记。release 分支命名规范release/v版本号gitcheckout-brelease/v1.0.0 develop# 在 release 分支上进行最后的 bug 修复和版本号更新# 修改 AppScope/app.json5 中的 versionCode 和 versionNamegitcommit-mchore: bump version to 1.0.0gitcheckout maingitmerge --no-ff release/v1.0.0gittag-av1.0.0-mHarmonyKit v1.0.0gitcheckout developgitmerge --no-ff release/v1.0.0gitbranch-drelease/v1.0.0单人开发时的简化如果是完全的独立开发没有协作者可以进一步简化# 直接在 develop 上开发不需要 feature 分支gitcheckout develop# ... 开发 ...gitcommit-mfeat: add XYZ tool# 定期合并到 maingitcheckout maingitmerge develop当有外部贡献者提交 PR 时再切换到 feature 分支模式。开源项目的 Pull Request 工作流HarmonyKit 欢迎社区贡献为贡献者设计的 PR 工作流如下对贡献者Contributor# 1. Fork 仓库# 在 AtomGit/GitHub 上点击 Fork 按钮# 2. Clone 你的 forkgitclone https://atomgit.com/YOUR_USERNAME/harmony-kit.git# 3. 添加上游仓库gitremoteaddupstream https://atomgit.com/VON-/harmony-kit.git# 4. 创建功能分支gitcheckout-bfeat/my-new-tool# 5. 开发并提交gitadd.gitcommit-mfeat: add my new developer tool# 6. 同步上游更新如果有新的变更gitfetch upstreamgitrebase upstream/develop# 7. 推送到你的 forkgitpush origin feat/my-new-tool# 8. 在平台上创建 Pull Request# 从 feat/my-new-tool 分支向 VON-/harmony-kit 的 develop 分支发起 PR对维护者Maintainer审查 PR 的代码质量和功能完整性在本地测试 PR 的变更检查是否通过 CI 构建如果配置了 CI选择合并策略Squash and merge将 PR 的所有 commit 压缩为一个保持 main/develop 分支的历史简洁。适合大多数小型 PR。Merge commit保留 PR 的所有 commit 历史。适合大型、精心组织的 PR。合并后清理如果 PR 修改了main_pages.json等配置文件确认没有引入冲突版本号管理HarmonyKit 遵循 Semantic Versioning (SemVer)MAJOR.MINOR.PATCHMAJOR主版本不兼容的 API 变更。如修改 ToolItem 接口定义导致旧的工具配置不兼容。MINOR次版本向后兼容的新功能。如新增一个工具、添加一个新的组件属性。PATCH修订版本向后兼容的 Bug 修复。如修复剪贴板功能在特定设备上的问题。在AppScope/app.json5中versionName 使用 SemVer 格式versionCode 使用递增数值// v1.0.0 → versionCode: 1000000 // v1.1.0 → versionCode: 1001000 // v1.1.1 → versionCode: 1001001 // v2.0.0 → versionCode: 2000000versionCode 的计算公式MAJOR * 1000000 MINOR * 10000 PATCH * 100常见 Git 陷阱陷阱 1误提交 .hvigor 目录如果.hvigor目录已经被跟踪tracked仅仅添加到.gitignore不会使其被忽略# 从跟踪中移除但不删除本地文件gitrm-r--cached.hvigor# 提交移除操作gitcommit-mchore: remove .hvigor from version control# 之后 .gitignore 规则生效陷阱 2构建产物在切换分支时的冲突当你从 feature 分支切换回 develop 分支时构建产物entry/build/可能被识别为有变更的文件。如果.gitignore配置正确**/build这些文件不会被跟踪切换分支不会有问题。但如果你在 feature 分支上执行了构建又在 develop 分支上执行了构建没有中间 clean可能会出现构建缓存错乱。解决方案# 切换分支后清理构建产物hvigorw clean hvigorw assembleHap陷阱 3oh_modules 版本冲突当oh-package.json5中的依赖版本在不同分支间变化时可能出现oh_modules不一致。最佳实践# 切换分支后重新安装依赖gitcheckoutbranchrm-rfoh_modules ohpminstall可以在 Git hookspost-checkout中自动化这一步骤但对于小型项目手动执行更简单且不容易出错。陷阱 4local.properties 覆盖 SDK 路径如果local.properties被意外提交到仓库因为你忘记在首次提交前添加.gitignore需要在所有分支中修复gitrm--cachedlocal.propertiesgitcommit-mchore: remove local.properties from tracking# 确认 .gitignore 包含 /local.properties合约式 CI/CD 配置虽然 HarmonyKit 目前没有配置 CI/CD pipeline因为原子量级的 HAP 可以直接在本地构建但如果你需要为团队项目配置最简单的 CI 流程是# .gitee-ci.yml (atomgit CI 示例)name:Build HarmonyKiton:push:branches:[develop,main]pull_request:branches:[develop]jobs:build:runs-on:harmonyos-lateststeps:-uses:actions/checkoutv3-name:Install dependenciesrun:ohpm install-name:Build HAPrun:hvigorw assembleHap-p buildModerelease-name:Upload artifactuses:actions/upload-artifactv3with:name:harmonykit-happath:entry/build/default/output/default/entry-default-signed.hap结语Git 工作流是一个约定优于配置的领域。HarmonyKit 的 Git 工作流不追求理论上最优而是追求实践中可持续。核心原则只有五条不提交构建产物和 IDE 配置、commit message 要写变更的原因、feature 从 develop 切出并合并回 develop、版本号遵循 SemVer、社区贡献通过 Fork PR 模式。这些原则在项目只有 1 个人和 5 个文件时看起来是过度设计但当项目有 10 个贡献者和 100 个文件时它们是防止代码库混乱的最后防线。项目仓库https://atomgit.com/VON-/harmony-kit