在这里插入图片描述

HarmonyKit | 鸿蒙开发：Git 工作流与 .gitignore 最佳实践

引言：版本控制不只是 git add 和 git commit

HarmonyKit 从第一个 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？

  1. 体积巨大：oh_modules 包含所有依赖包的完整源码，可能达到数百 MB。HarmonyKit 的两个依赖（hypium 和 hamock）体积不大，但原则上的原因仍然成立。

  2. 版本锁定由 oh-package-lock.json5 管理：和 package-lock.json 一样，锁文件记录了精确的依赖版本。任何人 clone 项目后执行 ohpm install 即可获得与原作者完全一致的依赖版本。

  3. 不同平台的二进制差异：部分 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         # 构建报告

这些缓存文件有以下几个特征：

  1. 绝对路径硬编码：缓存中记录了文件的绝对路径（如 /Users/wangxinjie/Desktop/harmony/harmonykit/...）。不同的开发者路径不同，提交到仓库会导致路径不一致。

  2. 频繁变化：每次构建都会更新缓存信息，产生持续的 git 变更。

  3. 可重建：删除 .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。

/.idea：IDE 项目配置

.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、.clangd：C/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 tool
fix 修复 Bug fix: cannot copy empty text to clipboard
refactor 代码重构 refactor: extract color logic to ColorUtils
style 样式调整 style: adjust tool card shadow and spacing
docs 文档变更 docs: add contributing guide
chore 构建/工具配置 chore: update hvigor to 6.1.1
test 测试相关 test: add unit tests for HashUtils

HarmonyKit 不强制在 commit message 中关联 issue 编号，因为多数变更是自发的功能开发而非对特定 issue 的响应。但如果某个 commit 确实解决了某个 issue，commit 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
wip

Commit message 的目标是让六个月后的自己（或其他贡献者）能理解"当时为什么要做这个变更"。对于现在的你来说"显而易见"的决策细节，对于未来的你来说可能完全遗忘。

分支管理策略

HarmonyKit 使用简化版的 Git Flow：

main (默认分支，稳定版本)
├── develop (开发分支，集成所有 feature)
│   ├── feat/uuid-generator
│   ├── feat/color-converter
│   └── fix/copy-button-crash
└── release/v1.0.0

main 分支

  • 始终处于可发布状态
  • 每个 commit 都对应一个已测试、可上架 AppGallery 的版本
  • 不允许直接 push，只接受来自 develop 或 release 分支的 merge

develop 分支

  • 日常开发的主分支
  • 所有 feature 和 fix 分支从这里切出，也合并回这里
  • 定期（如每周）合并到 main

feature 分支

命名规范：feat/<功能简述> 或 fix/<问题简述>

# 创建 feature 分支
git checkout -b feat/radix-converter develop

# 开发完成后合并回 develop
git checkout develop
git merge --no-ff feat/radix-converter
git branch -d feat/radix-converter

使用 --no-ff（no fast-forward）确保即使可以快进合并也创建一个 merge commit。保留的 merge commit 提供了清晰的"feature 开始/结束"标记。

release 分支

命名规范：release/v<版本号>

git checkout -b release/v1.0.0 develop
# 在 release 分支上进行最后的 bug 修复和版本号更新
# 修改 AppScope/app.json5 中的 versionCode 和 versionName
git commit -m "chore: bump version to 1.0.0"
git checkout main
git merge --no-ff release/v1.0.0
git tag -a v1.0.0 -m "HarmonyKit v1.0.0"
git checkout develop
git merge --no-ff release/v1.0.0
git branch -d release/v1.0.0

单人开发时的简化

如果是完全的独立开发（没有协作者），可以进一步简化：

# 直接在 develop 上开发，不需要 feature 分支
git checkout develop
# ... 开发 ...
git commit -m "feat: add XYZ tool"
# 定期合并到 main
git checkout main
git merge develop

当有外部贡献者提交 PR 时，再切换到 feature 分支模式。

开源项目的 Pull Request 工作流

HarmonyKit 欢迎社区贡献，为贡献者设计的 PR 工作流如下：

对贡献者（Contributor）：

# 1. Fork 仓库
# 在 AtomGit/GitHub 上点击 Fork 按钮

# 2. Clone 你的 fork
git clone https://atomgit.com/YOUR_USERNAME/harmony-kit.git

# 3. 添加上游仓库
git remote add upstream https://atomgit.com/VON-/harmony-kit.git

# 4. 创建功能分支
git checkout -b feat/my-new-tool

# 5. 开发并提交
git add .
git commit -m "feat: add my new developer tool"

# 6. 同步上游更新（如果有新的变更）
git fetch upstream
git rebase upstream/develop

# 7. 推送到你的 fork
git push origin feat/my-new-tool

# 8. 在平台上创建 Pull Request
# 从 feat/my-new-tool 分支向 VON-/harmony-kit 的 develop 分支发起 PR

对维护者（Maintainer）：

  1. 审查 PR 的代码质量和功能完整性
  2. 在本地测试 PR 的变更
  3. 检查是否通过 CI 构建（如果配置了 CI）
  4. 选择合并策略：
    • Squash and merge：将 PR 的所有 commit 压缩为一个，保持 main/develop 分支的历史简洁。适合大多数小型 PR。
    • Merge commit：保留 PR 的所有 commit 历史。适合大型、精心组织的 PR。
  5. 合并后清理：如果 PR 修改了 main_pages.json 等配置文件，确认没有引入冲突

版本号管理

HarmonyKit 遵循 Semantic Versioning (SemVer)：

MAJOR.MINOR.PATCH
  • MAJOR（主版本）：不兼容的 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: 2000000

versionCode 的计算公式：MAJOR * 1000000 + MINOR * 10000 + PATCH * 100

常见 Git 陷阱

陷阱 1：误提交 .hvigor 目录

如果 .hvigor 目录已经被跟踪（tracked），仅仅添加到 .gitignore 不会使其被忽略：

# 从跟踪中移除（但不删除本地文件）
git rm -r --cached .hvigor

# 提交移除操作
git commit -m "chore: remove .hvigor from version control"

# 之后 .gitignore 规则生效

陷阱 2：构建产物在切换分支时的冲突

当你从 feature 分支切换回 develop 分支时，构建产物（entry/build/）可能被识别为有变更的文件。如果 .gitignore 配置正确（**/build），这些文件不会被跟踪，切换分支不会有问题。

但如果你在 feature 分支上执行了构建，又在 develop 分支上执行了构建（没有中间 clean），可能会出现构建缓存错乱。解决方案：

# 切换分支后清理构建产物
hvigorw clean
hvigorw assembleHap

陷阱 3：oh_modules 版本冲突

当 oh-package.json5 中的依赖版本在不同分支间变化时，可能出现 oh_modules 不一致。最佳实践：

# 切换分支后重新安装依赖
git checkout <branch>
rm -rf oh_modules
ohpm install

可以在 Git hooks（post-checkout）中自动化这一步骤，但对于小型项目，手动执行更简单且不容易出错。

陷阱 4：local.properties 覆盖 SDK 路径

如果 local.properties 被意外提交到仓库（因为你忘记在首次提交前添加 .gitignore），需要在所有分支中修复：

git rm --cached local.properties
git commit -m "chore: remove local.properties from tracking"
# 确认 .gitignore 包含 /local.properties

合约式 CI/CD 配置

虽然 HarmonyKit 目前没有配置 CI/CD pipeline（因为原子量级的 HAP 可以直接在本地构建），但如果你需要为团队项目配置，最简单的 CI 流程是：

# .gitee-ci.yml (atomgit CI 示例)
name: Build HarmonyKit

on:
  push:
    branches: [develop, main]
  pull_request:
    branches: [develop]

jobs:
  build:
    runs-on: harmonyos-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install dependencies
        run: ohpm install
      - name: Build HAP
        run: hvigorw assembleHap -p buildMode=release
      - name: Upload artifact
        uses: actions/upload-artifact@v3
        with:
          name: harmonykit-hap
          path: 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

# harmonyos # git # 华为 # 缓存 # 鸿蒙
Logo
人工智能6S服务平台

作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐

鸿蒙版剪映重磅更新：会员订阅、云空间上线，还能畅玩超多AI功能

如果你已经不满足于“随便剪剪”，而是对成片有更高的要求，会员订阅功能就是为你准备的。开通会员后，海量精选素材和精美模板无限用，还有智能字幕识别、AI画质修复、人像精修及轻量AI创作等AI能力一并加持，大幅简化后期繁琐操作。以前做视频，需要写脚本、筹备素材、掌握剪辑技巧，有了AI文字成片功能，你只需要输入一段文字，或者输入需求让AI帮你写一段文案，剩下的画面、配音和字幕都可以交给AI完成。此次升级，

avatar 人工智能6S服务平台

鸿蒙报错速查：struct 里嵌 class 声明就炸，Unexpected token 编译报错，根因 + 真解法

鸿蒙报错速查：struct 里嵌 class 声明就炸，Unexpected token 编译报错，根因 + 真解法报错原文常伴生报错：报错触发场景你写鸿蒙 ArkTS 时，在 @Component

avatar 人工智能6S服务平台

鸿蒙报错速查：arkts-no-destruct-decls 禁用解构声明，const { x, y } = obj 就炸，根因 + 真解法

鸿蒙报错速查：arkts-no-destruct-decls 禁用解构声明，const { x, y } = obj 就炸，根因 + 真解法报错原文常伴生报错：报错触发场景你写鸿蒙 ArkTS 时，用

avatar 人工智能6S服务平台