企业官网建设流程全解析

在Mac上用Git往码云（Gitee）上传代码，这个需求看着挺基础，但真正上手的时候，坑多得能让你怀疑人生。我记得自己第一次在终端里敲完git push，看到一串红色报错直接懵住，后来才知道多半是分支名、远程地址或者SSH密钥的问题。这篇文章就把整个流程从头到尾捋一遍，从装Git、配密钥、建仓库，到日常提交推送、处理冲突，全给你讲透。不管你是刚接触命令行的小白，还是偶尔需要往码云传东西的同学，照着做基本都能一次跑通，同时也会把我踩过的那些坑单独拎出来说一说。

1. 准备工作：码云账号与Mac环境检查

1.1 注册并创建远程仓库

先去码云官网注册一个账号，这一步没什么好说的，手机号或邮箱都能注册。注册完之后，登录进入控制台，在右上角找到“新建仓库”的按钮，点进去会看到几个关键选项：仓库名称、是否开源、初始化仓库的方式。

这里有个容易纠结的地方：要不要勾选“初始化仓库”？选项里面通常会出现“使用Readme初始化仓库”这一项。如果你打算直接克隆到本地再开始写代码，勾选没问题；但如果本地已经有一个现成的项目目录，我建议不要勾选初始化，让远端仓库保持一个完全空白的状态，这样后面关联、推代码的逻辑会更干净，少一点历史冲突。

仓库名称尽量用英文和短横线组合，比如my-project-demo。中文名称虽然能用，但是命令行里敲来敲去容易出错，加上在URL里会有一堆转码字符，纯属给自己找麻烦。仓库创建好之后，会有一个HTTPS地址和一个SSH地址，长这样：

https://gitee.com/用户名/仓库名.git git@gitee.com:用户名/仓库名.git

这两个地址后续要用，先复制下来放着，耐心看完下一节再决定用哪个。

1.2 检查Mac上是否已安装Git

Mac系统自带Git，但不一定是新版本，更不一定是好用版本。打开终端，直接敲：

git --version

如果返回了一个版本号，比如git version 2.39.2，那么你已经有了Git，可以直接用。如果提示command not found，说明没装。Mac上推荐用Homebrew来安装：

brew install git

装完之后再看一眼版本号。注意，如果你之前电脑上有一个老版本的Git，又通过brew装过新版，偶尔会出现PATH冲突，明明执行的是/usr/bin/git而不是/usr/local/bin/git。这种情况可以先跑一下which git看看路径，再把Homebrew的bin目录放到PATH前面，省得后面用的时候遇到莫名其妙的问题。

提示：如果连Homebrew也没有装，可以先去Homebrew官网复制安装命令，正文就不展开了。装包工具这种东西，属于macOS开发环境里的基础设施，没装的话你后面装任何软件都会很难受。

2. Git本地配置：先让“你是谁”清楚

2.1 配置user.name与user.email

Git每次提交代码的时候，都会记录提交人的名字和邮箱。很多人在这个环节很随意，结果传到码云以后，提交记录里显示的人名是一串乱码，或者压根显示不出来。正确做法是设置成与码云账号一致的信息：

git config --global user.name "你的名字" git config --global user.email "你的邮箱"

这里强调的是--global，意思是全局生效，一次配置，本机所有仓库都通用。如果你只想针对某一个项目单独设置提交身份，可以去掉--global，把命令放到项目目录里执行，这样会覆盖全局配置。

配置完之后可以用这个命令确认：

git config --list

它会输出所有当前生效的配置项，包括user.name、user.email，以及下一节要讲的credential和remote相关配置。一旦发现user.name或者user.email写错了，直接重新执行一遍配置命令覆盖就行，没有别的副作用。

2.2 配置SSH密钥并添加到码云

我强烈建议你用SSH方式而不是HTTPS方式。原因后面说。先讲怎么配置SSH。

第一步，在终端里检查本地是否已经有一对密钥：

ls -al ~/.ssh

如果看到id_rsa和id_rsa.pub文件（或者id_ed25519和id_ed25519.pub），说明你以前生成过。要是没有，就生成一对新的：

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

终端会让你确认保存路径，直接回车默认就行。接着会让你设置一个passphrase，这是给私钥再加一层保护，平时自己本机使用可以直接留空，一路回车到底。我不建议小白在这里设置密码短语，因为每次连接都要输入一遍，体验很崩溃。

生成完之后，查看公钥内容：

cat ~/.ssh/id_rsa.pub

把输出的一大串以ssh-rsa开头的文本全部复制下来，然后打开码云后台，找到“设置”里的“安全设置”，找到“SSH公钥”选项，粘贴进去，起一个备注名保存。

这时候在终端里验证一下连接是否打通：

ssh -T git@gitee.com

如果看到Hi 用户名! You've successfully authenticated, but GITEE.COM does not provide shell access. 这样的提示，就说明SSH已经配置好了。

2.3 HTTPS方式与SSH方式怎么选

我知道很多教程会直接让你用HTTPS地址，因为简单，复制链接就行。但我在实际用下来的感受是，SSH方式更适合每天都要推拉代码的人。

HTTPS方式在推送时，每次都要输入码云的账号、密码（或者个人访问令牌），而且现在很多平台已经不支持用账号密码直接推了，得单独去生成访问令牌。如果你还在用旧密码习惯，大概率会碰到Authentication failed的报错。SSH方式配置好公钥后，推送、拉取都不需要再输密码，对日常效率提升是很明显的。

切换方式或者做对比的时候，可以看下面这张表：

我个人的选择：大概率是SSH，除非在特别受限的网络环境里，SSH端口被堵了，再退回HTTPS。

3. 从零到一：新建项目并推送代码

3.1 初始化本地仓库并关联远程

假设你本地有一个项目目录，里面是你的代码文件。打开终端，进入这个目录：

cd /Users/你的用户名/Desktop/MyProject

如果这个目录还不是一个Git仓库，需要执行初始化命令：

git init

执行完以后目录下会多出一个.git隐藏文件夹，不用管它，也可以随时用ls -a查看。初始化的意思是让Git开始“盯着”这个目录里的文件变化。

接着把远端仓库关联上，这里用同一个示例名字，但请注意替换成你自己的地址：

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

把origin理解为本地仓库给远端仓库起的一个昵称，习惯上大家都用origin。如果以后想改地址，可以用：

git remote set-url origin 新地址

关联好了之后，可以用git remote -v来验证：

git remote -v

正常情况下会输出两行，fetch和push各一行，对应你刚才设置的地址。如果输出为空，说明关联没成功，重新执行git remote add origin那一步就好。

3.2 提交本地代码并推送到码云

这里要从工作区、暂存区、本地仓库、远端仓库这几个概念开始讲清楚，因为很多人用了很久Git，一说git add和git commit还是一团浆糊。

工作区是你当前操作目录里看得见的文件；暂存区是从工作区选出来准备提交的内容；本地仓库是提交之后生成的记录；远端仓库是码云上的那个仓库。整个流程就是：文件先在工作区，通过git add放进暂存区，再通过git commit提交到本地仓库，最后用git push推到远端仓库。

先把当前目录下所有文件加入到暂存区：

git add .

如果你只想添加某一个文件，可以用git add 文件名。这里有一个值得注意的点：.会添加所有变动过的文件，包括可能不想提交的临时文件、日志文件、编译产物等。所以规范的项目里都会有一个.gitignore文件，把这个文件提前写好，能省掉很多麻烦。不知道怎么写.gitignore的，可以去搜索对应语言的模板，比如Python临时文件__pycache__、Node的node_modules，都需要忽略。

添加完成后，可以查看状态：

git status

这个命令会告诉你哪些文件已经进入暂存区，哪些还没有被跟踪。养成随时查看状态的习惯，才不会出现“我改了代码但提交了个寂寞”的情况。

接着提交到本地仓库：

git commit -m "第一次提交"

-m后面是提交信息，建议写清楚这次改了什么，比如“新增登录页面”“修复列表排序问题”，不要写“update”或者“111”这种没意义的短语。提交信息是给未来的自己和其他协作者看的，诚实一点没有坏处。

最后推送：

git push -u origin master

如果是新仓库新代码，这个命令基本就能搞定。-u参数的意思是设置上游分支，把本地的master分支和远端的master分支关联起来。以后再次推送的时候，直接输入git push就行了，不需要每次都带上origin和分支名。

推送成功后，去码云仓库页面刷新，应该能看到代码已经在文件列表里了。

3.3 从远端拉取代码（克隆与pull的日常习惯）

如果你不是从零开始建项目，而是要把码云上已经存在的仓库拿到本地来，操作更简单：

git clone git@gitee.com:用户名/仓库名.git

克隆完成之后，会自动进入那个仓库目录。但要注意，克隆下来的项目和你的项目如果已经存在同名目录，会提示是否覆盖；建议把本地原有目录备份后再克隆，避免代码被覆盖丢失。

日常开发中最常用的是git pull：

git pull origin master

这个命令会把远端master分支上的最新提交拉下来，合并到当前本地分支。如果你在码云网页端直接改了代码，或者同事推了新代码，本地需要执行一次pull才能拿到。很多冲突都出现在pull之后：本地改过同一个文件的同一行，远端也改了那一行，Git就会提示冲突。这时候必须手动打开文件，选择保留哪一边，或者两边的改动都要，然后再重新git add和git commit，完成一次合并提交。

常见的冲突标记长这样：

<<<<<<< HEAD 本地改的内容 ======= 远端改的内容 >>>>>>> origin/master

不要慌，把标记和不需要的内容删掉，留下最终想要的内容，保存文件，再add、commit、push就完成了。看到冲突不是坏事，至少说明你和别人改的是同一块代码，总比闷头写完了才发现完全对不上要强。

4. 实操过程中遇到的坑：常见问题排查实录

4.1 被拒绝的非快速前进推送

推送的时候最经典的一个报错是：

! [rejected] master -> master (non-fast-forward) error: failed to push some refs to 'git@gitee.com:用户名/仓库名.git' hint: Updates were rejected because the tip of your current branch is behind...

这个问题的原因很简单：远端仓库里有你本地没有的新提交。比如你创建仓库的时候勾选了初始化README，那么远端就多了那个README；或者别的电脑往这个仓库推送过代码。

解决办法是先pull合并，再push：

git pull origin master git push origin master

如果远端仓库只是一个没有实际内容的README，你又不想保留它，也可以用强推：

git push -f origin master

但强推相当于把远端的历史覆盖成你本地版本，会让远端已有的其他提交消失，所以这个命令只能用在确定自己拥有仓库绝对控制权、并且不会影响其他人的时候。我见过有同学在团队仓库里强推，结果把同事一天的提交全干掉了，场面极其惨烈。能用普通pull/push解决的情况，永远不要先想着-f。

4.2 分支名是master还是main？

Git刚诞生那会儿，默认分支名是master。前几年很多平台把初始分支改成了main。码云现在新建仓库时默认分支是master还是main，取决于你的设置或者模板。这就导致一个很常见的问题：本地是master，远端也是master，倒还好；但你克隆下来的代码，分支可能是main，你自己git init之后又是master，两边对不上直接推送失败。

方法很简单：

git branch -M main

这条命令会把当前分支重命名并强制指定为main。如果远端是main，本地也改成main，然后再push。如果你习惯用master，那就把远端仓库默认分支改成master，在码云仓库“管理”里可以找到分支设置。

遇到这种问题不要背命令，理解一下原理就好：分支名只是一个名字，推送的时候Git要求“本地分支”和“远端分支”存在对应的跟踪关系，名字不同就会拒绝。取名一致就没有这个问题。

4.3 推送成功但码云上看不到代码？

这个问题通常发生在你使用了git add .之后，又改了文件，然后没有再次git add和git commit，只执行了git push。Git不会把未提交的改动推送上去，因为推送的是“提交记录”，而不是“目录里的文件状态”。解决方案很简单：提交前看一下git status，确保所有改动都已经add了，如果还有变更列表，就重新add、commit再push。

另一种情况是.gitignore写得太狠，把代码文件都忽略了，比如写了*.txt把整个目录的文本文件全过滤了，那么git add .就不会把这些文件加入。查看git status时，这些文件会出现在untracked列表之外，甚至根本不显示。这种情况要检查.gitignore的规则是不是范围太大，再用git check-ignore -v 文件名来确认哪个规则匹配了它。

4.4 SSH连接失败与权限问题

如果你配置了SSH密钥，但推送时报Permission denied (publickey)，大概率是公钥没正确添加到码云，或者本地使用的私钥不是签名的那一把。可以先执行：

ssh -T git@gitee.com

看实际输出，如果报错，先检查是不是用的id_rsa（如果你之前生成过多对密钥，Git会按默认路径寻找）。如果默认路径下找不到密钥，可以创建一个config文件指定使用哪把私钥：

Host gitee.com HostName gitee.com User git IdentityFile ~/.ssh/id_rsa

另外，Mac上偶尔会出现“钥匙串”里保存了旧的账号密码信息，导致SSH连接或者HTTPS认证走得其实不是预期路径。遇到认证异常时，可以在“钥匙串访问”里搜索gitee相关的条目，删掉重试。

4.5 常见问题速查表

5. 进阶操作：让码云日常使用更顺手

5.1 用标签打版本

当项目进入某个稳定阶段，比如第一版上线、功能冻结，我会习惯给这个版本打一个标签。标签相当于给某一次提交贴了个名字，方便之后随时找回。

git tag v1.0.0 git push origin v1.0.0

第一个命令在本地打标签，第二个命令把标签推到远端。以后在码云上能直接看到v1.0.0这个版本。要列出所有标签就用git tag，不加参数就是纯列出。删标签也很直接：

git tag -d v1.0.0 git push origin :refs/tags/v1.0.0

这里第一行删本地标签，第二行删远端标签。日常开发样板里，你完全可以不用标签，但用了以后，每次代码发布都会变得很有仪式感，而且在出问题时能快速定位到旧版本。

5.2 分支合并与协同工作

码云仓库一般支持多人协作。你在本地新建一个分支：

git checkout -b feature-login

这个命令会从当前分支创建一个名为feature-login的新分支并切换过去。在这里写代码、提交、推送：

git push -u origin feature-login

然后在码云网页上创建合并请求，把feature-login合并到主分支。这种工作流叫“分支开发，合并审查”，适合团队协作场景。即使只一个人开发，用分支隔离功能模块，也比所有代码都堆在master上更清晰。

5.3 换电脑后如何快速恢复环境

换了台Mac，第一件事就是装Git、装Homebrew、配置SSH密钥。生成新密钥对，把公钥加到码云账号上，然后克隆仓库。以前你全局配置过的user.name和user.email要重新设置一遍，因为不同电脑的全局配置是独立的。如果换了电脑之后推代码发现提交者不是你，多半就是这一步漏了。

有些人会保存一个带dotfiles的云同步仓库，把配置文件同步下来，但我不建议初学者这么干，容易把系统配置弄乱。自己手动执行几条git config命令就够用了。

6. 关于码云与Git的几点个人心得

我从一开始就在本地用终端操作Git，而不是依赖图形界面工具，理由比较简单：命令行能让你看到每一步操作的真实过程，出错了也能根据终端提示直接排查，而图形界面很多时候把细节藏起来了。等你熟练以后，大部分操作其实就剩几个命令：git add、git commit、git pull、git push，加一个偶尔用用的git log。

再聊一下码云本身的体验：国内访问快，对中文项目的支持也好，不像有些国外平台偶尔出现网络抽风的情况。常用功能和企业协作方案都比较完整，个人项目、小团队内部协作都够用。而且它在创建仓库时提供了非常友好的模板引导，甚至可以直接导入其他平台的项目，这一点对那些从其他平台迁移过来的团队很友好。

我个人在实际操作中的体会是，把SSH配好、分支名统一、提交信息写清楚，这三个习惯养成之后，Mac上用Git传代码到码云就变成了一件非常无聊且稳定的事情。无聊是好事，说明你做的事情已经成了肌肉记忆，不会出错。到最后，你真正需要担心的反而不是怎么上传代码，而是你的代码写了什么、改得好不好，以及你提交的时候有没有把不该提交的密钥文件带上去。那种把API密钥传到公开仓库里的事故，才是真正让人夜里惊醒的事故。