如果你跟我第一次上手时一样本地项目已经写得有模有样结果打开 GitHub 新建仓库后对着网页发了一会儿呆不知道怎么把整个文件夹稳稳当当地传上去那这篇内容就是给你准备的。Git 和 GitHub 在刚开始接触时最容易被混为一谈而“上传”这件事也远没有网页端拖拽文件那么直觉。真正的做法是在本地通过 Git 命令行初始化项目、提交代码再关联远程仓库并推送。链路看起来不长但中间任何一步卡住都可能让新手劝退有人卡在安装 Git 后不知道用什么来敲命令有人卡在 push 时反复提示认证失败还有人被 main 和 master 两个分支名绕晕。这篇教程会把这整条链路完整走一遍。我会从 Git 安装、身份配置、仓库创建讲到第一次 git push 成功过程中会把每个命令背后的原因也讲清楚而不只是给你一长串复制粘贴的代码。你不需要有命令行基础只要电脑上能正常打开 GitHub 并登录账号跟着操作就能完成第一次上传。1. 动手之前先弄清Git 和 GitHub 是两件东西1.1 本地仓库与远程仓库其实是“记账本”和“云端保险柜”我见过不少新手把 Git 和 GitHub 当成同一个东西其实它们的职责完全分开。Git 是一个分布式版本控制工具它主要在你的电脑本地工作。它做的核心事情是记录项目的每一次改动每一次你执行一次提交相当于给整个项目拍了一张快照。从此以后你可以随时回到任意一次快照的状态对比改动、找回误删的文件甚至回到几天前某个还能跑的版本。这个能力对于写代码的人来说几乎是必需品因为没有人能保证自己不会改出问题。GitHub 则是基于 Git 的远程仓库托管平台。你本地的提交记录同步到 GitHub 上之后相当于把这份“账本”备份到了云端。好处非常明显换电脑时拉下来就能继续干活项目被误删时云端还有一份如果是多人协作大家各自在本地提交再由某个人统一合并不会互相踩踏文件。如果要做个类比Git 是你电脑里的一本“修改日记”每次提交就是写好一页日记GitHub 是存放这本日记的云端保险柜。push 是把最新几页抄送上去pull 是把云端的新内容拿回来。1.2 真正合理的前置准备清单开始操作之前你只需要准备好三样东西电脑上安装好 Git。具体安装过程会在第 2 部分细说这里先不展开一个能正常登录的 GitHub 账号。注册是免费的和普通网站注册流程没区别一个真实的本地项目文件夹。注意这个文件夹里至少要有一个文件不能是彻底的空文件夹原因是 Git 只追踪文件、不追踪空目录后面会专门讲这一点。很多人觉得自己得先把 Git 命令背熟才能开始真没必要。刚开始你只需要掌握十几个命令甚至先把 add、commit、push 这三个用好就已经能覆盖个人项目的大部分场景。2. 安装 Git 的关键选项这三个配置决定你后面是否顺利2.1 Windows 安装注意 PATH、默认编辑器和换行符在 Windows 上安装 Git最正统的渠道是去官网 git-scm.com 下载对应系统的安装包。网上搜到的很多第三方下载站版本老旧还可能捆绑额外软件不建议用。安装包下载完以后大部分页面一路点“Next”没问题但有几个配置项值得你停下来看一眼因为这里的选择会直接影响你后面一段时间的体验。第一项是“Select Components”默认选项即可。如果你发现默认没有勾选“Git Bash Here”上下文菜单选项建议手动勾上。它会在文件夹右键菜单里加一个“Git Bash Here”入口你之后进入项目的 Git 环境会非常方便不用手动敲一长串路径。第二项是“Choose the default editor used by Git”。新版 Git 在 Windows 上默认使用 Vim 作为编辑器但对不熟悉 Vim 的人来说一旦不小心进入 Vim 界面会完全不知道怎么退出这是新手一个非常常见的卡点。如果你电脑里装了 VS Code这里可以改成“Use Visual Studio Code as Gits default editor”如果什么都没装保留 Vim 问题也不大前提是你提交时坚持用git commit -m 说明这种带参数的方式就不会进入编辑器界面。第三项是“Adjusting your PATH environment”。我强烈建议选择中间那项“Git from the command line and also from 3rd-party software”也就是把 Git 加入系统 PATH。这样你之后在命令行窗口里直接输入 git 才能被识别否则只能在 Git 自带的终端里使用。还有一个可能让人困惑的点是“Configure the line ending conversions”这一步默认选项是“Checkout Windows-style, commit Unix-style line endings”。对于初学者来说保持默认或者第一项都可以但建议你记住你选了哪一项。后面如果项目在 Windows 和 Mac 之间来回切换出现了大量莫名其妙的文件改动提示多半就是换行符转换策略的问题。安装完成后你会在开始菜单里看到 Git Bash、Git GUI 和 Git CMD 等几个入口。日常操作选 Git Bash它模拟了 Linux 风格的终端环境很多命令习惯和 Windows 自带的 cmd 不一样比如查看文件列表用的是ls路径使用/c/Users/...这种格式新手固定用它能少很多环境切换带来的混乱。2.2 Mac / Linux 安装一句话版Mac 上最简单的方式是打开终端先执行git --version如果系统提示没有安装会弹出安装开发者工具的命令行工具的引导确认安装即可。也可以用 Homebrew 安装brew install git。Ubuntu / Debian 系的 Linux终端执行sudo apt update sudo apt install gitCentOS / RHEL 系则用sudo yum install git安装 Linux 版本时不同发行版的包管理器命令不同只需要保证自己装的是新版本至少 2.x 以上就足够完成本教程的所有操作。2.3 用 git --version 验证安装与进入 Git Bash安装结束后打开 Git Bash输入git --version能看到类似git version 2.x.x.windows.x的输出就说明安装成功。再执行git config --list这一步会列出当前的 Git 配置如果里面还是空的还没问题下一部分就会配置身份。从这一步开始后面所有操作都建议在 Git Bash 里进行。Windows 自带的 PowerShell 或 cmd 虽然也能执行 git 命令但在某些版本的终端里中文显示、路径处理都会有些小脾气新人不值得在这些地方浪费时间。3. 身份认证配置与仓库创建为第一次推送铺好路3.1 提交署名最不能省下的 git configGit 在提交代码时会在每次提交记录里写下一个作者信息。这个信息不是自动从系统读取的而是需要你主动告诉 Git。所以安装完 Git第一件必须做的事是配置用户名和邮箱git config --global user.name yourname git config --global user.email youremailexample.com注意这里的邮箱不一定要和 GitHub 注册邮箱完全一致但强烈建议保持一致。原因很简单GitHub 会把提交记录里的邮箱和你账号的邮箱对应起来一致的情况下你在 GitHub 提交列表里会显示自己的头像和昵称不一致的话提交记录会显示成一个通用头像看起来像“陌生人提交的代码”。设置完可以用下面命令验证git config --global --list--global参数的意思是“全局生效”也就是这台电脑上所有仓库都使用这个身份。如果你有几个不同的身份比如工作一个、个人一个也可以去掉--global在具体某个仓库内部单独设置。3.2 SSH 密钥与 HTTPS Token结合实际场景的选择本地 Git 要连接 GitHub无非两种认证方式SSH 密钥或者 HTTPS 加 Token。两者没有绝对优劣但实际体验差别很大。如果只求快速跑通流程HTTPS 比较直接你在本地复制 GitHub 仓库的 HTTPS 地址推送时在弹出的窗口里输入用户名和密码即可。不过需要注意GitHub 早在 2021 年就取消了账号密码的 HTTPS 认证方式现在要求使用 Personal Access Token 作为密码。这个 Token 本质上是 GitHub 给你签发的一个带权限的临时密码创建路径是 GitHub 的 Settings - Developer settings - Personal access tokens勾选 repo 权限生成后复制保存。如果选这条路推送时用户名填 GitHub 用户名密码粘贴 Token。但如果你打算长期和 GitHub 打交道我更建议直接配 SSH。原因有二第一不用反复输入认证信息配置一次以后就畅通无阻第二SSH 密钥的权限管理更清晰你可以为不同电脑生成不同密钥哪天某台设备不再使用直接在 GitHub 后台删掉那把公钥即可不影响其他设备。SSH 配置总共四步。第一步在 Git Bash 中生成密钥ssh-keygen -t ed25519 -C youremailexample.com如果你的系统提示 ed25519 不支持改用ssh-keygen -t rsa -b 4096 -C youremailexample.com命令运行后会询问保存位置和密码短语。保存位置直接回车使用默认路径即可密码短语也就是 passphrase是给你私钥加的一道本地密码如果不想每次操作都输入直接回车留空。第二步查看公钥内容cat ~/.ssh/id_ed25519.pub公钥是一长串字符从ssh-ed25519开头一直到结尾邮箱地址全部复制。第三步把公钥添加到 GitHub。登录 GitHub打开 Settings - SSH and GPG keys - New SSH key粘贴保存。第四步测试连接ssh -T gitgithub.com如果看到Hi yourname! Youve successfully authenticated, but GitHub does not provide shell access.说明密钥已经生效。这个输出看起来像“拒绝”但其实是成功的标志。3.3 在 GitHub 创建空仓库为什么我不建议先勾 README接下来去 GitHub 创建一个新仓库。点击右上角加号选择“New repository”填上仓库名和可见性Public 公开 / Private 私有。这一步有一个很多新手踩过的重要细节页面下方“Initialize this repository with”这组选项包括 Add a README file、Add .gitignore、Choose a license第一次操作时我建议全部不要勾选直接创建一个完全空的仓库。原因在于如果你勾选了 READMEGitHub 会替你在远程仓库里生成一条初始提交。而你自己本地仓库的提交历史和这条远程初始提交没有共同祖先推送时 Git 会因为双方历史不一致而拒绝报的正是新手最容易看到的failed to push some refs错误。虽然这个问题有解决办法但对于第一次上传的人来说完全没必要在还没有运行经验时给自己制造额外的障碍。仓库创建完成后GitHub 会给你一个引导页面上面显示两种远程地址HTTPS 格式https://github.com/yourname/yourrepo.gitSSH 格式gitgithub.com:yourname/yourrepo.git把对应格式的地址复制下来后面的操作会用到。如果你不想每次 push 输 Token就复制 SSH 格式如果暂时没配 SSH复制 HTTPS 格式也可以。两种方式都能完成第一次上传区别只在认证环节的体验。4. 本地项目首次上传 GitHub 的完整操作链4.1 用“Git Bash Here”进入项目目录最稳妥的路径现在回到本地找到你的项目文件夹。在文件夹空白处右键如果安装 Git 时勾选了上下文菜单这里会有一个“Git Bash Here”选项点击它Git Bash 会自动打开并定位到当前目录。这一步比你自己手动输入cd路径要稳妥得多尤其是在 Windows 的路径中包含中文、空格或特殊符号时手动敲路径很容易出错。打开后先用pwd确认当前路径确实是你的项目目录。4.2 git init 到 git commit用三轮 git status 理解暂存在项目目录下执行初始化命令git init这一命令的作用是在当前目录创建一个.git隐藏文件夹里面有 Git 需要的全部内部数据。从这一刻起这个目录就变成了一个本地 Git 仓库Git 会开始注意这里发生的每一次文件变化。然后执行git status这是接下来你会用到频率最高的命令之一。它的职责是展示当前仓库的状态。刚执行完git init时项目里的文件通常会显示为“Untracked files”中文意思就是“未被追踪的文件”。这些文件虽然存在但 Git 还没有记录它们。要让 Git 真正管住这些文件需要把它们加入暂存区git add .git add后面跟的.表示当前目录下的所有文件和子目录。如果你只想添加某个文件可以写git add index.html如果想添加某个文件夹可以写git add src/。这里解释一下暂存区的概念。Git 的工作流程可以拆成三块工作区你电脑上实际看到的文件、暂存区本次准备提交的候选清单、版本库已经提交的历史记录。git add是把工作区改动放入暂存区相当于在提交前先“点菜”确认哪些内容要进入这轮评审。执行完git add .后再执行一次git status你会看到文件名变成了绿色状态是“Changes to be committed”意思就是这些改动已经被放进暂存区等待提交。接着执行真实意义上的提交git commit -m first commitgit commit会把暂存区的内容正式记录成一条提交-m后面跟的是本次提交的说明一般用来简述这次提交做了什么。这一步也回答了为什么我建议永远用-m参数如果你不写Git 会打开默认编辑器让你输入提交信息新手一旦遇到 Vim就很容易卡住。提交完成后第三次运行git status你会看到提示nothing to commit, working tree clean意思是工作区干净了没有待提交内容。这说明本次提交已经完成了。4.3 关联远程仓库与 git push -u 的含义此时本地仓库有了第一条提交但 GitHub 上的远程仓库还是完全空的。现在需要把两者关联起来。git remote add origin gitgithub.com:yourname/yourrepo.git如果你用的是 HTTPS 方式则把地址换成 HTTPS 形式。命令中的origin是远程仓库在本地的名字相当于给远程仓库地址起了一个别名。之所以用 origin是因为这是 Git 社区约定俗成的远程主仓库命名你当然也可以改成别的名字但新手没必要特立独行。关联后可以验证一下git remote -v这个命令会列出当前仓库已经关联的所有远程地址。看到有输出就说明关联成功。接下来是最关键的一步——推送git push -u origin main这条命令的意思是把本地当前的main分支推送到名为origin的远程仓库并且用-u参数建立本地分支和远程分支的追踪关系。-u是--set-upstream的简写它值得特别一提。加上这个参数之后Git 会记住“当前本地分支对应的远程分支是谁”以后你在这个分支上直接输git push或git pull就不用再带origin main了。第一次推送时即便你已经设置了多项远程参数这条命令也是让后续操作变简单的关键。推送过程中如果走 SSH 认证第一次连接时可能会询问是否信任 github.com 的主机指纹输入yes回车即可。如果走 HTTPS则按提示输入用户名和 Token。推送成功后刷新 GitHub 仓库页面你会看到项目文件已经整整齐齐出现在仓库里提交记录里也有这个“first commit”。4.4 空文件夹传不上去Git 只追踪文件不是 bug有个高频问题顺便在这里讲清GitHub 上怎么上传文件夹很多人以为上传文件夹是一个独立操作其实不是。Git 追踪的最小单位是文件而不是文件夹一个文件夹如果里面没有任何文件git add 时会被自动忽略自然也不会出现在远程仓库。所以如果你的项目里有一个必须保留但当前是空着的目录比如用来放文件的uploads/目录正确做法是在里面放一个占位文件一般命名为.gitkeep。这个名字本身没有特殊含义纯粹是社区约定“这个文件存在的意义就是让 Git 保留这个空目录”。touch uploads/.gitkeep git add uploads/.gitkeep git commit -m add uploads directory git push这样远程仓库里就会保留 uploads 目录。touch在 Git Bash 里就是创建空文件的常用命令Windows 资源管理器里新建文本文件重命名效果也一样。5. 首次 push 最容易翻车的四种报错与解决5.1 “failed to push some refs”远程仓库已先有提交几乎每个新手都会在第一次推送时遇到这条报错原因通常就是第 3.3 节提到的创建 GitHub 仓库时勾选了 README导致远程仓库已经有了一个独立提交而本地仓库也有自己的提交两边互不相识Git 出于安全考虑拒绝覆盖远程内容。报错原文大概是这样的! [rejected] main - main (fetch first) error: failed to push some refs to github.com:yourname/yourrepo.git hint: Updates were rejected because the remote contains work that you do hint: not have locally.解决办法是按提示先把远程内容拉下来再做一次合并git pull origin main --allow-unrelated-histories--allow-unrelated-histories参数比较关键它的意思是“允许合并两个没有共同祖先的分支”。因为本地和远程的提交历史互相独立默认情况下 Git 会拒绝合并加了它才能顺利把远端的 README 合并到本地。合并可能会触发一个编辑器让你输入合并提交说明不用紧张直接保存退出。如果你不熟悉操作可以在 pull 之前先执行下面命令把默认编辑器改成 VS Code或者直接用-m参数提交合并git pull origin main --allow-unrelated-histories -m merge remote README合并完成后再执行git push -u origin main这次就能成功。如果远程的 README 文件对你毫无价值也可以直接在 GitHub 网页端删除远程仓库重新建一个空仓库或者用强制推送git push -f origin main覆盖远程历史。对于个人学习项目强制推送后果相对可控但一旦涉及协作尽量少用。5.2 “Authentication failed”密码认证时代已经过去另一个高频报错是推送时提示remote: Support for password authentication was removed on August 13, 2021. fatal: Authentication failed for https://github.com/yourname/yourrepo.git这段提示翻译过来就是GitHub 已经不支持用账号密码做 HTTPS 认证了。很多新手不知道这一点在弹窗里输入 GitHub 登录密码自然会被拒绝。解决方式取决于你绑定的远程地址如果用的是 HTTPS 地址去 GitHub 生成一个 Personal Access Token推送时用户名填 GitHub 用户名密码处粘贴 Token如果不想再为 Token 烦恼干脆切换成 SSH 认证。先按第 3.2 节配置好密钥再执行git remote set-url origin gitgithub.com:yourname/yourrepo.git这条命令会把当前仓库关联的远程地址从 HTTPS 改成 SSH不用删除重新添加。改完后执行git remote -v确认地址已经变化再重新 push 即可。5.3 分支名从 master 变成了 main别慌如果你在 push 时遇到这种提示error: src refspec main does not match any说明本地仓库里没有叫 main 的分支。旧版本 Git 初始化的默认分支名是 master而 Git 2.28 以后以及 GitHub 新建仓库默认分支名都是 main。两边不在同一个名字Git 自然找不到要推送的分支。处理方式是把本地分支重命名git branch -M main-M表示“强制把这个分支重命名为 main如果已存在同名分支则覆盖”。执行后再推送git push -u origin main这里还提醒一个细节你在 GitHub 新仓库页面上看到的默认分支名称通常显示为 main。如果你本地分支是 master不做统一命名就可能把master也推上去远程仓库里出现 main 和 master 两个分支并存的情况。虽然也能运行但对个人项目来说没有必要保持一个默认分支就够了。5.4 莫名出现的行结束符 diff还有一个问题平时不触发一触发就让人摸不着头脑你明明只是改了一行代码但git diff显示整个文件都变了每一行都带上改动标记。这种情况十有八九是换行符问题。Windows 默认使用 CRLF回车加换行表示一行结束Linux / Mac 使用 LF只换行。Git 在提交和检出时可以自动转换换行符但转换策略如果和文件原始格式不匹配就会发生“虽然没改内容但 Git 认为所有行都变了”的奇怪现象。解决方案要根据项目类型来确定。如果你是在个人项目里遇到这个问题可以在仓库根目录添加一个.gitattributes文件明确指定文本文件的换行符规则* textauto更严格一点按扩展名指定*.js text eollf *.html text eollf *.css text eollf添加后执行git add --renormalize .这会让 Git 按照新的换行策略重新规范化文件。规范化后提交一次后续的改动对比就会恢复正常。如果项目有多个协作者end of line问题最好在项目初期就统一通过.gitattributes一次性约定而不是让每个人各自安装配置。否则每次跨平台协作都在制造噪音 diff非常耗神。6. 上传成功后我更推荐你养成的几个 Git 习惯6.1 首次提交前先写好 .gitignore很多新手第一次提交时就把整个文件夹全部 add 进去顺手把node_modules、__pycache__、target这些目录也推到了 GitHub。这些目录是依赖或编译产物动辄几百 MB别人克隆你的项目时会被迫下载一堆毫无意义的东西。正确做法是首次提交前就写好.gitignore文件。不同技术栈有不同的忽略规则Node 项目至少要忽略node_modules/ dist/Python 项目至少要忽略__pycache__/ *.pyc .venv/Java 项目至少要忽略target/ build/除此之外本地的环境配置文件、IDE 配置、日志文件、密钥文件等都应该纳入忽略列表。如果你拿不准家里项目的规则可以去 GitHub 官方维护的 gitignore 仓库里复制对应模板地址上直接搜“github/gitignore”就能找到。这里要特别强调一点.gitignore对还没被 Git 追踪的文件生效。如果某个文件已经被提交进仓库再把它写进.gitignore并不能让它从仓库里消失你需要额外执行git rm --cached才能把它从版本控制里移除。所以第一次提交前做好忽略比后面补救要省事得多。6.2 提交信息怎么写回看时不后悔第一次上传很多人会写“first commit”这没问题。但后续提交如果全是“update”、“修改”、“1”等到一周后你想找某次改动会发现历史记录完全没法看。建议从小养成这个习惯一行提交信息尽量说清楚“这次提交做了什么”。比如“修复登录页在移动端样式错乱的问题”“新增用户头像上传功能”“重构订单查询模块去掉冗余接口”另外一次提交尽量只做一件事。如果你同时改了页面样式、调整接口、优化了数据库查询最好拆成三次提交而不是混在一个提交里。这样做的好处是将来排查问题时可以精确定位到某一次改动不用在几十个混合提交里大海捞针。6.3 漏提交了文件用 git commit --amend 补救第一次提交经常出现的情况是提交完成后发现自己漏了一个文件或者提交说明写错了字。如果是刚提交完、还没有推送使用git commit --amend是最顺手的补救方式。假设你漏了一个文件config.js先把它加进暂存区git add config.js git commit --amend -m 补充遗漏的配置文件这个命令会把暂存区的内容合并进上一条提交并替换掉上一条提交的说明。也就是说提交历史里不会出现一条“哦忘了加文件”的记录而是直接变成一条更完整的提交。需要注意--amend只适合还没有推送出去的提交。如果已经git push过了再 amend 就会导致本地和远程历史不一致需要强制推送才能同步涉及协作时风险很大。所以我的习惯是提交后、推送前先看一眼提交内容确认无误再 push。6.4 日常循环其实就这四条命令当你第一次 push 成功之后后续的日常开发流程会迅速收敛成这样一个循环git status git add . git commit -m 描述本次改动 git push配合两个查看命令git log --oneline git diffgit log --oneline用来快速浏览提交历史每一行一条提交非常清爽git diff用来查看工作区里还没暂存的改动内容提交前扫一眼能有效避免把调试代码顺手提交上去。你在 GitHub 上看到的所有所谓“大佬”项目其版本管理动作本质上也是这组命令的重复与组合。差别只在于他们对提交时机的把握、分支策略的选择、以及历史整洁度的维护更讲究。第一次上传成功只是起点但你已经完成了最关键的从 0 到 1。后面要做的无非是把这个循环用熟再根据实际需求逐步接触分支、合并、回滚、rebase 这些更进阶的概念。别急着一次性学完所有 Git 命令真正常用的本来就不多先把当前这组命令练到不假思索你会发现 GitHub 从“一个看不到入口的网站”慢慢变成了“一个很自然的代码存放地方”。