企业官网建设流程全解析

刚开始折腾 Git 托管平台的时候，我一度觉得 Gitee 只是“GitHub 的国内替代品”，随便注册个账号把代码推上去就完事了。结果真正开始做仓库管理才发现，门道全在细节里：密钥配不好，push 的时候一脸懵；分支策略不统一，三五个人的团队能把主线搞得一团乱麻；更别说 Release、Pages、Webhook 这些功能，很多人从头到尾压根没点开过。

这篇内容不讲套话，全部是我自己踩过坑、验证过的实操经验。从创建仓库之前的账号准备，到“下载代码—改代码—上传代码”的标准循环，再到分支保护、历史清理、Pages 部署这些进阶玩法，我会把每一步的关键选择和背后原因都掰开讲清楚。适合刚接触 Gitee 的新手，也适合带小团队做项目、想把仓库管理规范化的老手。看完照着操作，你的 Gitee 仓库基本不会再出那些“莫名其妙的怪问题”。

1. 仓库创建前的必做功课：账号、密钥与属性选型

1.1 SSH 密钥配置：为什么这是仓库操作的“门禁卡”

很多人第一次使用 Gitee 时，会直接复制 HTTPS 的仓库地址，然后每次 push 都要求输入用户名密码。一次两次还能忍，次数多了就发现效率低得离谱。相比之下，SSH 模式只需要在账号里绑定一次公钥，之后所有本地操作都走密钥认证，既不用反复输密码，也更安全。

SSH 登录的底层逻辑其实就是一对“门禁卡和锁”。本地生成一对密钥：私钥留在自己电脑上，公钥填到 Gitee 的账号设置里。每次连接时，Gitee 服务器用公钥验证你的身份，本地则用私钥完成签名。私钥一旦泄露，等于把门禁卡交给了别人，所以存放私钥的文件一定不能随意拷贝。

配置步骤很固定。打开终端，执行：

ssh-keygen -t ed25519 -C "你的邮箱@example.com"

建议使用 ed25519 算法，生成的密钥短、安全强度高。如果电脑比较老，或者公司安全策略要求 RSA，可以换成ssh-keygen -t rsa -b 4096。一路回车会生成在默认目录~/.ssh/id_ed25519，接着查看公钥内容：

cat ~/.ssh/id_ed25519.pub

复制完整输出，打开 Gitee 网站，点头像进入“设置”——“SSH 公钥”，粘贴保存。最后验证是否通了：

ssh -T git@gitee.com

第一次会让你确认主机指纹，输入yes。如果返回“Hi 用户名! You’ve successfully authenticated”，说明密钥配置成功，后面 clone、push 都不需要再输密码。

这里有个我经常看到新人犯的错：密钥配好了，但 Git 的全局用户信息没设置，导致提交记录里显示的是匿名身份，甚至有些场景下 push 被拒。顺手把这两个命令也执行了：

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

设置完可以查一下git config --list，确保信息正确。这一步虽然和密钥无关，但属于仓库操作的“地基”，提前铺好能省很多事。

1.2 仓库可见性与开源许可证：创建时不纠结，后面少折腾

创建仓库时有两个选项特别容易随便选，一个是“私有/公开”，另一个是“开源许可证”。我见过不少项目，创建时随手选了公开，后来代码里带了一些不该公开的东西，只能急急忙忙清历史、改权限。反过来，有些项目想靠开源建立影响力，却一直开着私有仓库，错过了很多曝光机会。

我的建议很简单：拿不准的时候就先建私有仓库，代码推进稳定了再切公开。Gitee 支持仓库可见性的后置修改，公开转私有或者私有转公开都行，但从公开转私有之后，star、fork 这些公开痕迹并不会完全消失，所以宁可在开始时保守一点。

开源许可证这个选项，很多新手完全无视。需要明确一点：不选许可证，并不代表“随便用”，在法律意义上默认是“保留所有权利”，别人即使看到你的源码，也不具备合法的使用、复制、分发权限。如果你想做开源，许可证必须选。

我个人给团队的建议是：通用工具类组件选 MIT，双方都省心；涉及底层框架或者希望社区一起维护的项目，可以选 Apache-2.0；如果是做研究型项目、希望别人改完也必须开源，那就选 GPL-3.0。注意我这不是法律意见，只是实践经验，具体到商业敏感项目，最好还是找法务确认。

仓库名也值得花十秒钟想清楚。Gitee 对仓库名的大小写和连字符有一定要求，建议统一用小写字母、数字和中划线，比如my-blog、order-service-api。中文仓库名虽然能用，但 URL 拼出来一长串编码，不管是在文档里引用还是命令行敲，都很难受。创建仓库时建议勾选初始化 README，顺带选上合适的.gitignore模板，Java 项目选 Java，Node 项目选 Node，这样第一次提交就不用费劲把构建目录塞进版本库。

2. 代码从本地上云：最核心的 Git 仓库操作流程

2.1 一次完整的“下载代码—改代码—上传代码”循环

Gitee 仓库管理的日常操作，本质就是一个循环：从远端拉代码，在本地修改，再把改动推回远端。很多人把 clone、pull、push 混为一谈，遇到问题全靠网上复制命令，结果改了文件之后不敢提交，生怕把仓库弄坏。

先从“下载代码”说起。拿到一个仓库地址，标准操作是：

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

这里用的是 SSH 地址，前提是你已经按第一部分配好了密钥。如果某些机器不方便配密钥，也可以用 HTTPS 地址，但后面 push 时需要输入用户名密码或个人访问令牌。我基本只在临时场景下用 HTTPS，长期开发的电脑一定配 SSH。

本地已经有一堆代码、想推到 Gitee 上新建的仓库时，很多人会直接操作，流程倒是不难：

cd existing_folder git init git remote add origin git@gitee.com:用户名/仓库名.git git add . git commit -m "first commit" git push -u origin master

但这里有个非常常见的坑：如果你在 Gitee 创建仓库时勾选了“初始化仓库”，远端就会有一个带 README 的初始提交，而本地是用git init全新初始化的历史，两边没有任何共同祖先。此时直接 push，大概率会报failed to push some refs，原因是远端有本地没有的提交，属于“非快进推送”。

我踩过一次之后，就不再纠结这个报错本身了，而是改变操作习惯：如果本地已有代码，Gitee 创建仓库时务必选“不初始化仓库”，保持一个空仓库状态；如果远端已经初始化了，最简单的办法不是解决冲突，而是直接：

git pull origin main --allow-unrelated-histories

合并两个不相干的历史后，再 push。但说实话，这条命令容易把提交历史弄乱，所以我更推荐的做法是：在空仓库状态下，直接git remote add origin然后提交推送，干净利落。

还有一个容易忽略的细节：Gitee 的默认分支名可能是master，也可能是main，取决于你创建仓库时的选项。现在新项目一般都建议用main，因为更符合当下的主流约定。如果远端默认分支是main，你本地默认分支还是master，直接执行git push -u origin master会被拒绝。解决办法是把本地分支改名：

git branch -M main

再执行：

git push -u origin main

从零开始走这个过程，建议顺序是：Gitee 建空仓库 -> 本地git init->git remote add-> 提交 -> 推送。这套流程我已经用了很久，基本不会再遇到历史分叉的怪问题。

2.2 分支管理与提交信息：把仓库历史整理成“可读的日记”

分支管理是我审仓库时最先看的东西。一个没有分支策略的仓库，所有人和所有功能都在main上疯狂提交，看起来每天都在更新，实际上代码状态混乱到无法发布。你问任何人“当前主线能不能上线”，没人敢给准话。

我常用的分支模型是：main始终保存可发布状态，dev做日常集成，功能分支叫feature/xxx，修复分支叫fix/xxx。每接一个新需求，不要直接在main上改，而是先切分支：

git checkout main git pull origin main git checkout -b feature/order-export

开发完成并验证之后，再切回main合并：

git checkout main git pull origin main git merge --no-ff feature/order-export

--no-ff的作用是强制生成一个 merge commit，即使这个分支只有一个提交，也能在历史里清楚地看到“这里合并过 order-export 这个功能”。扁平的线性历史看着很漂亮，但团队协作时，merge commit 提供了更清晰的功能边界。

提交信息这块，我坚持用格式化的写法。每个提交第一行尽量控制在 50 个字符内，用feat:、fix:、docs:、refactor:这样的前缀表明类型，第二行空一空，再写详细说明。举个例子：

fix: 修复订单列表在空数据时白屏的问题 原因是分页组件在 total 为 0 时没有渲染 empty 状态， 已补充默认空态文案。

这样写之后，git log --oneline扫一眼就能知道每次提交做了什么。团队里如果有人写“update”“修改”“123”这种提交信息，我会直接打回重写。提交信息是写给未来同事看的，不是写给 Git 看的。

.gitignore也是分支管理之外的必备项。Node 项目一定排除node_modules、dist、coverage；Java 项目排除target；Python 项目排除__pycache__、.venv。另外所有环境变量文件，比如.env、.env.local，必须忽略掉，这类文件里通常有数据库密码、API Key，一旦进版本库就是安全事故。判断标准很简单：凡是本地执行环境可能自动生成的、或者包含机器特定信息的文件，都不应该进仓库。

2.3 多人协作下的同步与冲突处理

多人协作的第一步，不是写代码，而是同步。每天早上到工位，先把远端的最新代码拉下来，再动手改自己的分支。我的同步顺序是：

git checkout main git pull origin main git checkout feature/order-export git rebase main

这里用rebase而不是merge，是有讲究的。rebase会把你当前分支上的提交，重新应用到main的最新提交之后，形成一条线性历史，避免出现一堆乱七八糟的“Merge branch 'main' into feature/xxx”提交。你可以在自己还没推送的分支上放心用rebase，但绝对不要对已经推送到远端的公共分支执行rebase，因为那会重写提交历史，直接坑到所有基于这个分支协作的同事。

冲突是 Git 绕不开的环节。执行git rebase main时如果提示冲突，Git 会在冲突文件里标出两边的内容：

<<<<<<< HEAD 当前分支原来的内容 ======= main 分支带来的内容 >>>>>>> main

我处理冲突的习惯是：先用git status梳理出哪些文件冲突了，再用编辑器逐个打开，逐段决定保留哪边、删掉哪边，或者两边都要并做调整。改完之后执行：

git add 文件名 git rebase --continue

最后再重新提交。如果是 merge 模式冲突，改完add之后直接git commit即可。

这里还有一个提醒：冲突并不可怕，可怕的是不知道冲突是怎么产生的。大部分冲突的根源是两个人改了同一个文件的同一块区域。想减少冲突，就要养成小批量提交、频繁同步的习惯，不要憋了两周的代码一次性推上来，那冲突量会瞬间爆表。我把冲突的解决原则总结成一句话：“先看上下文，再动代码；宁可多读一会儿，不要盲目删除。”这条规则我一直在团队里强调。

3. 仓库价值的二次开发：Pages、Release 与自动化联动

3.1 十分钟发布静态站点：Gitee Pages 完全够用

Gitee 在很多人的印象里只是“存代码的地方”，但实际上它还提供 Pages 服务，可以把仓库里的静态文件直接变成一个可访问的网站。个人博客、项目文档、前端 demo、临时演示页，都可以用这个功能搞定。

我这里说的“静态文件”，指的是纯 HTML、CSS、JavaScript 这类不需要服务器动态渲染的文件。如果你用 Vite、Hugo、VuePress 这类工具构建过站点，构建完成后生成的dist、public或者docs目录就是静态文件。把构建产物推到仓库里，然后打开仓库页面进入“服务”——“Gitee Pages”，选择发布分支和目录，点一下“启动”，就可以得到类似https://用户名.gitee.io/仓库名的地址。

我实际部署过一个 Vite 项目，流程大概是：本地构建生成dist，为了不污染源码，我单独用一个分支pages来存构建产物，或者直接把dist目录推到一个独立仓库。然后在 Pages 设置里把分支和目录指到对应位置。如果项目本身就是一个纯静态站点，直接把index.html放在仓库根目录，发布目录选“根目录”就行。

有几个细节需要特别注意：

• Pages 只能托管静态文件，PHP、MySQL、Node 后端这类动态逻辑跑不了，别指望拿它当服务器用。
• 每次更新静态文件后，需要回到 Pages 服务里重新部署，或者更新完后刷新，让它重新拉取仓库内容。
• 想绑定自己的域名，可以去 Pages 设置里配置，但前提是平台要求的身份验证已经完成，并且域名解析按提示设置好。

我见过不少新手把node_modules一起提交到仓库，然后启动 Pages 发现网站打不开。这其实不是 Pages 的问题，而是发布目录选错了，你应该只发布构建后的文件夹，而不是整个仓库。 Pages 的核心定位是“轻量、免费、快速上线的静态托管”，不要让它承担复杂的业务服务器职责。

3.2 Release 发布包的管理：给版本一个明确的“归档”

很多团队管理项目，版本号只是随手写在 README 里的几个数字，真正要交付给用户的时候，才发现没有发布包、没有更新日志、没有二进制文件，只能让人去 clone 源码自己编译。这是典型的仓库管理不到位。

Gitee 的 Release 功能，本质上是在一个 Git 标签（tag）上挂载一份“发布说明”和若干附件。打标签的命令是：

git tag -a v1.0.0 -m "release v1.0.0" git push origin v1.0.0

然后到 Gitee 仓库页面的“发行版”里，找到这个标签，填写发布标题、更新说明，上传编译好的压缩包、安装包或者文档附件。保存之后，用户可以直接在网页上点击下载，不需要碰 Git 命令。

版本号我建议遵循语义化版本规范：主版本.次版本.修补版本。比如1.4.2，主版本是 1，次版本是 4，修补版本是 2。当你的 API 发生不兼容变更时，主版本要加一；新增了向后兼容的功能时，次版本加一；只修复 bug、没有新增功能时，修补版本加一。这条规则不复杂，但团队里只要有人不遵守，版本号就彻底失去参考价值。

我在团队里推行 Release 管理之后，最大的收获是“回溯问题变得简单了”。用户反馈某个版本有 bug，我们可以直接定位到对应 tag 对应的代码状态，而不是对着main分支的最新代码猜半天。Release 的更新说明里还可以放“此版本新增了什么”“已知问题是什么”，这比让用户翻 commit 记录体感好太多。

3.3 Webhook 通知：让仓库成为自动化流程的“起点”

如果只是把代码推进仓库就结束，Gitee 和网盘也没什么区别。真正让仓库“活起来”的，是它作为自动化流程起点的能力，而这正是 Webhook 的用武之地。

Webhook 的逻辑可以这样理解：你在仓库里配置一个 URL，当特定事件发生时，Gitee 会主动往这个 URL 发送一个 HTTP 请求，通知你“仓库有动静了”。比如代码 push、Pull Request 被创建、Issue 被关闭，这些事件随时可以触发你的构建脚本、通知机器人或者接口服务。

在 Gitee 仓库的“管理”——“WebHooks”里，可以填写接收通知的 URL，选择触发事件，比如推送到main分支时触发。最常见的用途是：自己的服务器上部署了一套构建服务，当main分支收到新提交，Webhook 推一条 POST 请求过来，服务器收到请求后自动拉代码、跑测试、做构建。这样整个发布流程就从“手动登录服务器执行命令”变成了“push 即触发”。

配置 Webhook 时我特别强调一个安全细节：你的 URL 如果是公网可访问的，那么任何人都可能伪造请求。务必要在 Webhook 配置里填一个 secret 密钥，接收端校验请求头里的签名，不匹配的请求直接拒绝。我在自己的服务器上处理这种 POST 请求时，至少会做两层校验：一是校验请求来源 IP 是否可信，二是校验签名或 token 是否等于预期值。曾经有人只是配置了 URL、没加任何校验，结果被外部扫描器乱打了一堆请求，构建服务器被白白浪费资源，甚至还暴露了内部接口信息。

Webhook 是一个“接口思维”的玩法，不依赖任何重型中间件，只需要你有一个可以接收 HTTP 请求的入口就行。无论你用的是 Node、Python 还是其他后端技术，写一个接收函数，解析 JSON payload，再执行对应逻辑，整套联动就跑起来了。

4. 仓库管理踩坑实录：权限、误操作与清理修复

4.1 高频报错速查：从“权限不足”到“拒绝推送”

管理 Gitee 仓库久了，你会发现绝大多数报错都集中在几个固定场景。与其每次打开搜索引擎现查，不如把高频问题整理成一张速查表，遇到问题先对照原因，再动手处理。

我印象最深的是很多人遇到“非快进推送”时，第一反应是git push -f强制推送，直接把远端的初始提交覆盖掉。这确实能解决问题，但它是一个非常危险的习惯。如果那条远端提交是同事刚推上去的，你一个-f就能把别人的工作“蒸发”掉。我的原则是：-f只用于你确定是本地唯一开发者的分支，或者你确实需要重写历史且已经和团队确认过的场景，其他情况一律先 pull 再 push。

git pull --rebase和git pull的区别也需要讲清楚。前者把你的本地提交从远端最新提交之后重新应用，历史更线性；后者会直接产生一个 merge commit，历史里多一个“合并分支”的记录。日常同步我用--rebase，但如果我的分支已经推送过、同事也在同一个分支上协作，那就老老实实用普通git pull，避免重写公共历史。

还有一个小问题被问得很多：git 命令在 Windows 上输入中文提交内容时，偶尔会出现乱码。这不是仓库坏了，而是编码和终端配置的问题。建议把仓库里的提交信息统一用英文和中文混合描述时，确保文件编码是 UTF-8，并设置：

git config --global core.quotepath false

这能让中文文件名在git status输出里正常显示，视觉上清爽很多。

4.2 团队协作的安全边界：成员权限与分支保护

仓库管理不只是命令行的操作，权限分配才是决定“谁能动代码”的关键。Gitee 的仓库成员分为多个级别，从只读的观察者，到可以推送代码的开发者，再到拥有全部管理权限的管理员。我在给团队建仓库时，会让每个人按职责选择自己的角色：核心维护者给开发者权限，外部协作人员尽量给只读权限，严禁每个人都开管理员。

很多团队犯错，是“谁提了需求就在仓库里拉一个权限”，最后仓库的管理员快和成员一样多了。这带来的直接问题有三个：第一，任何管理员都能调整仓库设置，误操作概率大增；第二，代码保护机制形同虚设，谁都能往main直接推送；第三，一旦有人离开团队，清理权限时找不到到底给他开了哪些入口。

更稳妥的做法是配合“分支保护”使用。Gitee 仓库的“管理”——“分支设置”里，可以把main设为保护分支。保护分支的效果是：开发者不能直接向这个分支 push，所有变更必须通过 Pull Request 流程，并且可以设置至少需要多少人评审通过才能合并。这样一来，main就不是任何人随意修改的地方，而是一个有审批门槛的正式发布通道。

我在小团队里推行的做法是：仓库给三四个开发者权限，但main开保护分支，要求至少 1 个评审人通过。这个设定看起来增加了一点流程成本，但它能逼着团队成员在合并之前多看一眼自己的代码，很多低级的“早上还能跑，下午就崩了”的问题，都在这个环节被拦住了。

如果团队还没有启用分支保护的习惯，可以从一个简单规则开始：谁开发的功能，不自己合并到main，而是开 Pull Request 让别人 Review。Review 不光是找 bug，也是在帮团队同步背景知识，避免核心代码只有一个人看得懂。等这个流程适应了，再慢慢提高评审人数和保护范围。

4.3 历史清理与敏感信息补救：仓库“翻新”的正确姿势

仓库管理里最难处理的事情，不是不会 push，而是把不该提交的东西推了上去。我见过有人把数据库密码写进配置文件直接提交到公开仓库，也见过有人在仓库里误传了几百 MB 的日志文件，还见过把本地的密钥文件整个放大包里推上来的。

首先要强调：一旦敏感信息推到远程仓库，仅仅删除这个文件是不够的，因为 Git 的提交历史里还保留着这份文件的每一个历史版本，任何人 clone 仓库、翻一下历史，就能把它找回来。所以正确的补救顺序是：

第一，立即到 Gitee 把仓库设为私有，阻断新的公开访问。 第二，马上修改或撤销被泄露的密码、密钥、Token，因为历史已经存在，泄漏风险已经发生，改密码才是止损的关键一步。 第三，把敏感文件从当前代码里剔除，加入.gitignore，提交一个“移除敏感信息”的修复。 第四，用工具清理 Git 历史，把敏感文件从所有历史提交中抹掉。

清理历史我最常用的工具是git-filter-repo，比老牌的filter-branch快很多，也更不容易出错。安装之后，一条命令就可以把某个文件从全部分支历史中移除：

git filter-repo --path .env --invert-paths --force

这条命令的意思是：把所有路径为.env的文件从历史中反转排除掉。执行完成后，所有 commit 的哈希都会变化，所以需要和团队成员协调好，在一个统一时间点做清理，清理完成之后所有人都要重新 clone 仓库，不能用原来旧的本地历史继续 push，否则那些敏感文件会再次回到远端。

清理完历史之后，再去 Gitee 的仓库设置里检查一遍，确认没有其他分支、旧标签、附件里仍然残留敏感文件。说句实在话，如果这些内容涉及真正的生产密钥，我对团队的建议是“销毁仓库、重建一个”，因为历史清理工具再可靠，也无法保证第三方在你清理前已经 clone 过这份历史。这个决定听起来有点狠，但比事后补救要稳妥得多。

再提醒一个比较隐蔽的坑：大文件误提交也会让仓库体积膨胀到不可维护的状态。如果你只是误提交了一个构建产物，但还没有推送到远端，本地用git reset撤销暂存并删除文件就够了；如果已经推送了，同样可以走git-filter-repo按路径清理。但最好的策略还是事前用.gitignore拦住，不要给“误提交”留机会。

最后再分享一个小技巧。我管理 Gitee 仓库时，习惯在本地建一套和远端仓库一一对应的目录结构，每个仓库根目录放一个 README，开头三行必须写清楚三个问题：这个项目是干什么的？怎么在本地跑起来？有哪些已知坑？别小看这个习惯，半年之后你回来看某个仓库，会发现它比任何高级配置都省时间。

仓库管理这个东西，本质上是在给团队和组织积累技术资产。密钥、分支、Release、权限，每一步都别留死角；遇到搞不定的报错，先回到权限和同步这两个核心上排查，绝大多数坑都在那里。把基础线走顺之后，再慢慢用 Pages、Webhook 这些能力去放大仓库的价值，你手里这个“放代码的地方”就会真正变成项目的发动机。