企业官网建设流程全解析

开始工作。

做鸿蒙开发的兄弟，尤其是个人开发者或者小团队，应该都经历过这种痛：代码改着改着，设备调通了，结果一兴奋把某个能用的版本覆盖了，想回退却找不到痕迹。或者项目越写越大，想拆个模块、修个bug，连个对照都没有，只能靠感觉。我自己在DevEco Studio里折腾Harmony项目时，就狠狠被这个问题绊过几次，后来老老实实把Gitee用起来，才算彻底把开发节奏握在手里。这篇就把我从本地瞎写、到用DevEco Studio推送项目到Gitee做版本控制的完整过程，包括踩过的坑和总结出的套路，一次性讲清楚。

这个内容适合谁看？刚接触Harmony开发、想给项目建立版本管理的新手，或者已经开始用Gitee但操作不熟练、被各种报错劝退的开发者。读完之后你不仅能完成首次推送，还能把日常提交、分支切换、回滚、多人协作这一整套流程跑顺，真正体会到版本控制带来的安全感。

1. 项目里为什么要动Gitee：不是仪式感，是保命

1.1 没有版本控制的Harmony项目有多脆弱

先说说我自己的经历。最早做一个ArkTS的Demo，改一个界面状态，手一抖把整个入口文件逻辑翻新了，结果新方案没跑通，旧版本又找不回来了。没有版本管理，就意味着你的每一次“保存”都是单向通道，没有后悔药。后来我养成了每隔一段时间手动复制备份的习惯，备份文件夹越攒越多，名字从"backup"一路排到"backup_final_ver3"，最后连自己都分不清谁是谁。

更麻烦的是多设备调试。我平时常用一台手机和一台平板交叉验证布局，有时候为了测某个兼容性问题，改完代码之后连哪一版部署到哪台设备都记不清。这个时候脑子里浮现的不只是“乱”，而是对一个确定性系统的渴望——我需要知道某一行代码是什么时候被改的、为什么要改、以及出问题的时候能准确地退回到上一个稳定状态。版本控制解决的就是这个问题，Gitee只是承载这个机制的载体。

1.2 为什么我选Gitee而不是其他平台

用Gitee的原因很实际。第一，国内访问稳定，不用费劲等上传，速度这一块对日常push和clone的体验影响非常大；第二，免费私有仓库对个人项目足够友好，Harmony项目有些业务代码和签名信息不想公开，私有仓库就省心很多；第三，DevEco Studio本身内置了完整Git支持，而Gitee的仓库地址可以直接配合使用，两者之间几乎没有额外配置成本。

有人会问，用本地Git不就好了，为什么非要推送到远程？说白了，本地仓库只能帮你记录历史，解决不了“电脑坏了怎么办”“想换台电脑继续写怎么办”“想和别人协作怎么办”这类问题。Gitee作为远程存储，相当于给你的代码上了一道异地备份，同时提供了分支管理、权限控制、提交记录可视化的能力。推送这个动作，就是把本地的工作成果同步到一个你不容易弄丢的地方。

1.3 核心概念：本地Git、远程仓库和DevEco Studio的关系

这里有必要理清一个很容易懵的点。DevEco Studio不是版本控制系统，它只是继承自IDEA那个强大的集成环境，内置了Git操作面板。真正干活的是Git本身，而Gitee是挂在Git之上的一个远程仓库托管平台。所以你的电脑上必须先装好Git，然后在DevEco Studio里配置好Git路径，编辑器才能调用Git命令完成init、add、commit、push这些动作。

可以这么理解：DevEco Studio是操作台，Git是引擎，Gitee是车库。你在操作台上按几个按钮，引擎就把代码打包好送去车库停放。按钮背后执行的是Git命令行，所以哪怕你是纯IDE流选手，也建议把几个常用命令记住，万一IDE界面抽风、或者遇到命令行排查的场景，不至于干瞪眼。

2. 环境准备：先把工具链理顺再动手

2.1 安装并验证Git环境

Windows系统的开发者建议直接去Git官网下安装包，一路默认选项装完就可以。macOS用户可以用Homebrew执行brew install git，或者下载官方安装器。装完之后，打开DevEco Studio，进入File > Settings > Version Control > Git，确认Git的可执行文件路径已经被识别。如果DevEco Studio检测不到Git，大概率是环境变量没生效，重启一下IDE，或者手动指定git.exe的路径。

验证Git是否装好，老规矩，在终端敲一句git --version，能输出版本号就算成了。很多新手在这一步就卡住，其实大多数情况是安装时没有勾选“Add Git to PATH”选项，或者安装完成后没有重启终端和IDE。这一步一定要确认好，不然后面所有按钮都是灰的。

2.2 配置身份信息与SSH密钥

Git每次提交都会记录作者信息，这个信息的价值在回看历史时才会体现。在终端执行：

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

这两行命令配置的是全局身份，可以理解成你的代码签名。如果公司或团队有统一的代码托管账号，建议保持邮箱跟Gitee账号一致，这样提交记录能正确关联到人。

接下来是SSH密钥。虽然DevEco Studio也能用HTTPS方式推送，但HTTPS方式每次都要输入账号密码或私人令牌，比较烦。SSH密钥用起来舒服，一次配置，长期免密。生成密钥的方式：

ssh-keygen -t rsa -b 4096 -C "你的邮箱"

一路回车即可，默认生成路径在用户目录下的.ssh文件夹里。生成完后，打开公钥文件（id_rsa.pub），复制全部内容，登录Gitee，在“设置 > SSH公钥”里粘贴保存。然后在终端里执行ssh -T git@gitee.com，看到成功提示就代表通了。

注意：SSH私钥就是id_rsa这个文件，千万别把它传到代码仓库或者发给任何人。泄露私钥等于把你的仓库大门钥匙交出去了。

2.3 在Gitee上创建仓库时的几个选择

在Gitee网页上点击“新建仓库”，重点留意几个选项。仓库名称尽量和项目功能对齐，最好用英文或拼音，中文字段在某些Git操作和URL拼接中会带来不必要的麻烦。默认分支建议选main，符合现在的命名习惯。

初始化仓库时，新手建议勾选“初始化仓库”并加入README和.gitignore。不过如果你本地已经有代码，想以本地为准推上去，就不必勾选，不然远程仓库会有一次初始提交，和本地历史对不上，第一次推送就得多处理一次合并。这个取舍我在实操部分会详细展开。

私有还是公开？没有开源计划就果断私有。虽然Gitee私有仓库有成员人数限制，但对个人项目来说完全够用。等哪天想开源了，再切公开也不迟。

3. 本地项目推送到Gitee的完整实操

3.1 在DevEco Studio里初始化本地仓库

打开DevEco Studio的Harmony项目，点击顶部菜单的VCS，选择Enable Version Control Integration。这里特别说一下，新版本DevEco Studio已经不需要先执行git init命令了，直接通过这个菜单就能为当前项目创建本地Git仓库。如果依然想用命令行，也可以在项目根目录执行git init，效果一样。

初始化成功后，项目文件名会带上不同颜色标记，红色代表未跟踪文件，绿色代表新增但未提交，蓝色代表已修改。没有这些颜色，说明Git还没接管这个目录。

这里有一个值得提醒的点：DevEco Studio的底部有一个“Git”工具窗口入口，Log页签会展示详细的提交历史。个人开发时，我习惯开着Log面板写代码，每完成一个功能点就看一眼历史记录的变化，那种一切尽在掌握的感觉，能抵消不少调试带来的焦虑。

3.2 首次提交：add和commit的组合拳

初始化之后，右键项目根目录，选择Git > Add，把文件加入暂存区。然后可以在提交界面勾选本次要提交的文件，填写Commit Message。提交信息我建议按照“类型: 描述”的格式来写，比如“feat: 新增首页轮播组件”或“fix: 修复设置页崩溃问题”。这样到了回看历史的时候，扫一眼提交信息就知道这个节点干了什么。

首次提交在终端里的等价命令是这样：

git add . git commit -m "feat: 初始化项目结构"

git add .的“.”代表把当前目录的所有变更加入暂存区。如果项目里有些文件你根本不想让它进仓库，比如构建产物、本地密钥、依赖缓存目录，就一定要先处理.gitignore，再执行add，不然什么都往里怼，后面清理会非常痛苦。.gitignore的具体写法我放在第4节专门讲。

3.3 关联远程仓库并完成第一次push

到Gitee仓库主页，复制仓库地址，注意区分HTTPS和SSH。推荐用SSH格式，也就是git@gitee.com:用户名/仓库名.git这个样子的地址。然后在DevEco Studio菜单中找到VCS > Git > Remotes，添加远程仓库地址，给远程仓库起个名字，默认是origin。

接下来就可以执行push了。在IDE里点击推送按钮，第一次推送后远程分支不存在，DevEco Studio会自动判断并弹出推荐命令。终端里对应的命令是：

git remote add origin git@gitee.com:用户名/仓库名.git git push -u origin main

-u这个参数的意思是设置上游分支，也就是告诉Git：以后在这个分支上执行git push时，默认推送到origin的main分支。第一次推送跑完，打开Gitee仓库页面，看到本地文件整整齐齐出现在上面，这个动作就算彻底完成了。

这里如果出现! [rejected]或者提示远程有本地没有的提交，说明远程仓库初始化时光标选择了生成README或.gitignore，而本地也产生了初始提交，Git认为两边历史没有共同基础。处理方法有两种：一是把本地历史强行覆盖远程历史，二是先拉取远程内容再合并。个人建议用后来这种方式，因为强制覆盖容易把远程初始化的文件丢掉。

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

--allow-unrelated-histories这个参数，本质上就是告诉Git“我知道两边历史没有关联，但我就是要合并”，Git不会无脑拒绝。这也是新手很容易卡住的点，后面我在问题排查中会再提一遍。

4. 写出合格的Harmony项目.gitignore：少给自己挖坑

4.1 哪些文件绝对不能进仓库

Harmony项目的工程目录里隐藏着不少“不能用版本控制管理”的东西，最常见的是build目录，它产出的全是编译中间文件，每次构建都可能变化，放进Git里除了制造冲突没有别的意义。还有oh_modules，这是三方依赖下载下来的缓存目录，换个环境重新同步就行，不需要纳入版本控制。

另外一个容易被忽视的坑是签名文件。Harmony应用打包需要用到.p12证书文件、.p7b描述文件、.cer证书文件，这些文件一旦泄露，就相当于把应用的签名私密信息暴露了，别人可以拿它去签名你的应用。密钥文件的价值和私钥同等量级，不应该进仓库，更不应该推到远程。如果团队确实需要共享调试签名，也建议单独走其他安全渠道分发，而不是放在Git仓库里。

以及本地IDE配置文件，比如.idea目录、local.properties、hvigor的本地缓存等，这些都跟具体开发机的环境强相关。另外项目里的.hvigor文件夹是构建引擎的缓存，.cxx是native构建的缓存目录，统统建议忽略。

4.2 一份可以直接参考的.gitignore清单

我把自己项目里用的.gitignore简化了一份，你可以根据实际需求增删：

# 构建产物 build/ !.keystore *.hsp *.hap # 依赖与缓存 oh_modules/ .hvigor/ .cxx/ local.properties # IDE配置 .idea/ *.iml # 签名与密钥 *.p12 *.p7b *.cer *.mobileprovision # 系统文件 .DS_Store Thumbs.db # 日志 *.log

注意默认生成的.gitignore末尾还有一个!.keystore这样的取反规则，意思是虽然*.keystore格式被忽略，但特殊情况可以留一下。如果你是个人调试开发，真机/模拟器装的是调试包，可以不用管理这个文件。但如果是正式发布签名，严谨的做法是把签名文件放到仓库之外的独立目录，用环境变量或本地路径动态引用。

4.3 已经错推了敏感文件怎么办

这种错误我见过不少，我自己也踩过一次。文件已经被推送到了远程仓库，即使后来从仓库里删除，它依然存在于Git历史中，别人只要翻历史就能拿到内容。所以如果已经推送了密钥文件之类的敏感内容，最稳妥的做法是：

第一，立即在代码托管平台把那个仓库的访问权限收一下，公开仓库先转私有；第二，在本地把那个文件彻底移除并提交，让后续代码不再携带；第三，如果是证书和密码泄露，直接在应用市场重新生成一套签名，旧的那套作废；第四，如果泄露的是比较敏感的项目代码，可以考虑重写历史，但重写历史这个操作对团队协作有影响，需要谨慎评估。

提醒一句：不要单纯依赖.gitignore来保护密钥，它只是在正常流程里“避免误提交”的提醒机制，一旦你手动强制加入、或者改错文件名，它不会拦你，最后一道防线还是你的操作习惯。

5. 日常开发里的版本控制节奏与团队协作玩法

5.1 commit时机的把握：勤提交、语义化描述

很多人一开始容易走向两个极端：要么一个功能写了三天才commit一次，要么每改一个字符就commit一次。前者让历史记录方差太大，回退时颗粒度太粗；后者让历史被大量无效更新刷屏，完全没有可读性。我自己比较习惯的做法是：一个可以编译通过的、功能上有边界的改动，就提交一次；边写边调、没跑起来的状态，绝不commit。

举个例子，做登录页面。我会拆成“搭建页面结构”、“接入表单校验”、“对接登录接口”、“处理异常状态”几个提交点。每一步完成，代码都能跑，然后commit。这样万一某一步改坏了，我可以精确地回到“页面结构刚搭好”的状态，而不是整个功能连锅端。

commit message也是同理，尽量一句话说清楚做了什么。我看到很多项目里的提交记录是“update”“fix bug”“aaa”，这种信息在三个月后回看时，基本等于没有。写清楚“修复了什么bug”“新增了什么功能”，对自己和对协作者都是尊重。

5.2 分支管理与标签：个人项目也用得上

有人觉得我是一个人开发，分支没什么用。但实际上分支的价值不只是多人协作，它可以帮你隔离试验性方案。我在做某个复杂动画时，经常开一个feature分支去试验不同的动效思路，写坏了直接切回main，完全不影响稳定版本。如果直接在主分支上改来改去，就会出现“这个版本跑得好好的，但主分支已经被改坏了”的尴尬局面。

常用的简单分支模型是这样的：main分支永远保持可发布状态，开发时从main拉一个feature分支，功能完成后合并回main。合并时可以勾选删除分支，保持分支列表干净。

在DevEco Studio底部工具栏也能看到当前分支名，点击即可切换。更规范的团队还可以利用Gitee的分支保护功能，把main设置为受保护分支，不允许直接推送，必须先发起Pull Request才能合入。这个对个人项目是可选操作，但对团队来说是刚需。虽然Harmony项目纯前端逻辑相对独立，但一旦多人粘着同一个工程改，保护措施就非常值得花很少的时间去配置好。

至于Tag，我建议每个可发布的版本打一个标签，例如v1.0.0。在Gitee上，这个标签可以直接绑定发行版，未来想精确取某一次发布对应的源码，点一下标签就能找到。标签在版本迭代过程中的价值，等你要给用户复现一个问题时就懂了。

5.3 多人协作：clone、pull、push的闭环

对团队来说，新成员拿到项目后做的第一件事就是git clone仓库地址，把远程代码拉到自己电脑上开始开发。日常开发时，每次动手写代码之前先git pull更新远程最新代码，写完push。如果本地改了某个文件，而远程也有人改了同一个文件，push时就会遇到冲突。

解决冲突的流程是：pull下来，Git会在冲突文件里用<<<<<<< HEAD、=======、>>>>>>>标记冲突区域，你需要手动判断保留哪部分内容。改完之后add、commit、再push。DevEco Studio提供了冲突解决的三路合并界面，可以看到本地版本、远程版本和合并结果，比直接用文本编辑器改要直观很多。这也是很多人问“DevEco Studio能解决Git冲突吗”的答案，它不仅能，而且做得挺好。

还有一个非常重要的协作习惯：不要直接往main分支乱推。哪怕人少，也建议大家都从main拉分支开发，必要时通过Pull Request来合入。这样每一笔改动都有迹可查，review过一个环节，能避免不少低级错误。团队规矩越早立下来，后面越省心。

6. 常见问题与排查技巧实录

6.1 push被拒绝，提示“远程有本地没有的内容”

这个问题前面提过一次，再展开一下。出现这种报错，本质上是因为远程仓库里有本地仓库不存在的提交记录，常见于远程创建仓库时勾选了初始化README或.gitignore，或者队友先推过代码而你没有同步。此时先pull，再push就好。关键是pull的时候，如果两边历史毫不相关，Git可能拒绝合并，要加--allow-unrelated-histories参数。

如果远程那些初始化文件根本不需要，比如只生成了README.md，但你本地已经有自己的README了，你完全可以用强制推送覆盖它。要注意，强制推送会丢弃远程对应分支上的所有提交，如果有其他人开发和推送过代码，这样做会直接弄丢别人东西，非常危险。所以在强制推送前先确认分支上只有你自己一个人在用。

这个操作在终端里是：

git push origin main --force

DevEco Studio推送界面的“Force Push”选项同理，除非你确定远程分支上的历史没有价值，否则不要点。

6.2 每次push都要输入用户名密码，怎么变成免密

如果当初clone或remote地址用的是HTTPS，push时会要求输入Gitee的用户名密码。但Gitee直接让你输密码已经不太好使，它更推荐使用私人令牌。这个令牌在Gitee“设置 > 私人令牌”里生成，然后push时把令牌当作密码填进去，Git会把令牌缓存下来，下次不再问。个人项目的实际操作感受是，换成SSH方式最省事，配置一次之后就再也不会被认证问题烦了。

如果想配置完SSH之后，把原来HTTPS的remote地址切换过来，用下面命令：

git remote set-url origin git@gitee.com:用户名/仓库名.git

这个命令不改变任何代码内容，只是把远程地址换了。切换后执行git remote -v确认地址无误即可。

6.3 换行符差异导致的整文件改动

Windows和macOS对换行符的处理不一样，Windows常用CRLF，Linux/macOS常用LF。如果团队成员跨平台开发，很容易出现“我什么都没改，但git status显示一堆文件有变化”的情况，打开一看全是行尾符差异。

解决方法是让Git统一处理换行符。在仓库根目录添加一个.gitattributes文件，写入：

* text=auto eol=lf *.bat text eol=crlf

这样Git会在检出时自动转换换行符，不同平台上的差异就不会再污染diff。对Harmony项目这种多人协作场景，越早加入这个文件越好。如果已经产生了大量换行符差异，建议在加入.gitattributes后执行一次git add --renormalize .来统一整个仓库的行尾状态。

6.4 想回到某个历史版本，但又怕把新代码弄丢

这时候不要用reset，优先用revert。reset会删除提交历史，好像那段时光被抹掉一样；revert则是通过创建一个新提交来撤销旧提交的内容，历史被完整保留。个人经验是，凡是涉及到有可能想找回的操作，保守一点永远不会错。

如果你想放弃本地未提交的修改，用git checkout -- 文件路径可以把文件还原到最近一次commit状态。如果只改了一部分文件，也可以打开DevEco Studio的Local Changes面板，右键某文件选择Revert，比命令行清晰很多。

如果改乱了整个分支，而且确定不要这堆改动，再考虑git reset --hard。但是reset --hard会同时丢掉工作区未提交的修改和已经提交的历史，使用前务必做备份或确认没有价值。

6.5 误提交了大体积文件或提交了不该提交的文件

Harmony项目如果误把整个build目录提交进去，仓库体积会迅速膨胀，push和clone都会越来越慢。先把不需要的文件加入.gitignore并提交一次，再把大文件从Git历史中清除。后者的常用操作是filter-branch或filter-repo，但重写历史对远程仓库会有影响，如果团队协作中别人已经拉了这些历史，重写会让所有人的仓库状态变得很混乱。

有个更快的方案：Gitee仓库设置里有一次“清理历史”的操作入口，但通常也会小心操作。真正稳妥的安排，还是在一开始就配置好.gitignore，并且commit前扫一眼变更文件列表，发现大文件直接先处理掉。

7. 我在实际使用中沉淀的几个习惯

把Gitee用起来不难，难的是稳定保持。我自己在使用过程中逐步沉淀了一些习惯，每次重装环境、换新电脑也都能丝滑衔接。这套流程跑顺之后，开发时的心理负担小了太多，代码也不再是“一次修改、终身焦虑”的状态。

第一，每次开工先pull，每次收工前push。哪怕今天只改了一个文件，只要有可用进展，就及时推到远程。远程仓库就是我对外界保护代码的备份，再也不用担心电脑硬盘出意外。

第二，签名文件绝不进Git仓库。无论团队协作还是个人项目，签名文件都单独放一个安全的地方，配置里用相对路径或引用环境变量去访问。真要共享，走其他安全渠道，而不是丢在仓库里。

第三，提交信息写得像给未来的自己看。写完代码那一刻你是最懂这段逻辑的人，一段时间之后可能就忘了。把“为什么改”写进提交信息，比写“改了哪些文件”更值钱。

第四，定期从Gitee上重新clone一次项目到另一个目录，确认真实依赖和构建配置都齐全。很多人本地项目能跑，是因为IDE缓存和本机环境在兜底，换一个干净环境就原形毕露。这个做法还能顺便检验一下.gitignore是否影响了必要的配置文件。

版本控制不是流程负担，它只是给你一种确定的掌控感。尤其做Harmony开发这种涉及真机调试、多平台适配、反复调优的场景，有一个干净、可追溯、能回滚的代码仓库，相当于给自己的开发生涯装了一条安全带。希望这篇能把你在DevEco Studio里使用Gitee之路上的大部分坑提前填平，剩下的，就放心跑起来再看。