企业官网建设流程全解析

GitHub 新建仓库这件事，看起来只是点几下按钮，但我见过太多人卡在第一步：仓库建完了，本地代码推不上去；或者推上去了，README 却是空的；又或者密钥配了半天，每次 push 还要输密码。这篇内容就是把这些坑一次性讲清楚，从账号准备到仓库初始化，再到 SSH 密钥配置和首次推送，每一步都说明白为什么这么做、不这么做会怎样。不管你是刚接触版本控制的新手，还是用过 Git 但一直没搞懂远程仓库逻辑的开发者，都能照着走一遍。

1. 建仓库之前先想清楚的三件事

1.1 仓库名不是随便起的

很多人新建仓库时随手打个test、demo、newproject，过两个月自己都忘了里面装的是什么。仓库名在 GitHub 上会成为 URL 的一部分，比如github.com/你的用户名/仓库名，它同时也是别人搜索你项目时第一眼看到的信息。我的习惯是：仓库名用小写字母加连字符，能表达项目用途，比如blog-source、cli-tools、># 进入项目目录 cd /path/to/your-project # 初始化本地仓库 git init # 添加所有文件到暂存区 git add . # 提交 git commit -m "initial commit" # 关联远程仓库 git remote add origin git@github.com:用户名/仓库名.git # 推送并设置上游分支 git push -u origin main

这里有几个细节值得展开。git init会在当前目录创建一个.git隐藏文件夹，所有版本控制信息都在里面。git add .会把当前目录下所有文件加入暂存区，但如果你的项目里有node_modules、__pycache__这类不需要版本控制的文件夹，最好先创建.gitignore文件把它们排除掉，否则第一次提交会非常大。

git push -u origin main里的-u是--set-upstream的简写，它的作用是把本地main分支和远程origin/main关联起来。设置之后，以后直接git push和git pull就会默认操作这个分支，不用每次指定。这个参数新手经常忘，结果每次推送都要写完整命令。

3.2 远程已有初始提交，本地也有项目

如果你在创建仓库时勾了 README，远程就有一个初始 commit。这时候本地项目直接推送会报错：

! [rejected] main -> main (fetch first) error: failed to push some refs to '...'

原因是两边的提交历史没有共同祖先。解决办法有两种：

第一种是先拉取远程内容并允许合并不相关的历史：

git pull origin main --allow-unrelated-histories

然后解决可能的冲突，再推送。第二种是直接克隆远程仓库到本地，把你的项目文件复制进去，再提交推送。第二种更干净，适合新手。

我个人的习惯是：如果远程已经有内容，就克隆下来，把本地文件拷进去，而不是在本地 init 再强行合并。这样历史记录更清晰，不会出现两个无关的根提交。

3.3 推送时遇到认证失败怎么办

用 HTTPS 地址推送时，GitHub 从 2021 年起就不再支持密码认证了，必须用 Personal Access Token（PAT）代替密码。如果你输入账号密码后报Authentication failed，就是这个原因。

生成 PAT 的路径是：GitHub 头像 → Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token。勾选repo权限，生成后复制保存，下次推送时用户名填 GitHub 用户名，密码填这个 token。

但说实话，每次推送都要输 token 很麻烦。更好的方案是配置 SSH 密钥，一次配置，长期免密。下面单独讲。

4. SSH 密钥配置：一次配好，长期省事

4.1 SSH 密钥的原理，用一句话说清楚

SSH 密钥是一对文件：私钥和公钥。私钥留在你本地，公钥放到 GitHub 上。推送时，GitHub 用公钥加密一段信息发给你，你的本地用私钥解密后发回去，验证通过就允许操作。整个过程不需要传输密码，所以比 HTTPS 更安全也更方便。

这对密钥可以用ssh-keygen命令生成，也可以用工具生成。命令行方式最通用，各平台都适用。

4.2 生成密钥的完整命令与参数解释

打开终端（Windows 用 Git Bash 或 PowerShell），执行：

ssh-keygen -t ed25519 -C "your_email@example.com"

参数解释：

• -t ed25519：指定密钥类型。Ed25519 是目前推荐的算法，比 RSA 更短、更快、更安全。老教程里常用-t rsa -b 4096，也能用，但新项目建议用 Ed25519。
• -C：添加注释，一般填邮箱，方便你在 GitHub 上识别这把钥匙是谁的。

执行后会提示你输入保存路径，直接回车用默认路径（~/.ssh/id_ed25519）。然后会问你要不要设置密码短语（passphrase），可以留空直接回车，也可以设置一个增加安全性。如果设置了，每次使用密钥时要输入这个短语，可以用ssh-agent缓存。

生成成功后会得到两个文件：id_ed25519（私钥）和id_ed25519.pub（公钥）。私钥绝对不能泄露给任何人，公钥才是放到 GitHub 上的。

4.3 把公钥添加到 GitHub

查看公钥内容：

cat ~/.ssh/id_ed25519.pub

复制输出的全部内容，以ssh-ed25519开头，以邮箱结尾。然后到 GitHub：头像 → Settings → SSH and GPG keys → New SSH key。Title 随便填一个能识别的名字，比如"我的笔记本"，Key 粘贴刚才复制的内容，点 Add SSH key。

添加完成后，在终端测试连接：

ssh -T git@github.com

如果看到Hi 用户名! You've successfully authenticated...就说明配置成功了。第一次连接会问你是否信任 GitHub 的指纹，输入yes回车即可。

4.4 多台设备或多账号的密钥管理

如果你有多台电脑，每台都生成一把密钥，分别添加到 GitHub，这样任何一台丢失或重装，只需删除对应的公钥，不影响其他设备。不要在多台设备之间复制同一把私钥，那样一旦泄露，所有设备都要重新配置。

如果你有多个 GitHub 账号（比如个人号和工作号），可以在~/.ssh/config文件里配置不同的 Host：

Host github-personal HostName github.com User git IdentityFile ~/.ssh/id_ed25519_personal Host github-work HostName github.com User git IdentityFile ~/.ssh/id_ed25519_work

然后克隆时用git@github-personal:用户名/仓库名.git，Git 会自动选择对应的密钥。这个配置在同时管理多个账号时非常实用。

5. README 与 .gitignore：仓库的门面与过滤器

5.1 README 不只是说明文档

README.md 是仓库首页自动渲染的内容，也是别人了解你项目的第一入口。一个合格的 README 至少包含：项目名称和一句话简介、安装步骤、使用示例、依赖说明、许可证信息。GitHub 支持 Markdown 语法，标题、列表、代码块、表格都能渲染。

如果你在新建仓库时没勾选 README，后面可以手动创建：

echo "# 项目名称" >> README.md git add README.md git commit -m "add README" git push

README 的文件名可以是README.md、README.rst、README.txt，GitHub 会按优先级自动识别。建议统一用.md，因为 Markdown 的排版能力最强。

5.2 .gitignore 的写法与常见模板

.gitignore文件用来告诉 Git 哪些文件不需要纳入版本控制。它的规则是按行匹配，支持通配符：

# 忽略所有 .log 文件 *.log # 忽略 node_modules 目录 node_modules/ # 忽略 .env 文件 .env # 但不忽略 .env.example !.env.example

不同语言和框架有不同的忽略规则。GitHub 在新建仓库时提供了模板选择，如果你勾了 .gitignore 并选了对应模板，会自动生成一份。如果没勾，可以到github.com/github/gitignore这个仓库里找对应语言的模板，复制到自己的项目里。

一个常见的坑是：如果文件已经被提交过，再添加到 .gitignore 是不生效的。需要先用git rm --cached 文件名把它从版本控制中移除，再提交。这个操作不会删除本地文件，只是让 Git 不再跟踪它。

5.3 许可证的选择逻辑

开源许可证决定了别人能怎么用你的代码。常见的有 MIT、Apache 2.0、GPL 3.0。MIT 最宽松，允许别人随意使用、修改、分发，只需保留版权声明；Apache 2.0 类似，但额外提供了专利授权；GPL 3.0 要求衍生作品也必须开源。

如果你只是分享学习笔记或个人小工具，MIT 就够了。如果是公司项目或希望更严谨，可以选 Apache 2.0。不确定的话，GitHub 在新建仓库时提供了许可证选择器，点进去有每种许可证的简要说明。

6. 新手最容易踩的五个坑与排查思路

6.1 推送报错 "remote origin already exists"

这个错误说明你已经添加过名为origin的远程仓库了。可能是之前操作过但忘了，或者复制粘贴时重复执行了命令。解决办法：

# 查看当前远程地址 git remote -v # 如果地址不对，先删除再重新添加 git remote remove origin git remote add origin git@github.com:用户名/仓库名.git

不要用git remote set-url直接改，虽然也能达到目的，但先删后加更直观，不容易搞混。

6.2 分支名不一致导致推送失败

GitHub 默认分支是main，但老版本 Git 在本地git init后默认分支是master。如果你本地是master，远程是main，推送时就会报错。解决办法有两种：

# 方法一：把本地分支重命名为 main git branch -M main # 方法二：推送时指定远程分支 git push origin master:main

方法一更彻底，推荐使用。-M是强制重命名，即使已存在同名分支也会覆盖。

6.3 SSH 连接超时或拒绝

执行ssh -T git@github.com时如果卡住或报Connection timed out，先检查网络是否能访问 GitHub。如果网络正常，可能是 SSH 端口 22 被限制。可以尝试用 HTTPS 端口：

# 在 ~/.ssh/config 中添加 Host github.com HostName ssh.github.com Port 443

这样 SSH 连接会走 443 端口，通常不会被限制。改完后再次测试连接。

6.4 提交了大文件导致推送失败

GitHub 对单个文件有 100MB 的限制，超过会拒绝推送。如果你不小心提交了大文件（比如数据集、视频），需要先从历史中移除：

# 从当前提交中移除 git rm --cached 大文件名 # 如果已经提交了多次，需要用 filter-branch 或 BFG 工具清理历史

预防措施是在项目开始时就配好.gitignore，把*.zip、*.mp4、data/这类目录排除掉。

6.5 克隆速度慢的应对方式

GitHub 在国内的访问速度不稳定，克隆大仓库时可能很慢。可以尝试以下方式：

• 使用浅克隆：git clone --depth 1 仓库地址，只拉取最近一次提交，历史记录不完整但速度快。
• 配置代理：如果你有可用的网络代理，可以为 Git 单独配置。
• 使用国内代码托管平台的镜像功能：部分平台支持从 GitHub 导入仓库，导入后在平台内克隆速度会快很多。

注意：浅克隆之后如果需要完整历史，可以用git fetch --unshallow补全，但这个过程同样需要网络通畅。

7. 仓库建好之后的日常操作习惯

7.1 分支策略：别一直在 main 上改

仓库建好后，建议养成用分支开发的习惯。main分支保持稳定，新功能开一个feature/xxx分支，修 bug 开hotfix/xxx分支，改完再合并回main。这样即使改出问题，也不会影响主分支的可用性。

# 创建并切换到新分支 git checkout -b feature/add-login # 开发完成后切回 main git checkout main # 合并分支 git merge feature/add-login # 推送 git push

对于个人项目，如果嫌麻烦，至少做到：每次推送前先git pull，避免远程有更新而本地不知道，导致推送被拒。

7.2 提交信息的写法

git commit -m "update"这种提交信息，过一周自己都看不懂改了什么。好的提交信息应该说明"做了什么"和"为什么"：

fix: 修复登录页面在移动端的布局错位 feat: 添加用户头像上传功能 docs: 更新 README 中的安装步骤

用fix、feat、docs、refactor这类前缀，可以让提交历史更清晰。这不是强制规范，但团队协作时非常有用。

7.3 定期清理远程分支

功能分支合并后，远程分支不会自动删除。时间长了，远程会积累大量已合并的分支。可以在 GitHub 仓库的Branches页面手动删除，也可以用命令：

# 删除远程分支 git push origin --delete feature/add-login # 清理本地已合并的分支 git branch -d feature/add-login

保持分支列表干净，找起来不费劲。

8. 从新建仓库到持续使用的完整闭环

新建仓库只是第一步，真正让仓库发挥价值的是持续使用。我自己的习惯是：每个新项目建好后，先配好 SSH、写好 README、加上 .gitignore，然后做一次初始提交。之后每天结束工作前git add . && git commit -m "..." && git push，形成肌肉记忆。

如果你还在用 HTTPS 地址推送，每次输 token，强烈建议花十分钟配一下 SSH。配完之后你会发现，推送代码这件事变得毫无阻力，这才是版本控制该有的体验。另外，README 不要等到项目做完再写，建仓库时就写个初稿，后面边做边补，比最后补写轻松得多。

仓库建多了之后，你会慢慢形成自己的模板：一套固定的 .gitignore、一个 README 骨架、一套分支命名规则。到那时候，新建仓库就是几分钟的事，精力可以全部放在代码本身。