做技术这些年我一直建议身边朋友把代码托管这件事认真对待。过去大家习惯把项目文件丢在U盘、网盘甚至微信文件传输助手里等到要版本回退、多人协作、或者换电脑继续写的时候才意识到问题有多痛。华为云CodeHub就是用来解决这个问题的——它的本质是一个基于Git的代码托管平台你可以在上面创建私有或公开仓库把本地代码推上去之后所有修改都有历史记录随时能回滚也能多人并行开发。这篇教程我会从注册账号开始带你走完创建仓库→本地关联→首次推送的完整链路全程用最笨但最稳的方式并把你大概率会撞上的报错一个一个拆开讲清楚。适合刚接触代码托管的初学者也适合已经用GitHub但想在国内环境里找更稳托管方案的朋友。1. 搞懂CodeHub它到底是什么能干什么1.1 从一个提交记录说起在开始操作之前我想先用大白话讲清楚CodeHub在我们整个开发流程里扮演的角色。你可以把CodeHub想象成一个带完整历史记录的共享文件夹你在本地写的每一份代码文件经过git commit之后就相当于在时间线上打了一个快照再把快照通过git push传到CodeHub远端就等于把这份快照备份到了云端。以后不管是你自己换电脑还是同事需要接手项目只需要git clone或git pull就能拿到最新代码以及全部历史版本。这个过程相比把文件夹整个压缩发给你有一个本质区别Git记录的是每次提交的差异diff而不是每次复制整个项目。所以哪怕项目文件已经几百兆几十个人每天提交几十次仓库体积的膨胀速度也远低于直接复制。CodeHub作为云端托管端还额外承担了权限管理、代码审查、合并请求Merge Request、问题跟踪这些团队协作能力这是本地Git仓库根本做不到的。1.2 为什么在华为云上选它而不是直接用GitHub或Gitee不少人会有疑问我已经在用GitHub了为什么还要用CodeHub我给你梳理一下我的实际体会。首先是网络稳定性。GitHub虽然功能全面但国内直连经常出现断断续续的情况尤其当你push一个包含较多历史提交的仓库时跑到一半连接被重置是常有的事。CodeHub的服务器部署在华为云国内的Region比如我用的华北-北京四上下行速度非常稳定全程没有那种等半天没反应的焦虑。其次是和华为云生态的集成。如果你后续计划把代码部署到华为云服务器、用云上的编译构建服务做自动化部署或者用CloudIDE做云端开发那代码放在CodeHub里是最顺滑的——在控制台里就能直接把仓库关联到流水线不需要来回复制地址、配置凭证。我见过很多团队代码存在GitHub构建却要单独配置一堆Webhook和密钥维护成本高且容易出安全问题。第三是免费的私有仓库。个人开发者最关心的其实是私有仓库额度。CodeHub对于个人实名认证用户私有仓库的空间和数量对绝大多数个人项目、毕设、小团队项目来说都是够用的这一点和需要付费才有私有仓库的GitHub相比对起步阶段的开发者友好很多。1.3 动手前的准备清单理想情况下你只需要准备这几样东西就能走完整个流程一个华为云账号并且已经完成个人实名认证后面细说本地电脑上安装了Git工具Windows用户推荐直接装Git for WindowsmacOS用户可以用Homebrew安装一份准备上传的本地代码文件夹哪怕里面只有一个README.md也行稳定的网络环境正常家庭或办公网络即可不需要特殊手段提示请记住你的华为云账号密码以及后续可能设置的访问令牌Access Token。我在第五节会专门讲密码和令牌的区别这里先不展开。2. 从零开始实操5分钟完成本地代码上传2.1 注册华为云账号并完成实名认证访问华为云官网点击右上角注册按照流程填写手机号、邮箱、设置密码。这里有一个小技巧注册完成后先别急着进CodeHub先去控制台右上角账号头像下的账号中心里完成实名认证。个人开发者选择个人认证即可需要提供身份证信息和人脸识别一般一两分钟就能完成。为什么我一直强调先实名因为我踩过这个坑你如果在未实名状态下进入CodeHub创建仓库系统可能提示服务未开通或者权限不足。华为云的很多服务尤其涉及代码托管这种可能包含敏感内容的功能默认要求用户先完成实名认证。这个步骤虽然有点烦但它不需要等待人工审核是即时生效的所以现在花两分钟后面就顺畅了。2.2 进入CodeHub服务并创建第一个仓库实名认证通过后在华为云控制台顶部的搜索栏直接输入CodeHub点击搜索结果里的代码托管 CodeHub即可进入服务页面。还有一种方式是通过开发者中心 → 代码托管进入不过直接搜索是最快的。进入CodeHub页面后点击新建仓库进入仓库配置页面。这里我给你几个参考配置配置项我的推荐值说明仓库名称my-first-repo只能用字母、数字、中划线、下划线不能以中划线开头可见范围私有个人学习也建议选私有避免代码泄露初始化仓库勾选初始化仓库会自动生成README、.gitignore文件选择模板Java / Python / Node.js 等有的话按项目语言选自动生成对应.gitignore这里有一个容易忽略的选项是否允许README初始化。我的建议是一开始勾选初始化这样仓库会自动生成一个默认分支可能是main或master后面你git clone或push的时候不会因为远端没有任何提交而遇到一些麻烦。如果你完全不勾选远端是一个空仓库也可以推送但对于新手来说有README的仓库操作起来容错率更低。点击确定后仓库就创建好了。页面跳转到仓库详情页你会看到一个HTTPS地址和一个SSH地址。这两个地址就是后续本地代码和远端仓库之间的门牌号先复制出来备用。2.3 在本地初始化并关联远程仓库本地操作是我认为最容易出错的部分所以我分几种情况讲清楚。第一种情况你本地已经有一个代码项目文件夹还没有任何Git历史。打开终端Windows用户用Git BashmacOS用户用Terminal进入你的项目目录cd /path/to/your/project git initgit init会在当前目录生成一个隐藏的.git文件夹从这一刻起你的项目就处于Git托管之下了。接着把所有文件加入暂存区并提交git add . git commit -m Initial commit然后添加CodeHub远程仓库地址git remote add origin https://codehub.devcloud.cn-north-4.huaweicloud.com/你的用户名/my-first-repo.git这里origin是你给远端仓库起的别名是约定俗成的默认叫法你也可以改成别的但建议不要因为你后面会看到大量文档和命令都以origin为准保持一致能少踩很多坑。第二种情况你本地还没有项目文件夹或者想把远端的空仓库直接拉到本地。git clone https://codehub.devcloud.cn-north-4.huaweicloud.com/你的用户名/my-first-repo.git cd my-first-repogit clone会自动把远端仓库关联为origin并且帮你建好本地分支然后你只需要把代码文件丢进这个文件夹再走一遍add → commit → push即可。2.4 首次推送见证5分钟目标的最后一步如果你是用git clone方式那么本地分支已经存在直接进入目录后把你准备好的代码复制进文件夹然后git add . git commit -m Add my project files git push -u origin main如果你是用git init方式在已有项目上操作那么在git remote add origin之后也需要做同样的事。这里重点讲一下-u参数-u全称是--set-upstream它的作用是让本地当前分支与远端同名分支建立跟踪关系。设置之后你以后再推送只需要执行git pushGit会自动知道推送到origin的main分支不用每次敲全名。第一次推送时加上-u是推荐做法。推送过程中Git会提示你输入华为云的用户名和密码。这里有一个极容易让人抓狂的点这个密码不是你的华为云登录密码而是访问令牌Access Token或代码托管中设置的HTTPS口令。你在弹窗里输入自己华为云账号的登录密码极大概率会报Authentication failed。正确做法是提前在CodeHub页面找到个人设置或者HTTPS密钥管理生成一个访问令牌把这个令牌复制出来当密码用。推送成功的标志是类似这样的提示To https://codehub.devcloud.cn-north-4.huaweicloud.com/你的用户名/my-first-repo.git * [new branch] main - main Branch main set up to track remote branch main from origin.到这里你的本地代码已经成功上传到华为云CodeHub刷新仓库页面就能看到你刚刚提交的文件了。整个流程熟练之后5分钟真的够用第一次操作慢在配置令牌和阅读各种提示上这很正常。3. 常见报错与排查技巧实录3.1 认证失败类错误密码、令牌与权限报错信息长这样remote: HTTP Basic: Access denied fatal: Authentication failed for https://codehub.devcloud.cn-north-4.huaweicloud.com/...这是我见到过最高频的报错几乎每天都有群里的人来问。它出现的原因很简单Git在通过HTTPS协议访问CodeHub时需要你提供一组有效的用户名密码而这里的密码并不是华为云账号的系统登录密码而是访问令牌。解决办法分两步。第一步进入CodeHub页面找到个人账户设置不同版本控制台的入口可能叫个人设置HTTPS密钥管理或访问令牌进去后点击生成新令牌给令牌一个名称比如my-pc-git选择有效期和权限范围一般选read_repository和write_repository就够用。生成后系统会展示一次令牌明文一定要立刻复制保存。第二步回到终端重新推送在用户名提示框输入你的华为云用户名通常是手机号或账号名密码提示框粘贴刚才复制的令牌。如果你的Git配置里已经缓存了错误的凭证Windows用户可以在控制面板 → 用户账户 → 凭据管理器里找到对应条目删掉macOS用户则需要在钥匙串访问里删除相关记录否则下次推送还是会用旧密码反复报错。还有一种特殊情况你没有这个仓库的权限。比如你用的是子账号而仓库是主账号创建的主账号没有授权给你。这种报错往往是Access denied或fatal: unable to access。排查思路是确认你登录的账号对这个仓库有没有Developer或更高权限去CodeHub仓库的成员管理里检查一下。3.2 仓库不存在与网络类错误报错信息有两种常见形式fatal: repository https://.../repo.git/ not found fatal: unable to access https://.../: Recv failure: Connection was reset前者repository not found的原因可能有三种仓库地址拼错了比如用户名写错、仓库名大小写写错。Git仓库地址是区分大小写的MyRepo和myrepo是两回事。仓库是私有的而你当前使用的账号没有访问权限。你在未登录状态下访问一个私有仓库的地址Git也会报not found因为它不会告诉你这是权限问题这是一种安全设计。用对了凭证之后一般就能解决。仓库真的不存在。你还没有创建仓库或者已经被删除。回到CodeHub控制台确认仓库状态如果被删除了重新建房再关联即可。Connection was reset这类网络错误主要是本地网络到华为云机房之间的链路不稳定导致的。可以尝试更换网络环境比如用手机热点或者配置本地的HTTPS代理。这里要注意如果你的电脑开了代理工具也可能导致Git的HTTPS请求被代理干扰反而报错。可以直接执行下面两条命令临时禁止Git走代理git config --global --unset http.proxy git config --global --unset https.proxy3.3 远端有本地没有的提交push被拒报错信息! [rejected] main - main (fetch first) error: failed to push some refs to https://... hint: Updates were rejected because the remote contains work that you do not have locally.这个错误发生的场景很典型你从网页端编辑了README或者同事A推了一个提交而你在本地也提交了代码此时你本地的历史与远端的历史出现了分叉。Git出于安全考虑拒绝你直接覆盖远端要求你先把远端的最新提交拉到本地。解决思路是先拉后推git pull origin main git push origin main但这里又有一个新手很容易撞上的坑如果你本地最初的提交记录和远端的历史完全不相干比如你本地用的是master远端是main且两边没有共同的parent节点git pull会报fatal: refusing to merge unrelated histories这说明Git认为你本地和远端是两个完全独立的项目。解决方法是先拉取并允许合并无关联历史git pull origin main --allow-unrelated-histories执行后Git会尝试把两边的文件合并到本地如果同一文件两边都有内容的话会提示你解决冲突。对于刚开始练习的场景最简单的办法是把本地代码先备份到别的文件夹然后直接从远端clone一份干净的仓库把代码复制进去再推。虽然显得笨但成功率最高。只有当你确实需要保留本地已有的Git历史时才值得去深入研究--allow-unrelated-histories的合并操作。3.4 大文件、忽略规则与clone失败CodeHub对单个文件的体积是有上限的我记得应该是100MB左右。如果项目中不小心提交了一个几百MB的模型文件或压缩包git push时会直接报错remote: error: File: xxx.zip is 214.83 MB; this exceeds 100 MB这种问题处理起来有点麻烦因为错误记录已经写入了本地的Git历史里。解决办法是使用git filter-repo或BFG Repo-Cleaner这类工具重写历史把大文件从历次提交中彻底移除。但我不建议新手直接操作风险较高可能搞坏整个仓库。更好的策略是在源头就拦住它在项目根目录创建或完善.gitignore文件把构建产物、安装包、依赖目录排除掉。一个常见的Java项目.gitignore长这样target/ *.class *.jar *.war *.log .idea/ *.iml .vscode/对于Python项目则建议加上__pycache__/ *.py[cod] .venv/ venv/ dist/ build/ *.egg-info/如果你的项目确实需要管理大文件比如游戏美术资源或深度学习的权重文件请考虑Git LFSLarge File Storage。CodeHub是支持LFS的把大文件交给LFS管理Git仓库本身依然保持轻量clone和push的速度都不会被拖垮。我还遇到过一种很隐蔽的报错origin does not appear to be a git repository。这个不是网络问题而是你本地仓库和远端仓库的关联信息丢了或者你根本没有执行git remote add origin。排查命令非常简单git remote -v如果输出为空说明你的仓库还没配置远端重新执行git remote add origin 仓库地址即可。4. 进阶玩法把CodeHub真正用好4.1 配置SSH密钥一劳永逸免密推送如果你受够了每次推送都要输用户名和令牌SSH方式是你的不二之选。SSH密钥的原理是在本地生成一对密钥公钥和私钥把公钥上传到CodeHub之后Git向CodeHub发起连接时CodeHub通过公钥加密挑战信息本地私钥能正确解密就验证了你的身份。整个过程不需要输入任何密码。第一步在本地生成密钥。在终端执行ssh-keygen -t rsa -b 4096 -C your_emailexample.com一路回车即可对新手来说不额外设置密码短语更省心生成的文件默认在~/.ssh/id_rsa.pub。第二步查看公钥内容并复制到CodeHub。在终端执行cat ~/.ssh/id_rsa.pub输出的一大段以ssh-rsa开头的内容就是你的公钥全部复制。然后进入CodeHub的个人设置 → SSH密钥管理添加一条SSH公钥记录粘贴进去取个好记住的名字。第三步测试连接ssh -T gitcodehub.devcloud.cn-north-4.huaweicloud.com如果提示Welcome to CodeHub或类似信息说明SSH认证成功。以后你在CodeHub上复制仓库地址时记得选SSH格式形如gitcodehub.devcloud.cn-north-4.huaweicloud.com:用户名/仓库.git这样推送就自动免密了。注意SSH端口默认走22如果你所在的网络封了22端口可以测试一下443端口的SSH连接部分云托管平台支持这个备用通道具体看CodeHub的官方帮助文档。4.2 用分支管理你的开发流程很多单干的朋友习惯所有代码都往main分支上推这在项目早期完全没问题但一旦涉及到要给线上加个紧急修复同时又在开发新功能这种场景没有分支会很痛苦。基本的分支模型我建议这样用main分支始终是可发布的状态只允许合入经过验证的代码。每次开发新功能前从main拉出一个新的功能分支命名随意但尽量有语义。git checkout main git pull origin main git checkout -b feature/awesome-dashboard你在功能分支上正常提交、推送完成开发后在CodeHub网页端给main分支发起一个合并请求Merge Request。其他成员可以在请求下评论、审查代码确认无误后再合并。这样做的好处是明显的main分支永远干净任何时候都能基于它发版如果某个功能开发到一半被废弃直接删除分支即可对主分支零影响。我发现有不少人一开始嫌这套流程多此一举但真正经历一次线上出现bug却因为本地一堆未测试代码而不敢修复的窘境后都会主动回归分支规范。在CodeHub上操作分支和合并请求的入口很直观多试两次就熟了。4.3 利用CodeHub的代码审查与问题跟踪团队协作时CodeHub提供的合并请求Merge Request和问题跟踪Issue功能非常实用。前者结合分支模型使用后者可以记录你发现的bug、待办的需求、改进想法每一条issue都能关联提交记录、指派负责人、设置优先级项目脉络一目了然。还有一个小细节在提交信息中可以直接关联issue编号比如提交信息写fix #123等这次提交合并到主分支后系统会自动把issue标记为关闭具体语法可能略有差异以CodeHub页面提示为准。这种提交即关联的操作让项目进展非常透明我推荐每个人从写代码的第一天就养成规范提交信息的习惯。一个标准的提交信息可以长这样feat: add login page - support phone number login - add verification code module - fix #15类型前缀feat、fix、docs、refactor等是Conventional Commits规范里的约定CodeHub不会强制但团队约定俗成后翻历史记录的效率会高很多。4.4 与华为云DevCloud和CI/CD流水线打通CodeHub最大的优势之一就是它与华为云DevCloud系列服务的无缝联动。你不需要把代码下载到本地再手动部署到服务器直接在CodeHub仓库页面创建流水线把获取源码 → 编译构建 → 部署上线这几个阶段串起来。举个最简单的例子你有一个Node.js项目希望每次往main分支推送代码后自动在云端执行npm install和npm run build然后把构建产物部署到一台云服务器上。在华为云DevCloud的流水线服务里选择CodeHub源码源指定仓库和main分支添加一个构建任务选择Node.js构建镜像再添加一个部署任务填写服务器IP和部署脚本一个基础的CI/CD就搭好了。从此之后你只管推送代码剩下的事情流水线自己会做。这前后端的体验跨度很大——从一个上传代码的工具变成驱动自动化流程的源头。我是强烈建议所有CodeHub用户都去试着配一次流水线的哪怕只是构建一下然后打印一行hello它带给你的视角变化是纯代码托管没法给的。不过这一步内容量很大我今天先不展开后续可以单独写一篇流水线的实操教程。5. 写给大家的避坑心得总结一下我这几年来用CodeHub、也用过其他代码托管平台之后沉淀下来的几点体会。第一遇到报错先冷静把整行报错信息复制到搜索引擎里而不是只看最后几个单词。很多人一看到fatal就慌了其实fatal在Git里只是一个普通的错误级别标识后面的完整提示才真正告诉你问题在哪。比如fatal: Authentication failed for https://...最核心的信息是认证失败和网络无关、和代码无关、和仓库是否存在也无关。第二访问令牌Access Token用完一定要妥善保存它是你HTTPS方式下最高的凭证。如果令牌泄露别人就能随意读写你的仓库。我的做法是给每台设备单独生成一个令牌设备不用了顺手删除对应的令牌避免一把钥匙走天下的风险。令牌权限也要遵循最小化原则只给read_repository和write_repository不给删除或管理权限。第三提交信息的质量决定你项目历史的可读性。《编写优质提交信息的核心技巧》这类文章很多但核心就是一句话为代码写说明而不是为Git写日志——把添加了xxx功能拆开讲清楚为什么做这件事比写一百个字面描述有用得多。我见过同事写update file这种提交信息过了两周连他自己都不记得改了什么。第四git pull之前建议先git stash保存你未提交的改动否则当本地有冲突时Git会拒绝拉取。新手经常在这里卡住以为自己的代码全丢了。其实stash就像代码的临时储物柜改完冲突后随时可以再把改动取回来git stash # 暂存未提交的改动 git pull # 拉取远端 git stash pop # 恢复改动第五不要因为嫌麻烦就不写.gitignore。它可能是你从能用到好用的分水岭。很多初学者第一次上传项目把node_modules几万个依赖文件也推上去了导致每次操作慢到怀疑人生仓库体积也瞬间爆炸。从项目第一天就写一份贴合语言的.gitignore后面受益无穷。我在实际使用中最深的感受是CodeHub这类平台真正的价值不在于有个地方存代码而在于它强制你建立起版本思维和协作习惯。当你习惯了每次提交都带着明确意图、每次合并都走审查流程、每个问题都有迹可循之后你写的代码质量和开发的顺畅度都会往上走一个台阶。如果你现在还在本地写代码、文件名加v2、v3、最终版的状态我想说的是是时候改变一下了。Git的入门门槛没有你想象中那么高今天这篇教程里的命令能解决你90%的日常需求剩下的10%等你真正遇到了再去搜索、去解决那时候你已经有足够的能力判断什么是靠谱的答案了。