企业官网建设流程全解析

前两天有个刚入门的朋友问我：代码写好了想传到 Gitee 上存起来，结果在命令行里敲git push一直被拒绝，弹出的提示看着像天书，查了半天才发现是 SSH 公钥没配置。这个场景我太熟了——刚接触 Git 的时候，我连"公钥""私钥"是干嘛的都搞不清，对着教程一步步点，点完了还是报错。这篇就把我踩过的坑整理出来，从 Git 安装、Gitee 建仓库，到 SSH 公钥的生成与配置，再到代码上传的完整流程，一次讲清楚。适合刚接触 Git、想在 Gitee 上管理代码的初学者，也适合装过 Git 但一直没搞明白 SSH 是怎么回事的同学。

1. 先把关系理清：Git、Gitee 和 SSH 公钥分别是干什么的

1.1 Git 解决的是"后悔药"和"协作"两件事

很多人第一次听到 Git，是在面试题或者同事嘴里，感觉是个很高深的东西。其实它的核心作用就两个：版本回退和多人协作。版本回退很好理解——你写代码改了一下午，改到第十版发现还是第一版最好，如果没有版本管理，你只能靠"复制另存为 xxx_final_v2_真final.zip"这种痛苦的方式。Git 用 commit（提交）把每次修改记成快照，想回哪一版都行。

多人协作则是 Git 更值钱的地方。本地随便怎么改都不会影响别人，提交之后推送到远程仓库，队友拉下来，各自在各自的分支上干活，最后合并。这个链条看着复杂，但只要把最基础的命令跑熟，日常单人开发也已经能明显感受到效率提升。

1.2 Gitee 是"放代码的云仓库"，不等于 Git

Git 本身是装在你电脑上的一个命令行工具，它的历史记录都存在本地目录里。但本地终究有风险——硬盘坏了、电脑丢了、你换了一台电脑，代码就没了。所以需要把代码放到一个远程托管平台上。Gitee（码云）就是国内常用的一家，功能上和 GitHub 类似，但服务器在国内，访问速度更快，中文界面也更友好。

打个比方：Git 像是你自己家里的一套档案管理系统，Gitee 则是把档案存到银行保险柜里，既能备份，也能分享给其他人一起编辑。很多人以为"Git 就是 Gitee"或者"Git 就是 GitHub"，这是最常混淆的一点。它们一个是软件，一个是网站服务，后面我会反复提到"本地"和"远程"这两个词，说的就是这两层。

1.3 SSH 公钥到底是个什么锁

SSH 公钥解决的是"怎么证明你是你"这个认证问题。每次 Git 要跟远程仓库通信，服务器都要确认：来的人是不是账号本人？最笨的办法是每次输账号密码，Git 也支持，但输一次两次还行，天天推代码还要输密码就太烦了。

SSH 的认证方式是：你本地生成一对密钥，一个叫私钥（自己留着），一个叫公钥（交给 Gitee）。当你发起连接时，私钥对请求做签名，服务器拿你事先存好的公钥去验证签名。签名对得上，就放行。这就好比你自己配了一把钥匙，把锁芯的"副本"留给门卫，之后每次进门前卫验锁芯，不用你再报一遍姓名密码。私钥一旦泄露，等于钥匙被别人配走了，这也是为什么所有教程都会强调：私钥文件绝不能上传、绝不能发给别人。

1.4 配置 SSH 到底值不值

这里可能有人会问：我用 HTTPS 地址克隆，记住密码以后也能免密啊，为什么还要折腾 SSH？我的建议是：如果是长期用命令行、或者经常跟远程仓库交互，SSH 一劳永逸。HTTPS 在部分环境下会反复弹认证提示，尤其在配置了二次验证的账号上，命令行里输密码还容易踩"认证失败"的坑。SSH 配好了，clone、push、pull 全程无感，换 IDE 也不用重新配账号。这一套配置大概十分钟，收益是之后一年都省心。

2. 环境准备：Windows 和 macOS 上把 Git 装好

2.1 Windows 安装：安装器里两个选项别选错

Windows 装 Git 最主流的方式是去 git-scm.com 下载安装包。安装界面虽然全是英文，但整个过程基本只需要一路 Next，有两个地方需要停一下看一下。

第一个是 "Adjusting your PATH" 这一步，一定要选中间那项 "Git from the command line and also from 3rd-party software"。如果你选成第一项 "Use Git from Git Bash only"，后续在 cmd 或 PowerShell 里敲 git 会提示命令找不到，这也是新手最常见的报错来源之一。

第二个是 "Choosing the default editor"，默认 Vim 可以保留，嫌难用可以后面再配 VS Code。反正第一次安装，核心目标就是：装完能在任意终端里敲出git --version。

git --version # 输出类似 git version 2.45.0.windows.1 就说明装好了

装完之后还会发现开始菜单多了一个 Git Bash，这就是一个类 Linux 的终端环境。我用 Windows 时习惯直接用 Git Bash 敲命令，因为它的命令提示和行为跟 macOS / Linux 更接近，教程里写ls、cat这些命令也能直接跑，不用再花力气记一套 Windows 版本的等效命令。后面我命令里的路径写法，也默认是在 Git Bash 环境下执行的，如果用的是 cmd 或 PowerShell，注意把cat换成本身的查看命令或者也用 Git Bash 操作。

2.2 macOS 安装：两种方式自选

macOS 上有两条路，一条是用 Homebrew 安装：

brew install git

另一条是安装 Xcode Command Line Tools，它会自带一个 Git 版本：

xcode-select --install

个人更推荐 Homebrew，因为版本新、后续升级方便（brew upgrade git一行搞定）。刚装完如果终端里执行git --version没反应，先检查一下命令是否被系统自带的旧版本覆盖，常见做法是用which git查看命令路径，确保指向你刚安装的位置。

2.3 装完第一件事：配置用户名和邮箱，不然 commit 会失败

这一步很多人会跳过，直到第一次git commit被拒绝才回来配。提交信息里必须带着作者信息，所以 Git 要求你提前声明"你是谁"。在任意终端执行：

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

--global表示全局生效，这样以后这台机器上所有仓库都默认用这个身份。建议邮箱和 Gitee 注册邮箱保持一致，这样代码提交记录能和账号关联上。

配置完成之后可以用git config --list查看所有配置项，确认无误。这些配置最终会写进用户主目录下的.gitconfig文件，如果你是个配置控，也可以直接编辑文件，但我还是建议先用命令，因为命令会顺便校验格式。之后再装小乌龟（TortoiseGit）这类图形客户端时，这套配置也会直接继承，不会出现两边身份不一致的问题。

3. 在 Gitee 上创建仓库：初始化选项别乱勾

3.1 注册和新建仓库的入口

登录 gitee.com 注册账号之后，右上角的"+"号或者主页的"新建仓库"按钮都可以进入创建页面。创建的时候需要填仓库名称和路径，路径会出现在访问地址里，比如我建一个叫 hello-git 的仓库，地址就是https://gitee.com/用户名/hello-git。仓库名称可以随时改，但路径一旦被别人引用，改了会影响访问，所以第一次命名尽量想清楚。

这个环节还有个很容易被忽略的点：仓库的"归属"选择。个人账号直接就是自己的，如果加入了某个组织或者企业，也可以选择建到组织下面。对个人学习来说，建在自己的账号下最省事，后面涉及到 SSH 公钥权限时也不容易混乱。

3.2 README、.gitignore、开源许可证到底选不选

创建页面有几个初始化选项，我的建议是：

• README：如果项目是公开的，建议勾选，它会作为仓库首页的说明文档。如果是纯私有备份，不勾也影响不大。
• .gitignore：这个非常推荐。它会告诉 Git 哪些文件不要纳入版本管理，比如 IDE 配置、编译产物、依赖包。Gitee 会根据你选择的语言生成一份模板，选对语言即可。
• 开源许可证：如果要开源，MIT 或 Apache-2.0 都行，MIT 更宽松；如果只是私有仓库，直接不选。

另外还有一个容易忽略的选项是仓库可见性：私有还是公开。私有仓库在 Gitee 上个人使用是免费的，但在网页上不会被别人搜索到。如果你只是想把代码当网盘用、不想分享，选私有就好。很多人一开始觉得公开也没关系，结果把写了一半的代码暴露出去，后面又来删库，反而麻烦。Gitee 支持仓库可见性设置和批量删库操作，网页上都能完成，但尽量在创建的时候就想清楚。

3.3 仓库页面要认识的三个地方

创建完成跳到仓库主页后，重点先看三个区域：

第一个是"克隆/下载"按钮。点开会同时显示 HTTPS 地址和 SSH 地址两种格式，前者长这样：

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

后者长这样：

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

地址是后续所有远程操作的关键，建议先复制到备忘录里存好。

第二个是默认分支名。Gitee 新建仓库通常默认分支是 master，也有人改成 main，这不重要，但你要记住自己仓库的默认分支是什么，因为推送的时候分支名必须对得上。

第三个是"文件"标签页。仓库里有哪些文件、谁改过、改了什么都从这里看。对初学者来说，这个网页上的历史记录列表，就是理解 Git 日志最好的辅助工具。网上搜 Gitee 使用教程时经常能看到"如何克隆项目""怎么把文件上传至 Gitee"这类问题，答案基本都藏在仓库页的地址和分支信息里。

4. 核心环节：SSH 公钥的生成与绑定

4.1 先查一查：这台电脑是不是已经有密钥了

在动手生成之前，先看一眼~/.ssh目录。Windows 上一般是C:\Users\你的用户名\.ssh，macOS / Linux 是/home/你的用户名/.ssh。终端执行：

ls -al ~/.ssh

如果看到id_ed25519和id_ed25519.pub或者id_rsa和id_rsa.pub这样成对的文件，说明已经生成过密钥。.pub结尾的是公钥，可以继续用，没必要重复生成。如果目录不存在，或者里面是空的，那就进入下一步。

这里我多说一句：很多人换电脑之后懒得配密钥，直接把旧电脑的整个.ssh目录复制过来，这其实是最快的恢复方式，只要私钥文件权限设置正确，一般都能直接用。如果你是 Windows 10/11 自带 OpenSSH，生成的目录结构和 Git Bash 是一样的，两边可以通用。

4.2 生成密钥：用 ed25519 还是 RSA？

现在主流推荐用 ed25519 算法，它比 RSA 更短、更快、安全性也不差，除非你要连一些特别老的服务器，才需要用 RSA 4096。命令如下：

ssh-keygen -t ed25519 -C "你的邮箱"

接下来会问保存路径，直接回车用默认位置即可，别改到一个自己都找不到的地方。然后会问要不要设置 passphrase（口令），我建议个人开发环境直接留空，否则每次使用私钥都要输入口令，反而把免密的意义搞没了。如果你安全意识强想设置，那就配合 ssh-agent 使用，避免反复输入。

生成完成后，~/.ssh下会出现两个文件：id_ed25519（私钥）和id_ed25519.pub（公钥）。再次强调：私钥永远不要发给任何人，也不要传到任何代码仓库里。公钥则可以放心分发，Gitee、GitHub 这类平台就是靠存公钥来识别你的。

4.3 把公钥复制到 Gitee 账号

查看公钥内容用：

cat ~/.ssh/id_ed25519.pub

输出是一长串以ssh-ed25519 AAAA...开头、以你邮箱结尾的文本，把它完整复制下来。然后登录 Gitee，点右上角头像，进入"设置"页面，找到"安全设置 → SSH 公钥"，标题随便填，比如"我的笔记本"，公钥内容粘贴进去，确定保存。

这里有个很常见的坑：复制的时候不要少字符、不要多空行。最稳妥的方法是直接用cat命令输出，然后用鼠标框选整个内容复制，别手打。Windows 用户在 Git Bash 里如果不好选中长文本，可以用cat ~/.ssh/id_ed25519.pub | clip把内容直接复制到剪贴板，再粘贴到网页输入框。这套操作在 Gitee 设置 SSH 公钥的教程里经常被简化掉，但实际用起来非常顺手。

4.4 验证配置是否成功：关注 ssh -T 的提示

配置完之后，在终端执行：

ssh -T git@gitee.com

第一次连接会提示是否信任该主机，输入yes回车。如果一切正常，你会看到一行类似这样的输出：

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

看到 "successfully authenticated" 就说明公钥已经生效了。如果输出的是Permission denied (publickey)或者Connection reset by ...，先别急，大概率是下面几个原因之一：公钥没粘贴完整、粘贴错了平台（加到了别人的账号下）、本地用的是 HTTPS 地址导致没走 SSH。逐个检查，通常十分钟内能解决。

5. 跑通全流程：从克隆到推送，第一次上传代码

5.1 情景一：远程已经有仓库，把它克隆到本地

在 Gitee 仓库页复制 SSH 地址，然后：

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

命令会把远程仓库的完整历史下载到当前目录，并生成一个同名文件夹。进入文件夹后你可以看到.git这个隐藏目录，它记录着整个仓库的版本历史，千万别手贱删掉，删了版本历史就全没了。

克隆完成后，用git remote -v看一下当前的远程地址，确认是 SSH 格式而不是 HTTPS 格式。有些时候网上教程里复制下来的是 HTTPS 地址，你照抄之后虽然能克隆，但后面每次 push 都要认证，所以这一步检查特别重要。如果发现地址不对，可以用git remote set-url origin git@gitee.com:用户名/仓库名.git改成 SSH。

5.2 情景二：本地已经有一堆代码，想推到空仓库

这是入门阶段最常遇到的场景——代码早就写在本地了，Gitee 上刚建了一个空仓库。流程分四步：

cd 你的项目目录 git init git remote add origin git@gitee.com:用户名/仓库名.git

如果项目还没有任何提交，先做一次初始提交：

git add . git commit -m "初始化项目" git branch -M main git push -u origin main

git remote add origin是把远程仓库地址和本地"origin"这个名字关联起来，从此push、pull都可以直接用 origin 指代远程。-u参数的意思是设置上游分支，设置了之后以后再推送只需写git push，不用每次重复写远程分支名，非常省事。

如果你创建的 Gitee 仓库默认分支是 master，记得把-M main改成-M master，或者干脆先用git branch查看当前分支名再决定。分支名对不上，推送时候会报一堆让人头大的提示。这也是网上搜索"Gitee 上传代码到仓库""怎么把文件上传至 Gitee"时最容易被忽略的细节。

5.3 日常迭代三步曲：改代码、提交、推送

代码托管起来之后，日常开发就是一套固定循环：

git status # 看当前改了什么 git add . # 把改动加入暂存区 git commit -m "提交说明" # 提交到本地版本库 git push # 推送到远程仓库

可以这样理解这几个命令的分工：git add是把要保存的东西放进购物车，git commit是结账生成一个快照，git push是把快照送货到远程仓库。购物车可以反复加减，没结账之前一切随意；结账之后想反悔就只能用回滚操作了，所以提交说明一定写清楚这次改了什么。

另外，多人协作或者多设备同步的情况下，推送之前先养成git pull的习惯。git pull会把远程的新提交拉下来合并到本地，再推上去就不会有冲突。如果直接推送时发现提示! [rejected]，说明远程有本地没有的提交，这时候强行推会被拒，正确做法也是先 pull。

5.4 分支、忽略文件和提交信息的小建议

既然是基础篇，分支不展开，但提一句：主分支保持基本可用，想开发新功能就开一个分支，测试稳定后再合并回主分支。这个习惯越早养成越好。

.gitignore建议单独维护，常见要忽略的有：Java 的target/、Node 的node_modules/、Python 的__pycache__/、IDE 的.idea/、.vscode/，还有各种.env环境变量文件。这些东西进了版本库，轻则让仓库变得臃肿，重则把密码密钥泄露出去。

提交信息用"动词 + 简要描述"的格式，比如fix: 修复登录超时问题、feat: 新增导出功能、docs: 更新 README，几个月后回看日志时，你会感谢当初写清楚的自己。

6. 高频报错和排查实录：这些坑我都替你踩过

6.1 "git 无法识别为 cmdlet、函数、脚本文件或可运行程序的名称"

这是 Windows 上新手的第一个拦路虎。原因基本只有一个：Git 安装时 PATH 没配好，或者安装完终端没有重新打开。系统环境变量里没有 Git 的可执行目录，cmd / PowerShell 自然找不到它。

解决办法：重新运行安装包，到 "Adjusting your PATH" 那一步选择中间选项（"Git from the command line and also from 3rd-party software"）；如果安装时已经选了还不行，就手动把C:\Program Files\Git\cmd加到系统环境变量 Path 里，保存后关掉终端重新打开。Git Bash 如果本身能打开但 cmd 不行，那也基本可以断定是 PATH 的问题。

6.2 Permission denied (publickey) 的完整排查链路

这个报错是 SSH 配置失败最典型的信号。按顺序排查：

1. 执行ssh -T git@gitee.com，确认是不是也报一模一样的错。
2. 打开 Gitee 设置里的 SSH 公钥列表，核对公钥内容是否完整、标题是否对应。公钥必须是一整行，以ssh-ed25519或ssh-rsa开头。
3. 检查本机~/.ssh下的私钥文件名。如果生成时改了文件名，Git 默认找不到，需要用ssh-add把私钥加到代理里，或者在~/.ssh/config里指定IdentityFile。
4. 确认克隆地址是git@gitee.com:用户名/仓库名.git这种格式，别把 HTTPS 地址当成 SSH 用。

还有一个容易被忽略的点：如果电脑时间和当前时间差太多，SSH 握手也可能失败。这个概率不大，但遇到查了所有配置都没问题时，顺手对一下时间总没坏处。

6.3 推送被拒：! [rejected] / failed to push some refs

这个报错的官方解释是"远程分支包含本地没有的提交"。最常见于：创建仓库时勾选了 README，同时本地又先执行了git init并提交过代码，两边历史没有关联，推送时就被拒绝。

解决思路是先同步再推送：

git pull --rebase origin main git push -u origin main

--rebase会把本地提交"重新放"到远程最新提交之上，这样历史是一条直线，看着干净。如果合并时有冲突，Git 会标出冲突文件，手动改完再git add、git commit继续。

也有人用git push -f强行覆盖，但这会抹掉远程的历史提交，单人私有仓库偶尔可以，多人协作的共享分支千万别这么玩。

6.4 克隆私有仓库报 404 或者提示没有权限

私有仓库对不可见账号来说就是 404，这是为了不泄露仓库存在性。遇到这种情况，确认三件事：你的 Gitee 账号是否登录、是否被添加为该仓库的协作者、克隆地址里的用户名是否拼写正确。如果仓库是你自己的但还是 404，大概率是没登录或者地址里用户名写错了。需要协作者时，在 Gitee 仓库的"管理 → 仓库成员管理"里添加对方账号，搜索到用户后选择角色，对方就能访问了。

6.5 Windows 换行符警告：LF 将被替换为 CRLF

在 Windows 上提交代码时，Git 经常提示 "warning: LF will be replaced by CRLF"，这是行尾符差异导致的。Windows 用回车换行（CRLF），Linux / macOS 用换行（LF），Git 默认会在检出时做转换，避免代码在两边系统上显示成一行。

我的建议是 Windows 上执行一次git config --global core.autocrlf true，macOS / Linux 上执行git config --global core.autocrlf input，以后基本不会再为这事烦恼。这个配置不是必须的，但配一下能少看很多警告，心情会好很多。

下面用一个表格收一下上面这些报错和对应的处理方式，方便你遇到问题时快速对照：

7. 配好 SSH 之后，还能顺手做的几件事

7.1 给静态站点一个家：Gitee Pages

如果你有个人主页、文档站或者纯前端项目想免费托管，Gitee 的 Pages 服务值得试一下。在仓库页面找到"服务 → Gitee Pages"，选择部署分支和目录，点击启动就能生成一个对外访问的静态网址。Gitee Pages 国内访问速度快，用来放项目文档非常合适。注意该功能需要完成实名认证，部署前先确认账号状态。

7.2 一个公钥可以同时用于多个平台

SSH 公钥的机制决定了同一对密钥可以添加到多个平台，比如 Gitee、GitHub 甚至公司内网的 Git 服务都可以注册同一个公钥。以后换新电脑时，备份好~/.ssh下的两个密钥文件，到新机器上放到同路径，再把公钥加到各平台，就能无缝恢复。前提还是一样的：私钥只在自己机器上，别上传、别外传。

7.3 给日常提交建立固定节奏

最后分享一些我自己的习惯。每天开始写代码前先git pull拉一遍远程更新，避免别人已经改了而你还在旧版本上写；下午或者晚上收工时确认当天改动已经commit并push，保证代码至少备份在远程。这个习惯最初看起来繁琐，但坚持一两周后，你会发现"代码丢了""改错了找不到之前版本"这种事彻底从你的工作里消失了。

我个人用得最多的一个技巧是git log --oneline --graph，可以把提交历史和分支关系以图形化方式压缩成一行行显示，比网页上的历史列表更直观。刚开始不必要背命令，能把status、add、commit、push、pull、clone这几个用熟，日常开发已经足够跑起来了。SSH 公钥配好之后，这些命令执行起来全程无感，你会慢慢习惯这种"只管写代码、不用管传输认证"的节奏。