Gitee(码云)新建仓库并将本地项目推送至该仓库前几天帮团队里新来的同学配置开发环境发现他最卡的一步不是写代码而是怎么把本地写好的项目推到码云上。密钥配了、仓库也建了结果一执行git push就报错来来回回折腾了半个多小时。说实话这个流程我已经走了无数次但对新手来说坑是真的多。今天就把“Gitee新建仓库 本地项目推送”这条完整链路拆开揉碎讲一遍从 SSH 密钥配置、仓库参数选择到三种不同场景下的推送操作再附上我这些年踩过的坑尽量让你一次性跑通。这个教程适合刚接触 Git 和码云的新手也适合那些平时只点图形界面、一旦出问题就两眼一抹黑的同学。你不需要有任何 Git 基础跟着操作就行但我也会把每一步背后的原理讲清楚这样你后面遇到变体场景时不至于只能照着抄命令。1. 准备工作为什么优先把 SSH 密钥配好1.1 SSH 和 HTTPS 到底选哪个往码云推送代码最常见的有两种通道HTTPS 和 SSH。很多新手会直接选 HTTPS因为看起来简单——仓库地址复制下来git clone一下就行。但实际上HTTPS 方式每次 push 都要输入用户名和密码虽然你可以让 Git 记住凭据但换电脑、换终端、或者凭据过期之后都会变成定时炸弹。SSH 的本质是配一把“钥匙”你把公钥放到码云后台本地私钥负责签名。配置好之后push 和 pull 全程免密也不用担心密码泄露安全性还更高。我自己一直推荐 SSH理由很简单对比项HTTPSSSH首次配置难度低直接克隆稍高需要生成密钥日常推送体验需要凭证可能频繁输密码配置后完全免密安全性依赖账号密码基于密钥对安全性更高换电脑成本重新输密码或配置凭据重新配置公钥即可适合场景临时下载公开仓库日常开发、长期维护当然如果你只是偶尔下载一个公开项目那 HTTPS 完全够用。但只要你打算长期把代码托管在码云上SSH 绝对是省心之选。1.2 生成并配置 SSH 密钥配码云密钥如果你已经生成过 SSH 密钥可以跳过生成这一步直接看后面的配置。不确定自己有没有的话先执行下面的命令看一眼ls -la ~/.ssh如果有id_rsa和id_rsa.pub这两个文件说明你已经有密钥对了。如果没有或者你干脆想换个新的执行ssh-keygen -t rsa -C 你的邮箱example.com这里的邮箱建议填你注册码云时用的邮箱它只是一个备注信息用来标记这把密钥属于谁。执行后终端会问你三个问题第一个是密钥保存路径直接回车用默认路径~/.ssh/id_rsa第二个是设置私钥密码passphrase建议直接留空否则每次 push 都要输一次密码SSH 免密的优势就没了第三个是确认密码同样直接回车。生成完之后查看公钥内容cat ~/.ssh/id_rsa.pub你会看到一串以ssh-rsa开头的长字符串这就是公钥。把整段内容复制下来。然后登录码云点击右上角头像进入“设置”——“安全设置”——“SSH 公钥”。把复制的内容粘贴到“公钥”输入框里标题随便填一个自己能认出来的名字就行比如“我的MacBook”或者“公司电脑”。点击确定密钥就配置好了。验证是否配置成功执行ssh -T gitgitee.com如果终端提示Hi 你的用户名! Youve successfully authenticated, but GITEE.COM does not provide shell access.说明密钥已经生效。这里有个细节首次连接时终端会问你Are you sure you want to continue connecting (yes/no)?记得输入yes回车别傻乎乎地输yGit 只认yes。1.3 配置本地 Git 身份信息密钥配好了还要让 Git 知道你是谁这一步很多新手会漏掉。如果不设置推送的时候 Git 会用一串随机字符串作为提交作者码云上显示出来就是一个陌生的名字后续追溯历史记录会非常痛苦。git config --global user.name 你的名字 git config --global user.email 你的邮箱example.com注意这里的user.email最好和码云账号邮箱保持一致这样你的提交记录才能正确关联到码云账号上。用--global是全局生效如果你不同项目想用不同身份可以去掉--global在具体仓库目录里单独配置。2. 码云新建仓库一步步把参数选对2.1 新建仓库的完整流程密钥配好之后接下来就到码云上创建仓库了。登录码云点击页面右上角的“”号选择“新建仓库”或者直接访问https://gitee.com/projects/new进入创建页面。这里有几个字段需要重点说仓库名称只能包含字母、数字、下划线、中划线和点不能有中文和空格。这个名字会直接体现在仓库地址里建议用能表达项目含义的英文单词组合比如blog-system、wechat-miniprogram别用test123这种没有辨识度的名字。路径没填的话会自动跟随仓库名称这个字段是仓库访问路径的一部分也不是不能改但改起来会影响已有克隆地址所以创建前想好。是否私有如果只是个人项目、学习代码或者还没定型的半成品建议选“私有”。等代码稳定了需要开源分享时再去仓库设置里改成“公开”也不迟。一旦公开代码就永久留痕了删掉也不代表别人没下载过。初始化仓库建议不要勾选“初始化仓库”包括不要自动生成 README、.gitignore 和开源许可证。原因是如果你本地已经有项目了远程仓库再初始化一个 README等你推送本地代码时就会因为两边历史不相关而冲突。后面我会专门讲这个坑。创建完成后你会看到一个仓库主页上面有仓库地址。在“克隆/下载”按钮那里可以选择 HTTPS 或者 SSH 地址。既然前面配好了 SSH这里就选 SSH 地址形如gitgitee.com:你的用户名/仓库名.git。2.2 开源许可证到底选什么很多新手在创建仓库时看到“开源许可证”这个选项就懵了。如果你确定自己不选择任何许可证那就选“无”后面的下拉框里也没有你想要的东西说明你不需要选。但如果你打算把项目开源许可证的选择会影响别人能不能用你的代码以及怎么用。这里给你最简化的选型建议MIT License最宽松别人拿到你的代码可以随便改、随便用甚至闭源商用只需要保留你的版权声明。适合绝大多数个人开源项目也最不容易劝退使用者。Apache License 2.0比 MIT 多了一条专利授权保护公司项目用得比较多。GPL License所谓“传染性”协议别人用了你的代码他的代码也必须开源且使用 GPL。适合你想强制自己代码的衍生品也开源的场景。但对于想被广泛集成的库来说GPL 会让很多商业团队直接绕开你。BSD License和 MIT 类似但更强调保留原始版权声明。个人经验做个人项目、工具类项目无脑选 MIT 就行。别选“无许可证”——在绝大多数法律框架下没有许可证意味着别人默认不能用你的代码这会极大地限制项目的传播。2.3 仓库参数没选对后面怎么补救有人会问“我已经选错了怎么办”比如创建仓库时勾选了初始化 README本地又已经有一个项目这其实是新手最容易遇到的冲突场景。不用慌后面第 3 节场景三里我会给出具体的解决命令。再比如你仓库建成了私有后来想让别人看到点击仓库页面的“管理”——“基本信息”找到“是否开源”切换成公开即可。仓库名称和路径在“管理”里也可以改但改完记得通知一下已经克隆过这个仓库的同事或伙伴他们本地的 remote 地址需要同步更新。3. 本地项目推送三种场景一次跑通3.1 场景一全新本地项目从零开始推送这是最典型的场景代码已经在本地写好了但本地目录还不是一个 Git 仓库。打开终端进入项目根目录先初始化仓库git init这会在当前目录下生成一个隐藏的.git文件夹里面记录了仓库的所有版本信息。执行完后把项目里所有文件加入暂存区git add .这里的.代表当前目录下所有文件。如果你只想提交某几个文件可以写成git add src/index.js这样的具体路径。接着提交一个初始版本git commit -m init: 初始化项目-m后面的内容是提交说明规范的提交说明对后续维护很重要。接下来需要把本地仓库和远程码云仓库关联起来git remote add origin gitgitee.com:你的用户名/仓库名.gitorigin是远程仓库的默认名字是 Git 的一个约定俗称你可以理解成给远程地址起了个简短别名。最后把本地代码推送到远程git push -u origin master如果你的默认分支不是master而是main那就把命令里的master换成main。-u参数的意思是将本地当前分支和远程 master 分支建立“上游关系”这样以后直接执行git push就能推送不用再带origin master了。推送成功后在码云仓库页面刷新就能看到你的代码了。3.2 场景二本地已经是 Git 仓库只想关联远程有些同学之前已经用 Git 管理项目了本地仓库里有一堆提交记录现在就差把远程仓库关联上。这种情况不用重新git init直接执行git remote add origin gitgitee.com:你的用户名/仓库名.git然后推送即可git push -u origin master如果你发现本地已经配过远程仓库执行git remote add会报错说origin已存在。这时候可以用git remote -v查看当前已有的远程仓库地址git remote -v如果只是地址配错了可以直接修改git remote set-url origin gitgitee.com:你的用户名/仓库名.git如果想把原来的远程删掉重新关联则执行git remote remove origin git remote add origin gitgitee.com:你的用户名/仓库名.git这里多说一句经常有人在网上复制别人的项目代码然后本地改了想去推到自己的仓库结果发现 push 的时候一直往原作者仓库推——因为.git文件夹是复制过来的里面记录的还是原仓库地址。这种问题用上面的git remote -v查一眼就能定位然后改掉就行。3.3 场景三远程仓库已有内容推送被拒绝这个场景我几乎每周都会遇到。你创建仓库时勾选了初始化 README或者远程已经有了别的提交这时候git push会报错! [rejected] master - master (fetch first) error: failed to push some refs to gitgitee.com:... hint: Updates were rejected because the remote contains work that you do not have locally.意思是远程有本地没有的提交Git 出于安全考虑不允许直接覆盖。解决办法分两种如果你的远程仓库只是一些初始化文件本地也没有需要特别保留的东西可以直接强制推送用本地历史覆盖远程git push -u origin master -f-f是--force的缩写表示强制推送。这个命令在多人协作的项目里极度危险因为它会把远程历史强行覆盖如果别人已经基于远程历史做开发会被你搞崩。但如果你自己一个人用、远程刚建、没别的东西那这也是最省事的办法。如果远程仓库确实有你要保留的内容尤其是多人协作场景正确的做法是把远程代码先拉下来再推送git pull origin master --allow-unrelated-histories为什么要加--allow-unrelated-histories因为本地仓库和远程仓库的历史没有任何共同祖先Git 默认会拒绝合并不相关的历史。加了参数后Git 会把两边内容合并到一起如果都是 README 之类的文件大概率会自动合并成功。合并提交一下git commit -m merge: 合并远程仓库内容然后正常推送git push -u origin master顺便说一下git pull的本质是git fetchgit merge但 merge 会生成一个“合并提交”历史记录会有一条分叉线。如果你想让历史更干净可以用git pull --rebase它会把你本地的提交重新“续”在远程提交后面历史是一条直线。不过 rebase 会改写提交哈希副作用是如果别人已经从你的分支拉过代码就不要随便 rebase 推送会引发一串冲突。4. 高频问题与排查技巧4.1 认证相关的三个高频报错推送代码时遇到报错十有八九是认证问题。我整理了三个最高频的你先对照排查报错一Permission denied (publickey)这个报错说白了就是 SSH 密钥没通过验证。排查步骤ssh -T gitgitee.com看是否提示认证成功。如果提示权限拒绝先确认公钥是否已经添加到码云后台最好重新复制一遍公钥检查有没有粘贴完整、多复制了空格。确认你用的密钥不是默认文件名。比如你生成密钥时手动改成了gitee_rsaGit 默认不会去找这个名字你需要在~/.ssh/config里配置或者手动指定。国内很多教程都会让人自定义密钥名这反而埋了坑。对新手来说默认的id_rsa是最省事的。报错二Remote host identification has changed如果你换过系统、重置过 SSH 密钥或者码云服务器的密钥发生了变化可能会遇到这个提示这是 SSH 为了防中间人攻击做的保护机制。解决办法是删除本地 known_hosts 里对应的旧记录ssh-keygen -R gitee.com然后重新执行ssh -T gitgitee.com输入yes记录新指纹。报错三remote: 对密码或 Token 认证的支持已关闭如果你用了码云上的 HTTPS 地址并且密码输入错误多次可能会触发这个提示。码云为了账号安全默认对密码认证限制较严格HTTPS 方式已改为推荐使用私人令牌Token。遇到这种情况要么换 SSH 地址要么去码云“设置”——“私人令牌”生成一个 TokenHTTPS 推送时密码栏粘贴 Token。报错信息原因解决方式Permission denied (publickey)SSH 密钥未配置或未生效重新检查公钥配置确认密钥文件名Remote host identification has changed远程主机指纹变化ssh-keygen -R gitee.com清除旧指纹对密码或Token认证的支持已关闭HTTS 密码认证受限换 SSH 地址或使用私人令牌4.2 用 IDE 推送代码有哪些隐藏坑命令行用得再溜日常开发大家还是习惯用 IDE。现在常用的几款开发工具都内置了 Git 集成但集成方式各有不同。IDEA / PyCharm 系列菜单栏VCS-Share Project on Gitee可以直接把项目分享到码云前提是你已经安装了 Gitee 插件官方插件市场搜“Gitee”安装。如果你没有这个插件也可以先在码云手动建仓然后在 IDEA 的 Git 工具栏里配置远程地址。IDEA 的 Push 按钮在右上角点击后会弹出窗口让你填写远程地址粘贴 SSH 地址即可。用 IDEA 的同学要注意IDEA 默认会把你本地的 Git 身份信息带进来如果之前配过不一样的用户名push 到了远端会显示成不认识的作者建议先从Settings - Version Control - Git确认一下身份。VS Code默认只支持 Git 的基本操作远程仓库的 add、push 需要手动操作。装一个“GitLens”或“Git Graph”插件体验会好很多。VS Code 里推送的隐藏坑是它会默认使用系统凭据管理器如果你之前用 HTTPS 克隆过仓库Windows 下 VSCode 会优先走 Windows 凭据管理器里的旧账号导致 push 到错误账号。重装系统、换账号后特别容易踩建议把凭据管理器里旧的gitee.com凭据删掉。命令行 IDE 混用我个人的习惯是日常编辑用 IDE但分支操作和推送用命令行。因为命令行输出更清晰报错信息更容易定位问题IDE 有时候吞掉报错细节调试反而更慢。新手不要有“命令畏惧症”Git 的命令就那么几个用熟了比 IDE 按钮高效很多。4.3 推送过程中的其他细节最后分享几个容易忽略的细节大文件问题。码云单个仓库容量目前限制为 1GB单文件大小限制为 100MB。如果你的项目里有超过 100MB 的文件比如数据集、安装包、媒体素材push 时会直接被拒。解决方案有两个一是用 Git LFSLarge File Storage管理大文件二是不要把大文件放进 Git 仓库改用对象存储、网盘等平台存放代码库里只保留引用路径。换行符问题。如果你在 Windows 写代码推到 Linux 服务器上拉取会遇到 CRLF / LF 换行符问题。Git 默认情况下会做一些转换但如果你在项目里混用了不同系统的文件diff 时会看到整段文件全被标记为修改。解决办法是在项目根目录加一个.gitattributes文件明确指定文件换行符处理规则。细节不展开记住有这个问题、加.gitattributes能解决就够了。提交信息规范。很多人图省事提交信息随便写“update”“1”“asdf”等到三个月后回查历史记录看到这些提交完全想不起来自己干了什么。建议提交信息带上前缀比如feat: 新增登录功能、fix: 修复首页白屏问题、docs: 更新README、refactor: 重构数据层。这种规范不需要上什么重型工具自己养成习惯就好。.gitignore 要及时配。很多新手第一次推送时稀里糊涂把node_modules、.idea、target这些编译产物、依赖目录全推上去了。轻则仓库体积爆炸重则因为平台差异导致依赖在别人机器上报错。项目一开始就配好.gitignore是投资回报率最高的动作。可以直接去 GitHub 的 gitignore 仓库找一个跟你项目类型匹配的模板或者用码云创建仓库时的模板。如果已经推送了不该推的文件要用git rm --cached -r把文件从 Git 索引中移除再提交这样文件会从仓库中删除但保留在本地。网络中断导致的推送失败。如果你网络环境不太稳定push 到一半断线不用慌Git 有断点续传机制直接重新执行git push即可。如果反复失败可以尝试git config --global http.postBuffer 524288000这个命令把 HTTP 传输缓冲区调大对大仓库和弱网环境有一定帮助虽然不是万能药但不妨一试。我个人在实际操作中的体会是Git 推送这件事前几次走流程确实会踩各种坑但本质上它就是一个“本地和远程对暗号”的过程——密钥对了、地址对了、历史关系理清了剩下就是时间问题。建议新同学不用急着背命令第一次老老实实按教程走一遍把每一步执行后终端输出都看一眼遇到报错先读英文提示Git 的报错提示其实写得很清楚。等你配好密钥、成功推上去一次后面就很顺了。再遇到推送问题把这篇文章翻出来对照排查大概率就能找到答案。