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 gitgithub.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 TokenPAT代替密码。如果你输入账号密码后报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_emailexample.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 gitgithub.com如果看到Hi 用户名! Youve successfully authenticated...就说明配置成功了。第一次连接会问你是否信任 GitHub 的指纹输入yes回车即可。4.4 多台设备或多账号的密钥管理如果你有多台电脑每台都生成一把密钥分别添加到 GitHub这样任何一台丢失或重装只需删除对应的公钥不影响其他设备。不要在多台设备之间复制同一把私钥那样一旦泄露所有设备都要重新配置。如果你有多个 GitHub 账号比如个人号和工作号可以在~/.ssh/config文件里配置不同的 HostHost 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然后克隆时用gitgithub-personal:用户名/仓库名.gitGit 会自动选择对应的密钥。这个配置在同时管理多个账号时非常实用。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 pushREADME 的文件名可以是README.md、README.rst、README.txtGitHub 会按优先级自动识别。建议统一用.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 gitgithub.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 gitgithub.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 骨架、一套分支命名规则。到那时候新建仓库就是几分钟的事精力可以全部放在代码本身。