企业官网建设流程全解析

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，理由很简单：

当然，如果你只是偶尔下载一个公开项目，那 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 git@gitee.com

如果终端提示：

Hi 你的用户名! You've successfully authenticated, but GITEE.COM does not provide shell access.

说明密钥已经生效。这里有个细节，首次连接时终端会问你Are you sure you want to continue connecting (yes/no)?，记得输入yes回车，别傻乎乎地输y，Git 只认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 地址，形如git@gitee.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 git@gitee.com:你的用户名/仓库名.git

origin是远程仓库的默认名字，是 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 git@gitee.com:你的用户名/仓库名.git

然后推送即可：

git push -u origin master

如果你发现本地已经配过远程仓库，执行git remote add会报错说origin已存在。这时候可以用git remote -v查看当前已有的远程仓库地址：

git remote -v

如果只是地址配错了，可以直接修改：

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

如果想把原来的远程删掉重新关联，则执行：

git remote remove origin git remote add origin git@gitee.com:你的用户名/仓库名.git

这里多说一句，经常有人在网上复制别人的项目代码，然后本地改了想去推到自己的仓库，结果发现 push 的时候一直往原作者仓库推——因为.git文件夹是复制过来的，里面记录的还是原仓库地址。这种问题用上面的git remote -v查一眼就能定位，然后改掉就行。

3.3 场景三：远程仓库已有内容，推送被拒绝

这个场景我几乎每周都会遇到。你创建仓库时勾选了初始化 README，或者远程已经有了别的提交，这时候git push会报错：

! [rejected] master -> master (fetch first) error: failed to push some refs to 'git@gitee.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 fetch+git merge，但 merge 会生成一个“合并提交”，历史记录会有一条分叉线。如果你想让历史更干净，可以用git pull --rebase，它会把你本地的提交重新“续”在远程提交后面，历史是一条直线。不过 rebase 会改写提交哈希，副作用是：如果别人已经从你的分支拉过代码，就不要随便 rebase 推送，会引发一串冲突。

4. 高频问题与排查技巧

4.1 认证相关的三个高频报错

推送代码时遇到报错，十有八九是认证问题。我整理了三个最高频的，你先对照排查：

报错一：Permission denied (publickey)

这个报错说白了就是 SSH 密钥没通过验证。排查步骤：

1. ssh -T git@gitee.com，看是否提示认证成功。
2. 如果提示权限拒绝，先确认公钥是否已经添加到码云后台，最好重新复制一遍公钥检查有没有粘贴完整、多复制了空格。
3. 确认你用的密钥不是默认文件名。比如你生成密钥时手动改成了gitee_rsa，Git 默认不会去找这个名字，你需要在~/.ssh/config里配置，或者手动指定。国内很多教程都会让人自定义密钥名，这反而埋了坑。对新手来说，默认的id_rsa是最省事的。

报错二：Remote host identification has changed

如果你换过系统、重置过 SSH 密钥，或者码云服务器的密钥发生了变化，可能会遇到这个提示，这是 SSH 为了防中间人攻击做的保护机制。解决办法是删除本地 known_hosts 里对应的旧记录：

ssh-keygen -R gitee.com

然后重新执行ssh -T git@gitee.com，输入yes记录新指纹。

报错三：remote: 对密码或 Token 认证的支持已关闭

如果你用了码云上的 HTTPS 地址，并且密码输入错误多次，可能会触发这个提示。码云为了账号安全，默认对密码认证限制较严格，HTTPS 方式已改为推荐使用私人令牌（Token）。遇到这种情况，要么换 SSH 地址，要么去码云“设置”——“私人令牌”生成一个 Token，HTTPS 推送时密码栏粘贴 Token。

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 LFS（Large 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 的报错提示其实写得很清楚。等你配好密钥、成功推上去一次，后面就很顺了。再遇到推送问题，把这篇文章翻出来对照排查，大概率就能找到答案。