企业官网建设流程全解析

很多人代码写完了，第一反应就是“传到 Gitee 上备份一份”。结果打开终端敲下git push，迎面而来的是一堆红字报错——git 没装好、身份没有配置、SSH key 不匹配、分支推送被拒绝……然后就开始在搜索引擎里一条一条翻解决办法，折腾一下午，仓库还是空的。

我见过太多这种场景了。Gitee 作为国内使用频率最高的 Git 代码托管平台，本身上传链路并不复杂，从本地仓库到远程仓库，核心就init、add、commit、remote、push五个动作，但每一步都有各自的隐藏条件：环境变量没配好、密钥没生成、仓库权限没开、分支名不一致，任何一个环节出问题，都会把整个流程卡死。

这篇指南就是写给“想把本地代码快速推到 Gitee”的人。我会从 Git 安装开始，一路讲到仓库创建、SSH 配置、首次推送，再把手边高频踩过的报错按链路梳理一遍，最后补充 VSCode 可视化和 .gitignore、冲突处理这类日常必用配置。不管你是刚接触 Git 的新手，还是已经被报错折磨过几轮的半熟手，照着这篇走一遍，大概率能一次跑通。

1. 先把“推送到Gitee”这条链路拆明白：本地仓库和远程仓库是怎么连上的

很多人一上来就敲命令，敲完报错也不知道错在哪，根本原因是对 Git 的模型没有一个整体认识。其实 Git 的日常操作就围绕四个区域转：工作区、暂存区、本地仓库、远程仓库。理解这四者的关系，后面所有命令都是在“搬运数据”。

1.1 本地仓库的本质是什么

你执行git init之后，项目目录里会多出一个隐藏的.git文件夹。这个.git就是本地仓库本身，它里面装着所有提交历史、分支指针、配置信息，相当于项目的“完整账本”。你看到的源代码文件只是“工作区”，随时可改、可删；而.git里记录的才是每一个历史版本的快照。

理解这一点非常关键。很多人以为“本地仓库”就是自己的项目文件夹，其实严格说，项目文件夹加上.git才算一个完整的 Git 仓库。如果你误删了.git，那所有提交历史、分支记录会全部丢失，项目源文件还在，但 Git 会认为这是一个全新的、从未被版本控制的目录——这也是“本地项目不小心把 .git 文件删除了怎么重新绑定 Gitee”这类问题频繁出现的原因。

1.2 五个核心命令对应的传输阶段

一次完整的推送，实际上是数据在四个区域间的依次流转：

这个顺序是固定的，跳步一定会报错。比如你还没git init就直接git push，Git 会告诉你这不是一个仓库；你add之后忘了commit就push，推上去的是空气。

1.3 HTTPS 和 SSH：两条到达 Gitee 的路

Gitee 每个仓库都会给你两种远程地址：HTTPS 和 SSH。很多人第一次看到两个地址就懵了，其实它们的区别只在“身份验证方式”。

• HTTPS 方式：每次推送时用 Gitee 账号密码（或私人令牌）验证身份。好处是配置简单，坏处是频繁推送会被反复要求输入凭证。
• SSH 方式：先在本地生成一对密钥（公钥和私钥），把公钥告诉 Gitee，之后推送时 Git 通过密钥自动完成身份验证，一劳永逸，不用再输密码。

我的建议很简单：别犹豫，直接走 SSH。虽然生成密钥乍一看多了一步，但这一步做完，后续所有仓库都能免密推送，划算得很。后面第 4 节我会给出完整的配置流程。

2. 环境准备阶段就劝退了一半人：Git安装与身份配置的细节点

工具还没用上，人先卡在安装阶段，这在我接触的初学者里比例非常高。Git 装不好有两种典型症状：一是终端输入git --version提示“无法识别”，二是不管敲什么 Git 命令都闪退或找不到路径。这两个问题的根源其实都在安装环节的某一个选项上。

2.1 Windows 上正确安装 Git

Git 官方下载地址是 git-scm.com，下载 Windows 版本后一路 Next 安装，但中间有几个界面要注意。

最关键的界面是“Adjusting your PATH environment”，这里有三个选项：

• “Use Git from Git Bash only”：Git 只能在 Git Bash 窗口里用，CMD 和 PowerShell 里识别不到 git 命令。
• “Git from the command line and also from 3rd-party software”（推荐）：把 Git 加入系统 PATH，CMD、PowerShell、VSCode 终端都能直接用。
• “Use Git and optional Unix tools from the Command Prompt”：会覆盖系统自带的 Windows 工具，不推荐，可能有副作用。

我建议新手直接选第二项，这是默认推荐选项，也是最省心的。安装完成后重新打开一个终端，输入git --version，能输出版本号就说明环境正常。

还有一个安装细节：行结束符处理界面（“Line Ending Conversions”）建议保持默认的 “Checkout Windows-style, commit Unix-style line endings”，这是绝大多数项目的标准配置，不要乱改，否则文件换行符会出各种诡异问题。

2.2 “无法将‘git’项识别为 cmdlet”的根因和修复

这是 Windows 上最经典的一个报错，完整提示是：

git : 无法将“git”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。请检查名称的拼写， 如果包括路径，请确保路径正确，然后再试一次。

一句话解释：系统在 PATH 环境变量里找不到 git.exe，所以不知道你敲的git是什么。

修复方式有两种。第一种最省事：重新运行 Git 安装包，选择 Modify，把 PATH 选项改成第二项“Git from the command line...”，完成修复后重新打开终端。第二种是手动修改环境变量：把 Git 的安装路径（默认是C:\Program Files\Git\cmd）添加到系统 PATH 里，然后重启终端。

这里有个很容易被忽略的点：修改完 PATH 后，已经打开着的终端窗口不会自动生效，必须重新开一个新的终端窗口。很多人改完环境变量发现还是报错，就是这个原因。

2.3 提交者的身份信息，必须在第一次 commit 前配好

Git 的每次提交都会记录作者和邮箱，这个信息就写在提交记录里，Gitee 上也会显示出来。如果不配，Git 会用一串随机生成的主机名当作者名，提交记录会变成一团乱麻，而且 Gitee 也没法把提交关联到你的账号上。

配置命令很简单：

git config --global user.name "你的昵称" git config --global user.email "你的邮箱"

--global表示全局生效，配一次，这台电脑上所有仓库都用这套身份。如果你想给某个特定仓库单独设身份，去掉--global再执行一遍即可。

配置完成后可以执行git config --list查看当前所有配置，确认信息无误再开始提交。

3. 在Gitee上建仓库：许可证选择、初始化选项和仓库地址的前因后果

本地代码准备好了，接下来去 Gitee 网站创建远程仓库。这一步虽然是在网页上点几下，但选项并不少，而且每一个选择都会影响你后面的操作。新手容易在这一步因为“开源许可证选什么”这种问题卡住，实际上没那么复杂。

3.1 页面参数到底怎么填

登录 Gitee 后，点击右上角的加号，选择“新建仓库”，会进入仓库信息填写页面：

• 仓库名称：必填，比如my-blog、note-taking-app。这是显示名，也会作为仓库路径的一部分。
• 路径：实际上就是仓库 URL 里的那段英文标识。默认会和仓库名一致，也可以单独改。
• 开源/私有：个人项目和未完成的代码建议选私有；想公开分享、让别人克隆你的项目，选开源。
• 初始化仓库：可以勾选“使用 Readme 文件初始化这个仓库”“选择 .gitignore”“选择开源许可证”。
• 分支模型：选择默认分支，常见的是master或main，现在新仓库默认master的比较多，后面 push 时要和这里保持一致。

有一个小建议：如果本地已经有一个写了很多代码的目录，尽量不要勾选“使用 Readme 初始化”选项。因为远程一旦初始化了 README，它就有了一个本地没有的提交，你第一次 push 本地代码时就会遇到“failed to push some refs”的经典报错，还得额外处理历史合并。远程仓库保持完全空的状态，是让首次推送最顺利的做法。

3.2 开源许可证：不是随便选一个就行

仓库创建页有“选择开源许可证”的下拉框，常见的有 MIT、Apache-2.0、GPL-3.0、BSD 等。很多人随便选一个完事，但许可证本质上是法律声明，选错了会影响别人能不能自由使用你的代码。

这里用三句话帮大家快速判断：

• MIT：最宽松。别人拿到你的代码，修改、商用、闭源都行，只要保留你的版权声明。个人开源项目和工具类代码选它最省事。
• Apache-2.0：也很宽松，和 MIT 类似，但额外包含专利授权条款，企业项目更偏爱。
• GPL-3.0：强传染性。别人用了你的代码，那他的衍生作品也必须开源。适合希望代码“永远开源”的场景。

如果你的仓库只是自己用，或者还没想好要不要开源，可以选“不使用许可证”。对于绝大多数个人初学者，我建议选 MIT，它简单、友好、限制最少。

3.3 仓库地址的两种形态

仓库创建完成后，页面会展示地址信息，通常形如：

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

.git后缀表示这是一个 Git 仓库地址。两个地址指向同一个远程仓库，只是访问协议不同。前面我说过建议用 SSH，那就需要提前把公钥配置到 Gitee 上，也就是下面这一节的内容。

4. 首次推送实战：SSH免密配置与完整命令走通

到这里，前置工作都完成了，开始真正动手。我按实际操作的顺序一步步来，每步都会说明为什么这样做。

4.1 生成 SSH 密钥并添加到 Gitee

打开 Git Bash（Windows 下建议用这个终端，兼容性最好），执行：

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

全程会问几个问题，可以一路回车。关于是否设置 passphrase（密钥口令），可以自由选择：设置了，每次使用密钥时要额外输一次口令，安全性高一些；不设置，纯免密，适合个人电脑。如果中途想退出重新设置，Ctrl+C即可。

生成完成后，在终端执行：

cat ~/.ssh/id_rsa.pub

屏幕上会输出一串以ssh-rsa开头的长文本，这就是公钥。全选复制。

然后打开 Gitee 网页：右上角头像 → 设置 → 安全设置 → SSH 公钥 → 添加公钥。把复制的内容粘贴到公钥框里，标题随便填，比如“我的Windows电脑”，保存。

验证是否生效，回到终端执行：

ssh -T git@gitee.com

如果看到类似 “Hi 用户名! You've successfully authenticated...” 的提示，说明公钥配置成功。这一步的输出因人而异，核心是看到successfully authenticated这类字样，没看到 Permission denied 就行。

4.2 本地目录从零推到 Gitee 的完整命令

假设你的项目在D:\projects\my-app，打开 Git Bash 进入该目录，依序执行：

cd /d/projects/my-app git init git add . git commit -m "init: 首次提交" git branch -M master git remote add origin git@gitee.com:你的用户名/仓库名.git git push -u origin master

逐条说明一下意图：

• git init：把这个目录变成 Git 仓库，生成.git。
• git add .：把当前目录下所有文件加入暂存区。注意点号代表“当前目录”，如果只想加某个文件，改成具体文件名。
• git commit -m "init: 首次提交"：生成第一个本地提交。
• git branch -M master：如果当前分支名不是master，强制改成master，保证和 Gitee 仓库默认分支一致。如果 Gitee 仓库默认分支是main，这里就改成main。
• git remote add origin ...：给远程仓库起名origin，这是 Git 社区约定俗成的名字，用remote -v可以查看。
• git push -u origin master：把本地master分支推到远程origin。-u参数会把本地分支和远程分支关联起来，之后在这个分支上只需要git push，不用再带参数。

第一次 push 如果一切顺利，终端会输出一串进度信息，最后提示分支已成功推送。打开 Gitee 仓库页面，代码就在那里了。

4.3 常见的 origin 冲突问题

有些读者可能之前已经试过git remote add origin，但当时用的地址不对，第二次想重新添加，却收到提示：

fatal: remote origin already exists.

意思是origin这个名字已经被占用了。解决办法不是重新add，而是先查看当前远程地址：

git remote -v

如果发现有误，可以修改：

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

或者干脆删掉重新加：

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

这里要记住一个思路：remote add只负责把“远程地址”和“本地别名”绑定，它不会去检查地址通不通、仓库真实存在，真正的连通验证发生在git push的时候。

5. 推送失败才是常态：高频报错全链路排查手册

上面讲的顺畅流程，能一次走通最好。但真实世界里，推送失败的几率比成功高得多。我把自己见到的、被问到最多的四类报错整理成排查链路，每一类给到直接可用的处理方案。

5.1 fatal: not a git repository：小事但最常发生

完整报错：

fatal: not a git repository (or any of the parent directories): .git

这条报错的含义是：当前目录以及它的上层目录里都找不到.git文件夹。通常有两种触发原因。

第一种，你压根没有git init。解决方式是先执行git init，再继续后续操作。

第二种，你在错误的目录下执行命令。比如你已经在D:\projects\my-app里git init过，但终端当前停留的目录是D:\projects或别的路径，Git 找不到.git，自然报这个错。用pwd确认当前目录，用ls -a看看目录下有没有.git文件夹。

还有第三种特殊情况：你以前初始化过，但后来把.git目录误删了。这种情况等于本地仓库历史全部丢失，源文件还在，但 Git 已经“失忆”了。处理办法只能重新git init、重新git add .、重新git commit，以前的提交记录无法恢复。如果之前的代码在 Gitee 上还有一份完整备份，那就直接git clone拉下来继续开发，不要再对本地这个“残缺仓库”做无谓抢救。

5.2 权限类报错：SSH 公钥和 HTTPS 凭证的路子都在这

SSH 方式最典型的报错是：

git@gitee.com: Permission denied (publickey).

排查路径按顺序走：

1. 确认你的远程地址是不是 SSH 形式。git remote -v看输出，如果地址是https://开头，那你走的根本不是 SSH 通道。
2. 检查公钥是否真的加到了 Gitee。用ssh -T git@gitee.com验证，如果还是 permission denied，说明公钥没有生效。
3. 检查公钥文件和目录权限。Windows 下公钥一般在C:\Users\你的用户名\.ssh\，确认id_rsa.pub存在。
4. 如果你重装过系统、重新生成过密钥，但 Gitee 上还留着旧的公钥记录，也会验证失败。删掉旧的，重新添加新的。

HTTPS 方式对应的报错通常是：

remote: Login failed, please check your account and password.

这种一般是账号密码错了，或者 Gitee 账号开启了二次验证、需要改用私人令牌。对策是去 Gitee 设置里生成一个私人令牌（Personal Access Token），把令牌作为密码输入。另外，如果你看到类似 “check api token or gitlab version” 这种提示，通常是 IDE 或第三方工具在连接自建 GitLab 时出现的鉴权问题，思路也一样：确认 token 是否有效、权限是否足够、远端版本是否兼容。

5.3 failed to push some refs：远程和本地历史分叉了

报错完整形态：

! [rejected] master -> master (fetch first) error: failed to push some refs to 'git@gitee.com:用户名/仓库名.git' hint: Updates were rejected because the remote contains work that you do hint: not have locally.

这句话翻译过来：远程仓库有你本地没有的提交。最常见的原因是远程仓库勾选了 README 初始化，或者你在网页端直接改过文件，导致远程多了一个提交。

处理方式分两种。如果远程那份“额外提交”是你不需要的，比如只是自动生成的 README，而你想让本地代码完全覆盖远程：

git push -f origin master

-f是强制推送，会直接覆盖远程历史。这个操作要谨慎，如果仓库里已经有别人提交的代码，强推会丢掉别人的成果。只有确定远程的提交可以被舍弃时才建议这样做。

如果远程的提交是有用的（比如别人也提交了代码，或你自己改过 README），那就先把远程内容拉到本地再推：

git pull origin master git push

如果 pull 时遇到：

fatal: refusing to merge unrelated histories

说明本地和远程的提交历史完全没关系（比如一边是git init新建的，一边是网页初始化的）。这时加上--allow-unrelated-histories：

git pull origin master --allow-unrelated-histories

合并后再git push，就能成功了。

5.4 推送频繁要求输入账号密码：一条命令解决

HTTPS 方式下，Git 每次推送都可能要求输入账号密码，很多人被烦得不行。Windows 上可以通过凭据管理器缓存凭证：

git config --global credential.helper manager

Git for Windows 默认会启用 Git Credential Manager，第一次输入过的账号密码会被安全保存，后续不需要重复输入。如果这个方式在你的环境里不生效，终极解决办法还是切换到 SSH 方式的远程地址，彻底告别密码。

6. VSCode操作Gitee：可视化面板的效率和那些“覆盖本地”的坑

熟悉命令行固然重要，但日常开发中，大量操作其实都在 VSCode 里完成。VSCode 内置了 Git 支持，界面化操作对新手非常友好，但要知道它的边界——很多骚操作它做不了，最终还是得回到命令行。

6.1 内置源码管理面板怎么用

VSCode 左侧活动栏有一个分支图标，点开就是“源代码管理”面板。这里会实时显示工作区的文件变动：

• 每个修改过的文件都在“更改”列表里，右侧有加号，点击相当于执行git add。
• 顶部的输入框是提交信息，写完后点“提交”按钮，相当于git commit -m "..."。
• 提交完成后，点“同步更改”或“推送”按钮，相当于git push。

这个过程基本覆盖了日常 80% 的需求：改代码、看 diff、提交、推送。我在 VSCode 里看文件差异（diff）比命令行直观得多，修改前踌躇不决时，先点开 diff 看一眼再决定要不要提交，这个习惯能帮你减少很多误提交。

VSCode 配置 Gitee 本质上不需要额外插件——它直接调用系统安装的 Git。只要系统 Git 身份配置好了、SSH 密钥生效了，VSCode 里的提交推送就一路畅通。首次打开已有 Git 仓库的文件夹时，VSCode 会自动识别，直接就能在面板里看到状态。

6.2 拉取远程代码“覆盖本地”：先 fetch 再 reset

有一个高频搜索词是“vscode 拉取 gitee 项目覆盖本地项目”。这个需求通常出现在：远程仓库的代码比本地新，而本地已经被改得一团糟，你想直接舍弃本地改动、让本地完全变成远程的样子。

注意，直接“拉取”（pull）做不到彻底覆盖——如果本地有未提交的修改，pull 会触发冲突或拒绝执行。正确的姿势是两条命令：

git fetch origin git reset --hard origin/master

git fetch会把远程的提交下载到本地一个叫origin/master的引用里，但不改动你当前的工作区；git reset --hard origin/master会把当前分支指针强制移到远程的提交位置，同时清空工作区和暂存区里所有本地改动，让本地和远程完全一致。

这里必须强调：reset --hard会丢弃所有未提交的本地修改，且不可恢复。执行前请确认你不需要本地任何未提交的内容了。如果你只是想“看看远程代码”，不想动本地，用git fetch后直接查看origin/master分支的内容就好，别急着 reset。

6.3 从 Gitee 克隆项目和常用插件

git clone是获取远端代码的标准方式：

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

克隆下来的目录自带完整.git历史，直接用 VSCode 打开就能开始开发。相比“手动下载 ZIP 再解压”，克隆最大的优势是保留了 Git 历史，后续可以直接在本地提交和推送。

至于插件，我觉得最值得装的是 GitLens。它能在代码行上直接显示这一行是谁在什么时候写的、提交信息是什么，对复盘代码演进和理解他人项目帮助极大。另一个是 Git Graph，可视化展示分支和提交关系，特别适合学习 Git 原理阶段使用。

7. 后续过日子必备：.gitignore、冲突解决与提交规范

上传成功只是开始，真正让 Git 成为生产力工具的是日常的习惯和细节。这一节把几个最重要的基本功讲透，都是实际项目中会用到的。

7.1 .gitignore 到底该写什么

如果你的项目里有node_modules、编译产物、IDE 配置文件，不加 .gitignore 就直接git add .，这些垃圾文件会被一并提交上去。特别是 Node.js 项目的node_modules动辄几百 MB，提交上去不仅仓库巨大膨胀，别人克隆下来还满屏冲突。

一个基础的 .gitignore 模板可以这样写：

# 依赖目录 node_modules/ vendor/ # 构建输出 dist/ build/ target/ out/ # 日志和临时文件 *.log *.tmp # IDE 和系统文件 .idea/ .vscode/ .DS_Store # Python 缓存 __pycache__/ *.pyc # 环境变量与密钥 .env

Gitee 仓库创建页面也提供了 .gitignore 模板，会按照你选择的语言自动生成一份匹配的忽略规则，如果你在创建时勾选了，本地就不用自己写太多。

这里有个常见的坑：.gitignore 只对“尚未被跟踪”的文件生效。如果某个文件已经被git add或git commit过了，你再往 .gitignore 里加它也没用——Git 会继续跟踪它。想把它从跟踪状态移除但保留本地文件，需要：

git rm --cached 文件名

然后在 .gitignore 里加上对应规则，提交一次，后续就不会再误上传这个文件了。

7.2 冲突处理：不要怕，按规则来

pull 或 merge 时遇到冲突，Git 会在冲突文件里插入特殊的标记：

<<<<<<< HEAD 这里的代码是当前分支（本地）的版本 ======= 这里的代码是传入分支（远程）的版本 >>>>>>> origin/master

<<<<<<<到=======之间是本地版本，=======到>>>>>>>之间是远程版本。你的任务是决定保留哪边，或者融合两边，然后把这三行标记全部删除，保存文件，再执行：

git add 冲突文件 git commit -m "解决冲突"

搞定。冲突不是灾难，它只是 Git 在告诉你：两个分支对同一处代码有不同意见，需要人来做决定。使用 VSCode 解决冲突时，编辑器会提供“采用当前更改”“采用传入更改”等按钮，点击后自动帮你处理标记，比命令行下肉眼操作省力很多。

处理冲突最核心的注意点就一句：永远不要在没理解冲突双方意图的情况下强行选一边。所谓“冲突”，很可能是两段代码在逻辑上互相依赖，只看语法看不出问题，盲选你当时看着顺眼的那版，合并完一运行就崩，这才是真正的坑。

7.3 提交规范：让历史可读

提交信息写得乱七八糟，三个月后回看，git log输出的全是“fix”“update”“111”这种无意义信息，谁也看不懂项目经历了什么。我现在用的提交习惯是：

• 一次提交只做一件事，粒度越小越容易回溯和回退。
• 提交信息用“类型前缀 + 简短描述”格式，比如feat: 增加用户登录接口、fix: 修复首页白屏问题、docs: 更新README。
• 提交前先git status和git diff，确认没提交不该提交的文件。

日常可以用git log --oneline快速查看提交历史，一屏一行的紧凑展示，非常直观。如果发现最近一次提交信息写错了，用git commit --amend -m "新的信息"可以修正，但要记住这只能在你还没有 push 的情况下使用。

还有个安全提示：不要把.git目录暴露在可以被公网访问的静态文件服务里。有些人搭了网站，结果服务器把整个项目目录当静态资源根目录，http://域名/.git/能被直接访问，那就等于把源码全部泄露了。所以部署时一定要把.git目录挡在 Web 可访问范围之外，这是很多人忽略的隐患。

最后分享一点个人体会：第一次跑通从本地到 Gitee 的推送之后，一定要顺手做一遍“从 Gitee 克隆到另一个目录”的反向操作，用 clone 下来的仓库做一次正常的修改、提交、推送。这样正反两个方向都走通，你对 Git 的本地和远程协作模型就彻底建立了直觉，以后再遇到什么“fatal”开头的报错，第一反应就不会是慌，而是看一眼信息，顺着链路去定位问题。项目初期多用几次git status和git remote -v，这两个命令会是你最忠实的排障伙伴。