企业官网建设流程全解析

把本地项目的文件传到 GitHub 或 Gitee 的远程仓库里，这件事看起来简单，实际操作时却卡住过很多人。我刚接触 Git 的那会儿，也天真地以为在网页上拖拽上传就完事，结果项目文件一多、改动一频繁，网页上传完全失控。后来老老实实把 Git 本地推送这套流程跑通了，才觉得这是每个开发者都应该掌握的基本功。这篇文章专门讲怎么用 Git 把本地文件上传到 GitHub 或 Gitee，从最开始的安装配置，到第一次推送成功，再到日常更新和报错排查，一步一步写清楚。适合刚接触版本控制的新手，也适合给临时需要把项目挂到远程仓库的人做个速查。

1. 上传前先想清楚：Git 到底在解决什么问题

1.1 本地仓库和远程仓库的关系

Git 是当前最主流的分布式版本控制工具，而 GitHub 和 Gitee 都是基于 Git 的代码托管平台。两者的关系可以简单理解成：本地仓库是你自己的项目档案室，远程仓库是放档案的公共展示柜。你在本地做的每一次修改，都不会立即出现在远程仓库里，需要先确认改动、生成提交记录，再显式地推送上去。

这个“显式推送”的设计一开始让人很不习惯，但它是版本控制的核心价值所在。因为每次推送之前，你都有机会检查自己改了什么，而不是让所有临时修改一股脑出现在公共仓库里。网页拖拽上传的问题就在于没有中间检查步骤，也几乎没有版本历史，哪次改了什么全靠人工记，简直是自找麻烦。

1.2 为什么推荐用 SSH 连接远程仓库

连接 GitHub 或 Gitee 有两种常见方式：HTTPS 和 SSH。SSH 连接的核心是用密钥对代替账密反复输入，本地生成一对公钥和私钥，私钥留在自己机器上，公钥填到平台的 SSH 配置里。推送代码时，平台通过公钥判断有没有权限。

用 HTTPS 也不是不行，但每次推送往往都要验证身份，有时候还要折腾个人访问令牌，体验比较割裂。SSH 配好之后，日常操作基本上是无感的，推拉代码都畅通。所以我下面的步骤都以 SSH 作为默认方案，如果你想改用 HTTPS，只需要把仓库地址换成 HTTPS 形式，其余流程一样。

2. 上传前的准备：装好 Git，配好身份，生成密钥

2.1 安装 Git：不同系统的偷懒办法

Windows 上最省事的做法是去 Git 官网下载安装包，一路下一步装完。安装完之后，开始菜单里会出现 Git Bash，这就是一个类似 Linux 终端的命令行环境，后续命令都推荐在这里执行，因为路径处理和命令风格都更贴近实际开发环境。

macOS 用户可以直接用 Homebrew 安装，一条命令就能搞定：

brew install git

Linux 用户根据系统发行版选择包管理器就好，以 Debian/Ubuntu 为例：

sudo apt update sudo apt install git -y

装完先确认一下版本，至于版本形态，能用就行，不需要追求最新：

git --version

提示：Windows 安装时如果遇到要选择“默认编辑器”“PATH 环境”的选项，保持默认即可，不用过度纠结。

2.2 给 Git 设置一个身份签名

Git 的每一次提交都会记录作者信息，也就是 user.name 和 user.email。这两个配置直接影响远程仓库中提交记录的展示效果，建议第一次使用就配好：

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

加上--global表示这台机器上的所有 Git 仓库默认使用同一身份。如果你的公司和个人项目想分开身份，可以进入某个项目目录后不加--global单独配置，比如：

git config user.name "项目专用名字" git config user.email "项目专用邮箱"

很多新手漏了这一步，提交代码后发现远程仓库显示“无名之辈”，或者提交信息里的邮箱不对，看着非常难受。所以开局就把身份信息钉死，后面会省掉一堆麻烦。

2.3 生成 SSH 密钥并添加到 GitHub 或 Gitee

生成密钥的命令如下，建议用 ed25519 算法，比传统的 RSA 更短更安全：

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

命令执行后会问保存路径和口令，直接一路回车就能生成在~/.ssh/id_ed25519和~/.ssh/id_ed25519.pub两个文件里。.pub后缀的是公钥，可以随便给别人看；不带后缀的那个私钥要当作密码一样保护，绝对不能泄露。

查看公钥内容：

cat ~/.ssh/id_ed25519.pub

把输出的整串内容复制下来，登录 GitHub 后进入 Settings，找到 SSH and GPG keys，点 New SSH key，把内容粘贴进去保存。Gitee 也是类似路径，在设置里的安全设置里找到 SSH 公钥，粘贴保存。

验证一下是否配置成功：

ssh -T git@github.com ssh -T git@gitee.com

成功的话会返回类似“身份已验证”的提示。我第一次配的时候在这里卡了很久，后来发现是放公钥时把整个文件都粘贴进去了，平台只认那串以ssh-ed25519开头的内容，多一个字符都不行。

3. 在 GitHub 或 Gitee 上建立一个空仓库

3.1 GitHub 新建仓库的关键细节

以 GitHub 为例，登录后点击 New repository，填写仓库名称、选择公开或私有，然后直接创建。这里有一个特别容易踩的坑：如果你本地已经有项目要推上去，创建时不要把 README、.gitignore、License 这些初始化选项勾上。一旦远程仓库里有这些初始化文件，本地仓库和远程仓库就会是两个互不相识的历史，后面推送时会直接报错，还得多绕一段合并的路。

既然要配合本地推送，最干净的做法是创建一个什么都不带的空仓库。创建完成后的页面会显示一个仓库地址，可能是 HTTPS 形式也可能是 SSH 形式，记得点击按钮切换到 SSH 选项卡，复制那个以git@github.com开头的地址。

3.2 Gitee 新建仓库的注意事项

Gitee 的流程基本一致，登录后点“新建仓库”，填仓库名称，选择开源或私有。同理，如果本地已有项目，“使用 Readme 初始化这个仓库”这个选项不要勾选。

这里额外提醒一句：Gitee 对远程仓库的路径和地址风格跟 GitHub 略有差异，但 SSH 协议的核心逻辑一样。创建完成后，仓库页面同样有 SSH 地址，格式是git@gitee.com:用户名/仓库名.git。复制备用就好。

3.3 仓库地址的两种写法对比

仓库地址很容易混淆，我放一张速查表，方便对照：

SSH 形式适合配好密钥后长期使用，推送更顺滑。HTTPS 形式适合临时访问或者不想搞密钥的场景，但推送时会被要求验证身份，记住这点就够了。

4. 本地从零初始化：一条龙推上远程仓库

4.1 进入项目目录，执行 git init

打开终端，进入你的项目目录。如果不知道目录在哪，可以先切到对应路径，再执行：

git init

这条命令会在当前目录下生成一个隐藏的.git文件夹，它记录着这个项目的所有版本信息。把它理解成仓库登记处，以后所有版本操作都由它一手打理。

执行完先看一眼状态：

git status

此时目录里所有文件都会以未跟踪的形式出现，也就是 Git 还不认识它们。这很正常，毕竟刚刚登记，还没有谁被正式纳入管理。

4.2 把文件加入暂存区并生成第一个提交

Git 的工作流程里有一个非常重要的概念叫暂存区。它的作用相当于“待发货仓库”：你从工作区挑出本次要提交的文件，放进暂存区，检查没问题后再一次性打包发出。这不是多此一举，而是给开发者一个二次确认的机会，避免把临时日志、调试文件、缓存一股脑提交进去。

加入全部文件的命令：

git add .

分开添加某个文件或目录：

git add src/readme.md git add config/app.conf

添加之后再看看状态，确认暂存区里的内容符合预期，然后提交：

git commit -m "feat: 初始化项目结构"

这里-m后面的内容是提交说明，建议写清楚这次提交做了什么。以 “feat” 开头表示新功能，以 “fix” 开头表示修复问题，这种习惯会让后续回溯历史时省很大力气。

如果此时系统提示需要先配置 user.name 和 user.email，说明第一步的身份配置漏掉了，补上之后重新提交即可。

4.3 关联远程仓库并推送

现在把本地仓库和远程仓库连接起来，这一步是很多新手理解上的分水岭。所谓关联，就是在本地仓库里记一条“远程地址”的别名，默认的别名是 origin：

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

如果用的是 Gitee，就把地址替换成对应的 SSH 地址。关联之后可以查看一下：

git remote -v

看到两条记录，分别对应 fetch 和 push 使用的地址，说明关联成功。

接下来把当前分支改名为 main。Git 新仓库默认分支什么名字都行，GitHub 平台现在默认叫 main，为了保持一致，本地也统一叫 main：

git branch -M main

然后推送：

git push -u origin main

-u表示把本地的 main 分支和远程仓库的 main 分支绑定起来，以后直接在项目目录执行git push就能默认推到这。推送完成后刷新远程仓库页面，本地文件应该已经整整齐齐地出现在那里了。

注意：第一次推送如果报错提示“remote origin already exists”，说明这个目录之前已经关联过别的远程地址，可以用git remote -v先看，再用git remote set-url origin 新地址改掉。

5. 以后每次更新：从 commit 到 push 的完整节奏

5.1 日常三连：add、commit、push

项目推上去之后，并不是就完事了。后面每次改动代码，都会持续走一遍固定的三道工序：

git add . git commit -m "feat: 新增登录页面" git push

第一道工序是把改动放进暂存区，第二道工序是生成一条本地提交记录，第三道工序是把本地提交推到远程。这三步对应前面讲的“工作区、暂存区、本地仓库、远程仓库”的数据流动。

这里要特别强调一下：git add .虽然省事，但在大项目里等于闭着眼睛上货。更好的习惯是用git status先看，然后单独添加本次相关的文件，至少确认没有把.env、密钥文件、临时产物提交上去。提交前再花十秒看下改动内容：

git diff

看到的是尚未暂存的改动，确认没问题后再 add，是成本最低的保险。

5.2 push 被远端顶住的时候：先 pull 再看冲突

多人协作或者你在网页上直接改动过文件后，本地执行git push有可能会被拒绝。报错信息往往写着“failed to push some refs”或者“远程仓库包含本地没有的提交”。这种情况硬推是推不动的，正确的做法是先把远程的改动拉下来合并。

最简单的处理方式是用 rebase 让本地提交叠加在远程提交后面，保持历史更线性：

git pull origin main --rebase

如果本地和远程改的是同一个地方，Git 会提示冲突。此时打开冲突文件，里面会有标记示意两边内容的分界，手动整理成最终想要的版本，然后执行：

git add 冲突文件 git rebase --continue

没有冲突则不需要额外操作，直接再推一次：

git push

这种“先拉后推”的习惯应该刻进肌肉记忆里。别一看到拒绝就想着git push -f强制推送，强制推送会覆盖远程历史，在共享分支上这样做，等于自毁长城。

5.3 一个仓库同时推到 GitHub 和 Gitee

不少人有这样的需求：本地代码既想放 GitHub，又想放 Gitee，方便国内访问。操作方法并不复杂，核心是利用 Git 可以配置多个远程地址的特性，把两个平台分别当作不同的远程名来管理。

首先添加两个远程：

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

注意这里我没有用默认的 origin，而是用了 github 和 gitee 两个名字，这样一眼就能辨认对面是谁。之后推送时就分别执行：

git push github main git push gitee main

如果希望第一次就绑定上游，可以写成：

git push -u github main git push -u gitee main

需要移除某个远程时，用git remote remove github即可。这种双远端方案特别适合把 GitHub 作为主仓库、Gitee 作为国内镜像的场景，配置一次之后，推两遍也不算麻烦。

6. 高频报错与排查技巧实录

6.1 提示 Permission denied (publickey)

看到这个报错，说明 SSH 密钥没有被远程平台识别。先按顺序排查：密钥是否生成、公钥是否完整粘贴、平台是否保存成功、当前机器是否确实在使用这把私钥。必要时用ssh -T git@github.com手动测试，成功的输出里会带上你的用户名，这能直接确认问题出在哪。

还有一种情况是私钥不在默认路径，导致客户端没找到。可以用ssh-add手动添加，或者检查是不是因为这个平台配置了多个密钥，需要指定~/.ssh/config里的 Host 规则。不过新手阶段，最可能的问题还是公钥粘贴不完整或者复制到了私钥。

6.2 推送时报 fatal: repository not found

仓库地址错误，或者权限不够。检查地址里的用户名、仓库名是不是完全正确，注意大小写。如果仓库是私有的，确认当前 SSH 密钥是不是有权限访问。还有一种细节很容易忽略：地址里的用户名是平台账号名，不是仓库名。

6.3 单个文件太大推不上去

GitHub 和 Gitee 对单文件体积都有硬限制，超出之后推送会直接拒绝。遇到这种情况，先确认是不是误把二进制大文件放进仓库，比如压缩包、模型文件、数据库文件。解决办法是先用工具确认大文件路径，把它们移出版本控制，再考虑要不要用 Git LFS 这类专门方案管理大文件。

如果一个大文件已经被提交进历史记录，单纯删除当前版本还不够，需要重写历史才能彻底移除，这个过程对新手并不友好，所以最好的策略是在项目一开始就写一个靠谱的.gitignore，把不需要进仓库的文件提前挡在门外。

6.4 换行符问题：CRLF 和 LF 的经典内战

Windows 默认用回车加换行表示分行，Linux 和 macOS 则只用换行。跨平台协作时，Git 经常会提示“LF will be replaced by CRLF”这类信息。最稳妥的办法是 Windows 上开启自动转换：

git config --global core.autocrlf true

macOS 和 Linux 上则设置成：

git config --global core.autocrlf input

这样提交到仓库的统一是 LF 格式，本地检出时 Windows 自动转回 CRLF，两边都不受罪。另外，如果遇到中文文件名显示为转义字符，可以打开一个开关：

git config --global core.quotepath false

之后中文文件名就不会再变成一串八进制数字了。

6.5 常见错误速查表

7. 我每次都会注意的几个使用习惯

写到这里，基础的上传流程已经覆盖得比较完整了。再分享几个我实际操作中慢慢养成的习惯，算是在踩过坑之后沉淀下来的经验。

提交信息不要写“update”这种废话。哪怕只是改了三个字，也要说明改了什么，比如“fix: 修复列表加载空数据时页面崩溃”。以后回看日志时，这种信息能让你节省大量回忆成本。

推送之前养成看 diff 的习惯。git diff不只看内容，更要看成份，尤其要确认有没有密钥、密码、token 这类敏感信息混进去。一旦把密钥推到公开仓库，第一时间危险，第二时间就要立刻去平台撤销并重新生成，安全意识和流程习惯同样重要。

给稳定的版本打标签。代码不只是往 main 分支上推，还可以在重要节点用标签标记版本，比如：

git tag v1.0.0 git push origin v1.0.0

标签在远程仓库里会以一个清晰的版本号出现，比靠人脑记住“第几次提交”靠谱得多。

最后再说一个小技巧：新机器上我会把常用命令配成别名，减少重复敲长命令的时间。比如：

git config --global alias.lg "log --oneline --decorate --graph" git config --global alias.st status

配置之后，一个git lg就能看到清晰的提交历史拓扑，git st就能快速查看状态。别小看这些小别名，日积月累下来的效率提升很明显。

把本地文件上传到 GitHub 或 Gitee，本质上就是搭好一条从工作区到远程仓库的流水线。第一次配置 SSH、建库、推送可能会花一点时间，但配好之后，后面每次提交和推送都只是几十秒的事。先用这套基础流程跑顺，再慢慢接触分支、标签、变基这些进阶操作，你会发现 Git 越用越顺手。