DevEco Studio的开发者们，尤其是刚接触鸿蒙开发的朋友，估计不少人都有过这样的经历：项目在本地越写越大，突然想备份一下，或者想和队友一起改代码，却发现不知道该怎么把本地工程安全地托管到远程仓库。我最近刚把一个本地Harmony项目完整推送到Gitee，全程走了一遍版本控制的闭环，期间踩了不少坑，也理顺了DevEco Studio和Gitee协作的完整逻辑。这篇东西就是把我实际操作的过程、原理和教训一次性讲清楚，希望能帮大家少走弯路。

1. 为什么鸿蒙项目需要Gitee版本控制：从本地孤岛到协同开发

先聊一个最基础但常被忽略的问题：为什么一定要用Gitee这样的远程仓库来管理Harmony工程？

很多初学者觉得，Git本地提交就够了，反正代码在自己电脑上，历史记录也有了。但等你真正进入稍微正式一点的开发流程，就会发现本地仓库只是个孤岛。你换了电脑，或者硬盘出了问题，本地提交全没了；你想让A同学帮你看看某个模块的代码，总不能把整个工程压缩包发过去——那种"传压缩包—改完再传回来"的痛苦，经历过的人都懂。

Gitee作为国内常用的Git托管平台，解决的核心问题有三个：

第一是异地容灾。本地代码推送到远程，等于给项目多了一份异地备份。哪怕电脑报废，克隆下来就能继续干活。

第二是多人协作。它提供了一套基于分支的协作模型，每个人在自己分支上开发，通过Pull Request或Merge Request流程合并代码，冲突也能在可控范围内解决，而不是靠手动比对文件。

第三是版本回溯。提交历史里每一次变更都有记录，哪次改动引入的bug，用git log配合git blame基本能定位到具体的提交点。这对Harmony工程这种由配置文件、资源文件、代码文件交织的复杂结构特别重要。

那为什么特意选Gitee而不是国际平台？抛开网络因素不谈，Gitee在国内的访问速度和稳定性确实更适合大多数开发者。而且它支持免费私有仓库，对个人项目和团队早期项目都很友好。

DevEco Studio本身内置了Git支持，但它默认的远程仓库关联方式并不直观。我见过不少朋友在IDE里点了半天"Push"按钮，结果提示没有配置远程仓库地址，或者认证失败。根本原因是对Git的底层工作流不熟悉，IDE只是个图形壳，背后的原理还是那几条Git命令在起作用。

所以，在开始操作之前，先建立几个基本概念：

• 本地仓库：项目目录下的.git隐藏目录，记录了你所有的提交历史。
• 远程仓库：托管在Gitee服务器上的仓库，是你本地历史的一个"镜像"。
• 推送（Push）：把本地提交上传到远程。
• 拉取（Pull）：把远程更新下载到本地并合并。

理解了这些，后面的操作就有主线了。

2. 环境准备：DevEco Studio的Git集成与Gitee账号配置

这个步骤看起来简单，却是整个流程里最容易出问题的环节。先列一下我实际操作时需要准备的东西，每一样都有它存在的理由。

2.1 必须预装的部分

在打开DevEco Studio之前，先确认电脑上是否已经安装了Git。这一步很多人会忽略，因为DevEco Studio虽然内置了Git客户端相关的界面，但它实际上依赖系统级的Git命令行工具。

可以在终端或者命令提示符里运行：

git --version

如果返回了类似git version 2.39.0这样的信息，说明Git已经安装好了。如果没有，需要先去官网下载对应系统的安装包。安装的时候有个容易忽略的选项——Git会询问你关于PATH环境的设置。我的建议是选择"Git from the command line and also from 3rd-party software"，这样DevEco Studio才能正确调用Git命令。

2.2 在DevEco Studio中配置Git路径

打开DevEco Studio，依次进入：

• File->Settings（Windows）/DevEco Studio->Preferences（macOS）
• 找到Version Control->Git
• 在Path to Git executable中确认路径是否自动识别

如果这里显示红色的错误提示，说明IDE没有找到Git可执行文件。手动选择到Git的安装路径即可。Windows下通常是C:\Program Files\Git\bin\git.exe，macOS下通常是/usr/bin/git或者通过which git命令查询到的路径。

提示：Git路径配置正确是后面所有版本控制操作的前提。很多人点了Push没反应，先检查这一步。

2.3 Gitee账号与SSH密钥

Gitee仓库的访问方式有两种：HTTPS和SSH。HTTPS每次推送都需要输入用户名和密码或Token，SSH则通过密钥配对实现免密操作，更安全也省事。

我强烈推荐使用SSH。配置方法如下：

1. 在本地生成SSH密钥对（如果之前生成过就跳过）：

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

一路回车即可，会在用户目录下生成~/.ssh/id_rsa（私钥）和~/.ssh/id_rsa.pub（公钥）。

2. 打开Gitee官网，进入设置->安全设置->SSH公钥，把id_rsa.pub文件里的内容完整复制粘贴进去。

3. 在终端测试连接：

ssh -T git@gitee.com

如果看到欢迎信息，说明SSH配置成功。

这一节的重要性在于：认证问题解决了，后面的提交推送会比较顺畅；如果这步没做好，后面每次推送都可能弹出密码输入框，烦不胜烦。

2.4 在DevEco Studio中配置用户信息

新版本的Git要求在提交时知道你是谁，所以需要设置全局的用户名和邮箱，这些信息会记录在每次提交里：

git config --global user.name "你的昵称" git config --global user.email "你的邮箱"

也可以在DevEco Studio中通过Version Control->Git->Commit界面的用户信息区域直接填写。这个信息会成为提交历史的署名，建议多次确认拼写正确。

做完这些准备工作，环境就算就绪了。

3. 创建Gitee远程仓库与本地项目初始化的完整流程

环境准备好了，接下来进入核心操作：在Gitee上创建远程仓库，并将本地Harmony工程初始化为Git仓库。

3.1 Gitee上创建空仓库

登录Gitee，点击右上角的"新建仓库"，会看到一个表单需要填写：

• 仓库名称：建议与本地工程名一致或相关，比如harmony-app-demo。纯英文、用连字符分隔单词是主流做法，避免中文和空格。
• 路径：系统会自动根据名称生成访问路径，可以手动调整。
• 是否开源：个人学习项目可以选私有，团队项目根据需求选。
• 初始化仓库：有个关键选项问是否用Readme文件初始化仓库。注意，这里一定要选择"不初始化"，也就是不要勾选生成Readme、.gitignore、License这些文件的选项。

为什么不建议初始化？原因后面会讲，简单地说是为了避免和本地仓库的历史产生冲突，导致第一次推送被拒绝。

创建完成后，Gitee会显示一个仓库主页，里面有一个远程地址，形如：

git@gitee.com:你的用户名/harmony-app-demo.git

这个地址就是后面本地仓库要关联的远程目标。

3.2 本地工程的Git初始化

在DevEco Studio中打开你的Harmony项目，可以有两种操作方式：

方式一：通过IDE菜单VCS->Enable Version Control Integration...，选择Git，点击OK。这样IDE会自动在当前工程目录下执行git init。

方式二：直接在项目根目录下打开终端（IDE底部有Terminal标签页），手动执行：

git init

无论哪种方式，完成后项目目录下会出现一个.git隐藏文件夹，整个目录就变成一个Git工作树了。

此时，在DevEco Studio里打开Version Control工具窗口（通常在左侧或底部），应该能看到所有文件都被标成了红色（未跟踪状态）。

3.3 配置.gitignore：这是第一个容易踩坑的地方

Harmony工程包含大量不需要纳入版本控制的文件：本地配置文件、构建产物、临时文件等。如果没有合理的.gitignore，你会把这些垃圾文件也提交上去，导致仓库臃肿不堪。

DevEco Studio在创建Harmony工程时，通常会生成一个.gitignore文件。如果工程模板没带，就需要手动创建。

一个典型的Harmony工程.gitignore应该包含这些：

# 构建产物 /oh_modules/ /build/ /.cxx/ # 本地配置文件 /.idea/ *.iml /node_modules/ # 日志 *.log # 系统文件 .DS_Store Thumbs.db # 签名与密钥（安全性重要） *.p12 *.jks *.cer

注意：oh_modules是鸿蒙项目的依赖模块目录，体积巨大且可以由构建系统自动下载，一定不要提交。.idea是IDE的本地配置目录，每台电脑的配置可能不同，也不要提交。签名证书文件关系应用发布安全，更不能提交到远程仓库。

在DevEco Studio里创建.gitignore的方法很简单：在工程根目录右键 ->New->File，命名为.gitignore，粘贴上面内容即可。

3.4 第一次提交

配置好忽略文件后，打开Version Control窗口，在项目根目录上右键，选Git->Add（或直接使用快捷键Ctrl+Alt+A），把所有未跟踪文件加入暂存区。然后点击Commit按钮，填写提交信息，比如"init: 初始提交Harmony工程"。

提交完成后，Version Control窗口里应该能看到这次提交记录，所有文件变成白色（已提交状态）。

到此，本地仓库已经拥有了一条提交记录。但这只是万里长征第一步，真正的关键在推送。

4. 推送过程中的核心链路：关联远程仓库与认证处理

本地仓库有了，Gitee远程仓库也建好了，现在要做的是把两者连接起来，并完成第一次推送。这一步的坑最多，我把实际操作中遇到的问题和解决思路原原本本写出来。

4.1 关联远程仓库的正确姿势

在DevEco Studio中，可以通过图形界面操作：

• 打开Version Control窗口，选择Git->Manage Remotes...
• 点击加号，填入远程仓库名称（默认origin）和URL

也可以直接使用命令行，更直观：

git remote add origin git@gitee.com:你的用户名/harmony-app-demo.git

origin是Git默认的远程仓库别名，约定俗成，大家都叫这个名字，后面的推送和拉取命令都会引用它。

确认关联是否成功：

git remote -v

如果看到类似下面的输出，说明关联成功：

origin git@gitee.com:你的用户名/harmony-app-demo.git (fetch) origin git@gitee.com:你的用户名/harmony-app-demo.git (push)

4.2 首次推送：拒绝与强制

关联好了，接下来就是那一步经典的推送：

git push -u origin master

但如果你按照前面的建议创建的是空远程仓库，且本地默认分支是master，而Gitee现在默认分支通常是main，就会遇到下面这个问题。

我第一次推送的报错信息大致是这样的：

To git@gitee.com:your_name/harmony-app-demo.git ! [rejected] master -> master (non-fast-forward) error: failed to push some refs to 'git@gitee.com:...' hint: Updates were rejected because the tip of your current branch is behind hint: its remote counterpart. Integrate the remote changes...

翻译成人话：远程仓库里存在本地仓库没有的提交（比如Gitee自动生成的Readme），本地仓库的分支版本比远程仓库旧，Git出于安全考虑拒绝了覆盖操作。

这就是为什么我之前特别强调：在Gitee创建仓库时务必要选择"不初始化"。如果你手滑初始化了，或者远程已经有历史记录，你有两个解决思路：

第一种，把远程的修改拉下来合并：

git pull origin main --allow-unrelated-histories git push -u origin main

--allow-unrelated-histories这个参数很关键，它允许Git合并两个没有共同祖先的历史。但这种方法会让提交历史变得有点乱，看着不干净。

第二种，如果你的远程仓库是刚建好的空仓库，且确实不需要远程的任何文件，可以直接强制推送：

git push -u origin master -f

强制推送会用本地历史覆盖远程历史，适合远程仓库确实没内容、或者你确定不需要远程历史的情况。但这要小心，如果远程有别人提交的代码，强制推送会把别人的工作直接抹掉，所以使用前必须确认。

我是怎么处理的？说实话，我在Gitee上创建仓库时选择了空仓库，但DevEco Studio的Push操作默认推的是当前分支，而Gitee默认分支名可能是main。所以我在命令行用上面第二种方法，把本地master分支强制推送到了远程，然后将Gitee仓库的默认分支设置改成了master。

4.3 默认分支名的统一

这里要单独强调一下分支名的一致性。现在的Git init命令会自动根据init.defaultBranch配置决定默认分支名。如果全局配置里没设置，默认还是master；但Gitee新建仓库时默认分支经常是main。两边分支名不一致，推送拉取都会遇到些小麻烦。

建议提前统一：

git config --global init.defaultBranch main

然后在本地把当前分支改名为main：

git branch -m master main

再推送：

git push -u origin main

这样做的好处是让本地和远程的主分支名字保持一致，后续Pull Request等协作流程也不会出现"主分支在main和master之间来回切换"的混乱情况。

4.4 认证失败的处理经验

如果使用HTTPS方式关联远程仓库，推送时会要求输入Gitee的用户名和密码。需要注意：现在Gitee不再支持直接用账号密码推送代码，而是要求在设置中生成一个私人令牌（Personal Access Token），用这个Token作为密码输入。

所以，如果推送时提示认证失败，不用怀疑自己的密码，先去Gitee的设置->安全设置->私人令牌里生成一个新的Token，然后在推送提示中粘贴。

但用SSH方式就不存在这个问题，所有推送走密钥匹配。这也是我推荐SSH的一个原因：配置好之后真的是一劳永逸。

4.5 IDE的Push按钮无法使用怎么办

在DevEco Studio中，点击Push按钮有时会弹出错误，提示"Can't push refs"或者"Remote origin not found"。

这种情况几乎都是因为远程地址没配置好，或者当前分支没有上游分支。可以直接在IDE的终端中执行：

git push -u origin HEAD

HEAD表示当前所在分支，这样就把当前分支推送到远程同名的分支上，并建立跟踪关系。推送成功后，再回到IDE，Push按钮就能正常使用了。

5. 日常协作的版本控制节奏：分支策略与提交规范

推送成功一次，不代表版本控制爽了，真正的日常开发是一连串的提交、分支、合并、冲突处理。这个环节我结合Harmony开发的特点讲一下。

5.1 分支策略：别在主分支上直接改

有些同学追求省事，所有代码都直接在main或master上写，写完就提交，提交就推送。一个人开发游戏项目这样做勉强能行，但稍微复杂一点的Harmony工程，比如带多个模块（entry、feature、library等）的项目，并行开发很容易把主分支搞乱。

我建议的节奏是：主分支始终保留相对稳定的可用版本，开发新功能时从主分支拉出功能分支，测试稳定后再合并回主分支。

操作流程大致是：

# 从最新主分支拉出功能分支 git checkout main git pull git checkout -b feature/login-page # 在功能分支上开发，正常提交 git add . git commit -m "feat: 完成登录页面UI与基础逻辑" # 合并回主分支 git checkout main git merge feature/login-page git push

这种Git Flow的简化版，对于中小型Harmony项目已经够用，既保证了主分支的稳定性，又保留了每个功能的独立历史。

5.2 DevEco Studio中的分支切换

在DevEco Studio的右下角状态栏，会显示当前分支名。点击它，弹出分支菜单，你可以：

• 新建本地分支
• Checkout切换已存在的分支
• 比较分支差异
• 选择当前分支并Push

这里有个实际开发中容易踩的坑：Harmony工程的模块配置（module.json5等文件）在不同分支间切换时，可能会因为依赖版本不同而出现构建缓存混乱。切换分支后如果编译报错但代码看着没问题，建议执行：

• Build->Clean Project
• 再Build->Rebuild Project

清掉build和oh_modules里可能的脏缓存。这个动作不改变任何源代码，但经常能解决莫名其妙的问题。

5.3 提交信息规范：让历史可读

提交信息是被低估的工程能力。我看到很多人提交信息就写"更新"、"修改bug"，过了半个月回来看，根本不知道当时改了什么。

Harmony项目的代码往往涉及UI、API、数据层、权限配置等多个维度，提交信息建议遵循约定式提交的简单规范：

• feat：新功能
• fix：修复bug
• docs：文档变更
• refactor：重构（非修复非新功能）
• chore：构建、工具等杂项

示例：

feat: 新增登录页面指纹识别功能 - 实现用户指纹验证逻辑 - 接入生物识别API - 增加安全处理异常流程

为什么强调规范？因为git log --oneline看到的是十几年前的模糊信息。有一次我帮朋友排查一个崩溃问题，他的提交历史有二十多条"fix"记录，我只能一条条打开diff看，效率极低。良好的提交习惯，本质上是对未来的自己负责。

5.4 合并冲突：没有想象中可怕

很多初学者听到"冲突"就头皮发麻。实际上，在DevEco Studio中合并冲突已经被图形化得很友好了。

当两个分支修改了同一个文件的同一行代码时，Git无法自动合并，会把这个文件标记为冲突状态。此时DevEco Studio会弹出冲突解决界面，左侧是本地版本，右侧是远程/分支版本，中间是合并结果。你可以逐段选择采用哪边的代码，或者手动编辑中间区域。

处理完所有冲突后，标记为已解决，提交合并。原则上，只要你不是和队友同时改了同一行代码，冲突就比较容易合并。真正麻烦的是两个人改了同一个文件的不同部分，Git有些能自动合并，有些需要手动确认，这个只能靠经验积累手感。

5.5 忽略文件的时机也很重要

.gitignore只影响"还没有被跟踪"的文件。如果某个文件在加入.gitignore之前已经被git add过，那么它已经进入了版本控制，后续的gitignore修改不会生效。

我之前就犯过这个错误：把oh_modules整个目录提交到了仓库，推送到Gitee后发现远程仓库体积直接涨到几百MB，当时感觉相当尴尬。后来不得不从仓库中移除追踪：

git rm -r --cached oh_modules

--cached参数表示只从Git索引中移除，不会删掉本地文件。然后提交这个变更，再推送，远程仓库就瘦身成功了。

6. Gitee上的团队协作收尾：从推送到合并请求的实战衔接

本地推送到Gitee之后，如果是多人协作，通常还会走一条Pull Request的流程。这节说说在DevEco Studio和Gitee之间如何衔接。

6.1 用Gitee管理在线分支

当你在本地创建了一个新分支并推送后，打开Gitee仓库的"分支"页面，可以看到这个分支。此时，你可以发起一个Pull Request（简称PR），把功能分支的代码请求合并到主分支。

PR的好处很直接：

• 代码审查有据可依，每次改动都看得清清楚楚
• 自动检测冲突，提前暴露问题
• 合并历史保留在页面中，方便追溯

6.2 在DevEco Studio中更新本地

队友合并了一个PR之后，你的本地仓库还是旧代码，需要拉取更新：

git checkout main git pull

经常有开发者说推送和拉取"不顺畅"，大多数情况是分支跟踪关系没建立好。推送时用了-u参数（即--set-upstream），本地分支和远程分支的关系就绑定了，之后的git pull和git push就不需要再额外指定分支了。

6.3 远程仓库是团队的节拍器

我自己的体会是，远程仓库除了存代码之外，更像是一个团队的节拍器。每个人每天开工前先pull一下，工作结束前push一次，PR被review完合入主分支。这套节奏一旦建立起来，合作效率会明显提升，而且代码出问题时的沟通成本也低了很多。

Harmony开发中经常涉及公共模块的修改，比如某个组件库、或者公共工具类。如果大家不通过PR而是直接往主分支推，很容易动不动就覆盖了别人的成果，在DevEco Studio中表现出来就是各种冲突和丢失修改。现在大部分团队都通过分支+PR的方式来控制这种局面了。

7. 备份恢复场景：从Gitee克隆一个完整Harmony工程

版本控制不只是日常提交推送，还有一个重要的功能：任何时候从零恢复工程。

比如你换了台新电脑，想把这个仓库在新环境中跑起来。不需要再去拷贝工程文件，直接：

git clone git@gitee.com:你的用户名/harmony-app-demo.git

这个命令会把远程仓库的所有代码和历史下载到本地。克隆下来的工程虽然代码完整，但Harmony工程还需要重新安装依赖模块。在DevEco Studio中打开克隆下来的目录，等待IDE同步完成，或者手动执行构建，IDE会根据自己的依赖解析机制重新生成本地构建文件（如oh_modules），这是克隆项目后比较常见的操作。

还有一个小建议：重要版本发布时，除了Git历史的常规提交，最好在Gitee的"发行版"功能中创建一个对应的版本标签。这个标签对应一个不可变的历史快照，非常适合作为发布存档。操作上，只需要在本地打一个tag然后推送：

git tag v1.0.0 git push origin v1.0.0

后续不管代码怎么改，这个tag对应的版本都能一眼找到。

8. 实测中最值得记住的几个经验

整个流程走完之后，有几条心得想单独拿出来说，它们不属于任何一个步骤，但是很影响日常使用体验。

8.1 先规划再操作

很多推送失败都是因为前期规划不足。比如，在Gitee上创建仓库时没注意是否初始化，推送时遇阻；没有提前配置SSH，导致每次都要输账号密码。建议的顺序是：配好SSH -> 建空远程仓库 -> 本地init -> 提交 -> 关联远程 -> 推送。这个顺序走下来，几乎不会出问题。

8.2 不要在IDE里乱点"Updata Project"

在DevEco Studio里发现有更新时，不要盲目点"Update Project"按钮。先看一下更新来源是哪个分支，是不是自己当前所在分支，以及本地有没有未提交的改动。我的经验是：先本地手动提交所有改动，再执行pull，能避免大量冲突。因为未提交的改动与远程更新相遇时，Git的合并行为不可控。

8.3 善用Gitee的"查看文件"页面

推送完成后，打开Gitee仓库的文件页面，自己检查一下哪些文件被意外提交了。比如.jks签名文件、.p12密钥文件，这类文件如果在远程仓库里出现，要尽快用git rm --cached移除并修改对应的忽略规则。不要等到发布的时候才发现密钥泄露，那就要重新生成证书了，劳民伤财。

8.4 提交信息的粒度

提交是越小越好吗？也不是。频繁的"update"提交会把历史搞得像流水账。理想的情况是，一次提交对应一个逻辑完整的改动，比如"完成登录页面"是一个提交，"调整登录页按钮样式"其实应该合并到前一个提交里。如果已经提交了，可以使用git commit --amend修正上一个提交的说明，注意这只适用于还没有推送的本地提交。

8.5 网络波动下的推送兜底

有一次我推送到一半网络中断了，看到提示报错。这个情况不用慌，Git是具备原子性的，要么完全成功，要么完全失败，不可能出现推送一半的中间状态。重新执行push命令，如果中断提交不完整，不会有大问题。如果线上分支出现了意外的中间提交，通常是Gitee的清理机制会自动处理，或者再重新推送一次正确分支覆盖即可。

到这里，从DevEco Studio推送本地Harmony项目到Gitee的完整链路已经全部走通了。版本控制不是负担，而是给开发上了保险。初期多花十几分钟配置好SSH和分支模型，后面每天都在受益。希望这篇内容对大家有所帮助，如果按照这个流程操作，应该不会再遇到那种让人挠头的推送问题了。