说实话我见过太多人卡在“会用Git”和“会上Gitee”中间那道坎上——本地仓库建得明明白白代码写了一堆一说到“推送到远程仓库”就开始手忙脚乱。尤其是点开Gitee官网之后面对那一堆按钮和选项第一反应往往是“这跟GitHub怎么长得不太一样”。作为一个把Gitee当主力代码托管平台用了好几年的开发者我可以负责任地告诉你Gitee的实战使用真没你想的那么复杂你需要的只是一条清晰的操作路径和几个关键概念的正确理解。这篇内容不会给你堆砌命令大全而是从零开始讲清楚每步操作背后的原因让你看完之后不光知道“怎么点”更知道“为什么这么点”这样以后换任何代码托管平台你都能举一反三。这篇文章适合几类人看刚入行没多久、项目一直只存在本地硬盘里的新手被公司或团队要求把代码迁到Gitee但不太熟悉整套流程的同学还有那些想在Gitee上部署一个静态网站却始终没搞明白Pages功能的开发者。我会把注册配置、建仓库、代码上传、Pages静态托管这些高频场景全部拆开揉碎最后再给你一份常见问题排查清单基本都是我实际踩过的坑。1. 先把Gitee到底做什么说清楚1.1 为什么我建议把Gitee当成第一个代码托管平台如果你第一次接触代码托管我真心建议从Gitee开始而不是直接冲去注册GitHub。原因很简单一个是访问速度Gitee服务器在国内clone和push代码基本是秒级响应另一个是中文界面所有按钮、提示、文档都是中文对新手极其友好。很多教程一上来就让你敲git命令操作GitHub结果因为网络问题卡在第一步体验非常劝退。GitHub当然很好全球最大的开源社区但这不意味着它是唯一选择。Gitee的定位是“国内 GitHub”它在国内环境下做了大量针对性优化。比如私有仓库免费、容量限制宽松、支持一键导入GitHub仓库这些功能对个人开发者和小团队来说非常实用。我自己的经验是先在国内平台把Git操作练熟搞清楚工作流之后再接触GitHub会轻松得多因为底层逻辑是完全一致的。还有一点容易被忽略——Gitee的社区氛围其实更贴近国内开发者的实际需求。你在上面能找到大量中文注释的项目源码、针对国内业务场景的工具库、还有不少技术博主把教程和代码放在一起维护。这种“代码文章”的组合对学习型开发者来说价值很高。1.2 本地仓库和远程仓库一张图记住它们的关系很多教程在讲Gitee的时候默认你已经理解了Git的核心概念但实际很多人的困惑恰恰出在这里。我用大白话帮你理一遍本地仓库就是你电脑上那个隐藏的.git文件夹它记录了你所有代码的版本历史相当于你项目的“时光机”远程仓库就是Gitee服务器上为你这个项目单独开辟的一块存储空间相当于你把“时光机”备份了一份放到云端。两者之间的关系可以这样理解你平时在本地写代码、提交commit这些操作只影响本地当你准备把某个阶段的成果拿给别人看或者怕本地硬盘坏了代码丢失你就执行“推送”push把本地提交同步到Gitee别人改了代码或者你在另一台电脑上继续开发就执行“拉取”pull把远程最新的内容同步回本地。这个“本地-远程”双轨制的设计就是Git一切操作的核心逻辑。搞清楚这个后面所有命令你都能猜到大概意思git init是创建本地仓库git remote add是给本地仓库绑定一个远程地址git push是上传git pull是下载。2. 注册、配置把钥匙配好2.1 注册账号时的几个小细节注册Gitee账号本身没什么好说的手机号或者邮箱都可以。但有几个小细节值得你注意用户名个人空间地址一旦确定后面会显示在你所有仓库的URL里尽量选一个和你的技术ID一致、好记的英文名实名认证建议直接做掉虽然不实名也能用基础功能但后续开启Pages、增加仓库容量这类操作都会受到限制早晚要认证不如一开始就办好。登录之后先别急着建仓库先做一件事设置SSH公钥。这是新手最容易忽略、也是后面所有上传操作能否顺利的关键。Gitee支持HTTPS和SSH两种协议访问仓库HTTPS每次push都要输入账号密码虽然可以靠记住密码功能省事但换台电脑又得重新配置SSH则是一劳永逸配置一次密钥后续所有仓库的推送拉取都不需要再输入任何凭证。2.2 SSH密钥生成与配置实操先说原理SSH密钥就是一对加密文件一个私钥默认叫id_rsa留在你电脑上绝对不能泄露一个公钥id_rsa.pub可以随意分发把它填到Gitee后台相当于告诉Gitee“持有这把私钥的人是我的电脑”。以后你电脑访问Gitee时服务器会用公钥验证你的身份验证通过就放行。生成密钥的步骤非常简单。打开终端Windows用户建议直接用Git Bash别用自带的cmd输入以下命令ssh-keygen -t rsa -C 你的邮箱example.com -b 4096注意把邮箱换成你注册Gitee用的邮箱。执行之后一路回车即可它会默认把密钥保存到用户目录下的.ssh文件夹并且不设置密码短语passphrase。如果之前已经生成过密钥它会提示你是否覆盖根据你自己情况选择覆盖之后旧密钥就失效了。然后查看公钥内容cat ~/.ssh/id_rsa.pub如果你用的是Windows Git Bash路径一般是/c/Users/你的用户名/.ssh/id_rsa.pub。用鼠标选中整段输出并复制注意别漏掉结尾的邮箱号。接下来登录Gitee点击右上角头像进入设置找到“安全设置”里的“SSH公钥”选项卡把复制的内容粘贴到“公钥”输入框里标题可以随便填比如“我的MacBookPro”或“公司台式机”方便以后区分多台设备。保存之后在终端里输入ssh -T gitgitee.com第一次连接会提示是否确认指纹输入yes回车。如果看到欢迎信息类似“Hi 用户名! Youve successfully authenticated, but GITEE.COM does not provide shell access.”说明密钥配置成功整套流程走通了。2.3 实操心得HTTPS和SSH怎么选我见过很多教程直接让新手用SSH理由是不用输密码但对完全没接触过终端的人来说ssh-keygen这个命令本身就有门槛。所以我的建议是分情况如果只在固定的一台电脑上开发而且嫌配置麻烦直接选HTTPS也完全没问题第一次push输一次账号密码后面用Git的credential存储机制也能自动记住如果需要在多台电脑上协作、或者担心密码明文存储的风险那就老老实实配SSH一次性投入换来长期省心。说实话实际工作中把两种方式混用的人特别多——公司电脑配了SSH个人电脑用HTTPS——Git本身完全支持远程地址里写哪种协议就用哪种方式验证互不影响。确定一种方式之后远程地址的格式要注意HTTPS地址是https://gitee.com/用户名/仓库名.gitSSH地址是gitgitee.com:用户名/仓库名.git很多人push报错就是因为两种协议地址用混了。3. 建仓库注意几个容易选错的选项3.1 创建仓库时的字段逐个说登录Gitee之后点击右上角的“”号下拉菜单里选“新建仓库”就会进入仓库信息填写页面。看到那一堆字段别慌真正影响使用体验的其实就几个。仓库名称必须填尽量用小写字母、数字和中横线比如my-blog、mall-server不要用中文名、不要有大写字母。路径Path会自动根据名称生成一般不用改。仓库介绍和标签可以填也可以不填不影响功能但建议随手写上毕竟开源项目有个好描述能增加曝光。归属选择“个人空间地址”即可除非你加入了某个企业或组织。初始化仓库这一栏有三个选项红框里的“初始化仓库”自动生成README文件、.gitignore模板自动生成忽略规则文件、选择开源许可证。我的建议是新手先勾选“初始化仓库”和.gitignore模板这样仓库建好之后不是完全空白可以直接clone下来开始干活也可以避免很多刚上手时容易踩的坑。比如.gitignore可以自动帮你排除掉target、node_modules这类不应该提交的文件不然下次本来想提交全部代码结果把几千个依赖包全传上去了手忙脚乱得不偿失。3.2 开源许可证到底选哪个“开源许可证选什么”一直是新手纠结的重点。我在Gitee上见过很多仓库完全没有许可证文件这样做其实是有问题的别人看到你的开源项目想用又不敢用因为不确定你的授权范围。如果你只是想公开代码不关心别人怎么用最省事的是选“MIT License”它几乎是所有开源许可证里限制最少、最通俗易懂的别人想商用、想修改、想闭源都行只要保留你的版权声明即可。如果你的目标是希望代码永远保持开源别人改了也必须开源那就选GPL-3.0它对版权保护更严格——如果有人基于你的代码做了修改再分发那他的项目必须也开源且必须以同样的许可证方式发布。这一点很关键很多小白选了这个却不知道自己签了“互相传染”的协议直到某天商业合作时才尴尬。如果只是想把代码挂出来给团队内部或几个朋友用不想选择任何许可证那就用“自定义许可证”或者暂时不选把仓库设为私有Private就行完全不会有版权争议。许可证选择我个人推荐一个原则MIT是个人项目默认项Apache-2.0适合想同时保留专利授权的开源项目GPL-3.0适合希望强制保持开源的场景。3.3 私有和公开先别急着决定仓库可见性有“私有”和“公开”两个选项。公开仓库任何人都能看到和clone私有仓库只有你自己和被你授权的协作者能访问。许多新手一开始就把项目设为公开以为能获得关注但代码质量、注释、敏感信息比如数据库密码、API Key都没清理结果惹来一堆麻烦。我的习惯是刚开始写的个人项目一律私有等代码稳定、README写完整了、确定不包含敏感信息之后再切换为公开。Gitee支持在仓库的“管理”页面随时切换可见性这点非常灵活不需要一开始就做决定。另外注意Gitee的私有仓库对个人用户有协作人数限制但自己用完全足够。4. 代码上传命令行和IDE两种方式都给你4.1 命令行最通用的方案不管你用什么开发工具命令行那套流程永远应该先掌握因为它不依赖任何IDE在服务器上、在远程开发环境里都能用。假设你本地已经有一个项目文件夹里面有一堆代码现在要把它们提交到Gitee仓库里。进入项目目录初始化本地仓库cd 你的项目目录 git init这个命令会在当前目录下生成一个.git隐藏文件夹表示本地仓库已就绪。把项目所有文件加到暂存区git add .你可能会疑惑这个“暂存区”是什么。可以这样理解Git把所有待提交的文件分成了三步——工作区你实际改动的文件、暂存区你决定本次要提交的文件清单、版本库已经生成快照的记录。git add就是把文件从工作区挪进暂存区git commit则是把暂存区内容正式存档。提交到本地仓库并附上说明git commit -m 第一次提交初始化项目双引号里的内容建议写清楚本次提交做了什么方便以后回溯。把本地仓库和Gitee远程仓库关联起来。打开你的Gitee仓库页面找到“克隆/下载”按钮复制SSH地址。然后执行git remote add origin gitgitee.com:你的用户名/仓库名.git这里的origin是一个默认的远程仓库别名相当于给那一长串地址起个好记的名字。以后凡是看到origin就知道指的是Gitee上的这个仓库。推送本地代码到远程git push -u origin master如果分支不是master而是main新版Gitee仓库默认分支名可能是main把命令里的master换成main。-u参数表示第一次推送时建立本地分支和远程分支的关联关系以后直接输入git push就能推送不用再带完整参数。执行之后在Gitee仓库页面刷新一下你的代码就出现在上面了。整个流程我用一段话给你串一遍git init创建本地仓库、git remote add绑定远程地址、git add和git commit在本地存档、git push推到Gitee。四步走记住这个节奏后面就顺了。4.2 IDEA提交代码到Gitee平时用IntelliJ IDEA开发的同学完全可以在图形界面里完成上传不一定非要切到终端敲命令。但注意IDEA本身不带Git客户端你需要先安装Git软件然后在IDEA的设置里配置好路径。用IDEA打开项目之后菜单欄选VCS - Enable Version Control Integration选择Git这相当于执行了git init。关联远程仓库VCS - Git - Remotes点加号把Gitee仓库的地址粘贴进来。这里建议直接选HTTPS地址因为IDE里对SSH密钥的读取有时会跟系统配置有冲突HTTPS反而省事。之后每次修改代码选中文件或整个项目右键Git - Commit Directory填好Commit Message点击Commit。如果要推送再右键选Git - Repository - Push。第一次推送时IDEA会要求你输入Gitee账号密码验证通过后会保存凭证。4.3 PyCharm和VSCode的差异点PyCharm和IDEA同属JetBrains家族操作逻辑一模一样上面那套步骤完全适用。唯一的差异是如果用的是社区版PyCharm功能没有专业版全某些Git功能可能被禁用这时就老老实实用命令行。VSCode用起来更轻量。左侧菜单栏的源代码管理图标就可以完成提交、拉取、推送。但大部分VSCode用户还是会装一个GitLens插件它能显示每行代码的提交者、提交时间、最近修改记录查历史非常方便。另外可能有人不知道VSCode有一个专门的Gitee插件叫“Gitee”你可以在扩展市场搜一下装好之后能在侧边栏直接浏览Gitee仓库、创建仓库、甚至在线修改文件再提交节省了频繁切网页的时间。不过这类插件更新速度一般用之前先看看最近更新时间避免版本兼容问题。5. 静态托管Gitee Pages 让项目直接变成网站5.1 Pages 能做什么Gitee Pages是Gitee提供的一个静态网站托管服务简单说就是你把HTML、CSS、JS这些前端文件放到一个仓库里Gitee能帮你把它们发布成一个可以通过公网链接访问的网站。很多人拿它当个人博客的免费托管也有不少人部署纯前端的小工具比如我就在上面跑过一个PDF转换的纯前端小工具整个仓库只有几个前端文件但不影响它成为一个完整可用的服务。为什么叫“纯前端”因为静态托管只能跑浏览器端代码没有服务器端语言Node.js、PHP、Java这类的执行环境数据库更不用提。但好处也因此很明显没有服务器成本、没有运维负担、页面加载速度快而且完全不需要考虑后端安全问题。5.2 开通流程实操在Gitee上部署Pages的完整流程是先建一个仓库把前端项目文件推上去然后进入仓库的服务页面找到Gitee Pages。第一次使用会让你上传一个身份证信息做人脸实名认证认证过了才能开启。认证通过之后选择要部署的分支和目录一般选master分支和根目录点击启动等一两分钟它会自动生成一个形如你的用户名.gitee.io/仓库名的访问地址。之后每次更新代码需要手动点击更新按钮重新部署不像GitHub Actions可以全自动化。一个需要特别注意的点Gitee Pages对仓库容量和单文件大小有限制项目体积超过100MB基本就别想部署了。如果项目里有大图片、视频建议单独传到对象存储页面里引用外部链接就好。5.3 一个前端PDF工具上线的真实案例我曾经在Gitee Pages上部署过一个“PDF转Word”的前端工具源码是当时在GitHub上搜到的一个开源项目纯HTMLJavaScript实现文件只有几个。部署过程本身没什么好说真正有价值的是我踩过的坑。第一个坑是跨域问题。纯前端PDF转换本质是在浏览器本地解析PDF文件但某些浏览器对本地文件读取有安全限制直接通过file://协议打开会失败。部署到Pages之后因为通过HTTPS访问反而规避了这个问题。所以我建议如果你做这类纯前端小工具别只在本地测试老老实实丢到Pages上跑一遍很多诡异问题都是环境差异导致的。第二个坑是更新缓存。Pages部署完成后你刷新网站可能还是旧版本这是因为浏览器和Gitee CDN都做了缓存清理缓存或者强制刷新CtrlShiftR能解决大部分情况。如果还不行可以给引用的JS/CSS文件加上版本号参数比如app.js?v20240101强制浏览器拉取新文件。第三个坑就是部署时间。第一次部署大概3-5分钟更新部署大约1-2分钟。每次“更新”按钮点下去之后看到“部署成功”的绿色提示再关页面不然可能生成的是半旧的页面快照。6. 常见问题与排查技巧实录6.1 push时报错、报授权失败怎么办我见过最高频的问题是git push时报Permission denied (publickey)这几乎都是SSH密钥没配对导致的。排查顺序如下ssh -T gitgitee.com看是否显示欢迎信息如果提示Permission denied说明电脑上的密钥和Gitee上配置的公钥不匹配。这时候一件一件事确认公钥有没有完整复制到Gitee后台复制的是不是id_rsa.pub而非id_rsa生成密钥时邮箱有没有填错Gitee更换邮箱后旧邮箱的公钥是否被禁用。另一个高频问题是remote: HTTP Basic: Access denied这是HTTPS方式访问时账号或密码错误。处理办法比较简单重新输入一次正确密码或者在Windows的凭据管理器里删掉旧的金迪凭据再重新推送。macOS用户在“钥匙串访问”里搜索gitee删除对应的网络密码即可这个坑不少macOS用户都遇到过。6.2 上传代码后Gitee页面没显示怎么办有时本地命令执行顺畅Gitee页面刷新后却看不到代码。先确认自己是不是推错了仓库——这个错误多到你无法想象因为git remote -v能看到当前仓库绑定的远程地址如果显示的是另一个项目说明你复用错了.git配置。还有一种很隐蔽的情况你在项目里执行过git init但项目本身是一个子目录外面套着一层目录你刚好在错误的层级执行了命令导致提交的文件路径全不对。这种情况我的建议是清理掉所有.git文件夹重新来一遍find . -name .git -type d -exec rm -rf {} \;然后重新git init、重新绑定远程地址。6.3 误删仓库怎么抢救Gitee个人版没有直接回收站功能仓库一旦被删除代码和提交历史会全部消失。所以我持续强调那句本地永远留一份完整的副本涉及重要代码务必养成定期推送的习惯。有次我手滑在网页上删了一个demo仓库还好本地有完整代码但那个仓库里的Issues和Pages配置全没了只好重建痛了半小时。如果你误删了仓库并且本地没有备份不要完全绝望——Gitee客服可以尝试帮你恢复但过程比较慢而且不是100%保证成功。所以最好的“抢救”是从一开始就不让这种事情发生。我现在的习惯是重要仓库开“备份”和管理员二次确认每次删除前至少读两遍仓库名称。6.4 常见问题速查表现象可能原因解决办法push时报Permission deniedSSH公钥未配置或密钥不匹配重新执行ssh -T gitgitee.com排查push时报Access deniedHTTPS账号密码错误删掉系统密钥后重新登录push时报文件太大单文件超过100MB安装Git LFS或将大文件移出仓库中文文件名显示乱码编码问题全局配置git config --global core.quotepath false分支名称不同本地master远程main推送时指定分支名或git branch -M main改名Pages没有生效未实名认证或部署时间未到完成认证等待3-5分钟并刷新缓存Gitee页面看不到最新提交推错仓库git remote -v检查远程地址提交里包含不想要的临时文件.gitignore配置缺失补全忽略规则并git rm --cached最后再分享一个小经验Gitee的整体使用难度真的不高真正让你感到迷茫的是操作背后的概念。你把“本地分支”“远程仓库”“暂存区”“SSH身份验证”这些词弄明白了随便换一个平台GitHub、GitLab、Coding都能很快上手。我建议你找个不重要的项目按照上面流程老老实实走一遍建仓库、配置密钥、推代码、开Pages整个过程半小时搞定。走完一遍之后你会发现所谓Gitee实战其实就那几板斧往后就是肌肉记忆了。