彭河森刚接触GitHub的时候，我估计你跟大多数人一样，第一反应是：这不就是个网盘吗？把文件拖进去不就行了？等到真上手才发现，上传文件这个事儿，卡住的基本都是同一个地方——不是不会点按钮，而是搞不懂Git和GitHub到底什么关系，以及本地那一堆命令到底在干什么。
这篇文章就是写给纯新手的入门教学。我把上传本地文件到GitHub仓库的完整过程拆开揉碎，从Git是什么、GitHub仓库怎么建，到git init、git add、git commit、git push这一串命令到底谁先谁后、为什么是这个顺序，再到常见报错的排查思路，一次性讲清楚。你不需要懂编程，只要跟着操作，就能把本地文件安安稳稳送上GitHub仓库。
1. 网盘思维是最大的拦路虎：先搞懂Git和GitHub的关系
很多新手在第一步就栽了跟头，原因不是操作有多难，而是脑子里默认了"GitHub等于网盘"。这个比喻只对了一半，另一半恰恰是让你后续所有操作变迷糊的根源。
1.1 本地仓库和远程仓库：两个文件夹的概念
先说Git。Git是一个版本控制工具，它跑在你的本地电脑上，不依赖任何网站。它的作用是接管你某个文件夹的版本历史——你改过什么、删过什么、什么时候提交过一次快照，它全都记着。这个被Git接管的文件夹，叫"本地仓库"。
GitHub则是一个远程托管平台。你把本地仓库整个推送到GitHub上，它就帮你存在云端服务器里，别人能看到、能下载、也能参与协作。这个云端上的副本，叫"远程仓库"。
所以整个过程其实是：
- 本地电脑上有个文件夹，里面有你的文件
- 用Git命令把这个文件夹变成本地仓库
- 在GitHub网页上创建一个空白远程仓库
- 把本地仓库的内容推送到远程仓库
git push这个动作，才是真正的"上传"。而那些git add、git commit，都是在为推送做准备工作，相当于打包、贴标签。
1.2 为什么不能直接在网页上拖文件
你可能要问了：GitHub网页明明支持直接上传文件，为什么还要折腾本地命令？
能用，但有明显局限。网页上传适合偶尔传一两个小文件，比如一个README文档、一张图片。一旦你的项目有几十个文件、还有子文件夹，网页上传就非常痛苦，而且完全没有版本管理的能力——你改了文件，想保留修改历史，网页操作做不到。
更关键的是，真实的开发协作场景里，几乎所有人都在用Git命令行或图形客户端操作。如果你只会网页上传，后面想参与开源项目、想给别人的仓库提交代码，会寸步难行。所以这篇教学主要以本地命令行为主，这也才是真正值得学的路径。
1.3 新手理解这两个概念后，操作就顺了
我见过太多人卡在焦虑里：命令敲了、报错看不懂，越试越慌。其实只要你心里有"本地仓库文件推到远程仓库"这个基本模型，再看命令就不会乱。
每一条命令都有明确对应的动作：
git init：把当前文件夹变成本地仓库git add：把文件从工作区放进暂存区git commit：把暂存区的文件正式记录成一个版本git remote add：给本地仓库绑定一个远程仓库地址git push：把本地记录推送到远程
后面我会逐个展开，现在先记住这个流程骨架就行。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 动手前的准备：Git安装与本地环境配置
开始之前，先把工具装好。这一步看着基础，但配置不对的话，后面推送时百分百会报错。
2.1 安装Git：Windows、macOS、Linux各有各的装法
Windows用户
去Git官网下载安装包，选择对应64位的Windows版本。下载后一路Next安装即可，但中间有几个选项要注意一下：
- 在"Select Components"页面，勾选"Git Bash Here"和"Git GUI Here"，右键菜单里会出现Git Bash入口，非常方便
- 在"Choosing the default editor"页面，新手直接选默认的Vim就行，或者选Notepad++这些更友好的编辑器
- 在"Adjusting your PATH environment"页面，选第一项"Git from the command line and also from 3rd-party software"
装完之后，在桌面右键，如果出现"Git Bash Here"，说明安装成功。
macOS用户
如果你的Mac装了Homebrew，一条命令搞定：
bash复制brew install git
没装Homebrew的话，直接去官网下载macOS版安装包，双击安装。首次打开终端时可能提示"无法打开，因为来自身份不明的开发者"，去"系统设置 -> 隐私与安全性"里点"仍要打开"就好。
Linux用户
Debian/Ubuntu系用：
bash复制sudo apt install git
CentOS/RHEL系用：
bash复制sudo yum install git
装完先验证一下版本，终端里敲：
bash复制git --version
能输出版本号，说明装好了。
2.2 配置用户名和邮箱：这是提交记录的身份证
Git安装好之后，必须配置用户名和邮箱。这一步很多新手会跳过，结果推送时报错或者提交记录里显示一堆乱码名字。
在Git Bash或终端里执行：
bash复制git config --global user.name "你的名字"
git config --global user.email "你的邮箱"
注意，这个邮箱建议用你注册GitHub时用的邮箱，这样提交记录才能和你GitHub账号对上号。验证配置是否生效：
bash复制git config --global --list
会显示你刚才配置的user.name和user.email。--global参数表示全局配置，作用范围是你这台电脑上的所有仓库，不用每次换项目都重新配。
2.3 Windows用户要特别注意：换行符配置
这个细节最容易出问题。Windows和Linux/macOS的换行符不一样——Windows是CRLF，Linux和macOS是LF。如果配置不对，推送代码后Git会提示大量文件被修改，但实际上内容一行都没变。
建议Windows用户在安装后执行：
bash复制git config --global core.autocrlf true
macOS或Linux用户执行：
bash复制git config --global core.autocrlf input
这样Git会在提交时自动处理换行符差异，避免一堆无意义的diff。
2.4 安装后的第一跑：从Git Bash进入你的文件目录
Windows用户装完Git后，建议统一用Git Bash来操作，不要用自带的CMD或PowerShell。Git Bash的命令风格和Linux终端一致，教程里的大部分命令都能直接复制粘贴，省去很多兼容性烦恼。
打开Git Bash后，你要先进入存放文件的目录。比如文件放在D:\my-project，就敲：
bash复制cd /d/my-project
Git Bash里Windows盘符的写法是/d/而不是D:\，这个需要注意。不想打字的话，可以在Windows资源管理器里进入目标文件夹，右键选择"Git Bash Here"，终端会自动定位到当前目录。
3. 从零创建你的第一个GitHub仓库
本地环境准备好之后，去GitHub网页上建一个远程仓库。这一步在网页上操作，很简单，但里面有几个字段要选对，否则后面还要返工。
3.1 注册并通过验证
这个不用多说，去GitHub官网注册账号。注册过程中需要接收验证邮件，注册成功后建议顺手把头像、用户名之类的完善一下。
有一点提一下：GitHub的免费账号已经够个人用了，可以创建无数个公开仓库和私有仓库，不用担心付费问题。
3.2 新建仓库时那几个选项到底怎么选
登录后，右上角有个"+"号，点开选"New repository"，进入创建页面。这里有四个地方要填：
Repository name（仓库名）
这个必填，建议用英文小写和短横线，比如my-project。仓库名是给人看的，也是远程仓库地址的一部分，起得清晰一点方便识别。
Description（描述）
选填，但建议填上。一句话说清这个仓库是干嘛的，别人浏览你的GitHub主页时一目了然。
Public还是Private
Public是公开的，任何人都能查看你的代码；Private是私有的，只有你自己和被你授权的协作者能看到。
新手不知道怎么选的话，我建议：只是自己存东西、学习练手，选Private；打算分享出来给更多人看，选Public。顺便说一句，GitHub免费版的Private仓库功能已经很完整，不用担心私有仓库有限制。
Initialize this repository with（初始化仓库内容）
这里注意了，新手特别容易被这三行勾选项误导。这个区域有三个复选框：
- Add a README file
- Add .gitignore
- Choose a license
对纯本地推送上来的场景，这三个先都不要勾。因为一旦勾选，GitHub会在远程仓库里自动生成一个初始提交，比如README文件，这时候你的本地仓库和远程仓库就各自有了互不相关的历史记录，第一次推送大概率会报冲突。
正确做法是：一个都不勾选。GitHub会进入一个空白仓库的引导页面，页面里有一段git remote add origin ...的命令，这个就是后面要用的。
3.3 创建完成后，先看懂仓库地址
创建完后，仓库页面会显示一个地址。这个地址有两种形式：
- HTTPS形式：
https://github.com/你的用户名/仓库名.git - SSH形式：
git@github.com:你的用户名/仓库名.git
新手阶段建议用HTTPS，因为配置简单。SSH需要生成密钥对，虽然一劳永逸，但入门阶段先不用折腾。后面我会专门讲两者区别。
提示：请务必记住这个仓库地址，后面
git remote add要用到。建议复制到记事本里备用。
4. 本地文件上传的完整流程：从init到push逐条拆解
现在进入正题。假设你在本地有个文件夹叫my-project，里面放着你要上传的文件，打开Git Bash并定位到该目录，开始执行以下命令。
4.1 git init：把普通文件夹变成仓库
在my-project目录下执行：
bash复制git init
执行完，终端会显示Initialized empty Git repository in ...，并且文件夹里会多出一个隐藏的.git目录。这个.git目录就是Git的记录本，里面存着所有版本信息，千万不要手动去改它，也不要删它。
这一步的本质是在当前文件夹里创建一套空的Git管理机制。此刻你的本地仓库已经诞生了。
4.2 git status：随时查看当前状态
正式操作之前，先教一个"救命命令"：
bash复制git status
任何时候不确定自己操作到哪一步了、哪些文件被改了、哪些还没提交，敲一下就清楚了。终端会告诉你当前在哪个分支、有没有未跟踪的文件、哪些文件被修改过。
新手养成一个习惯：每执行完一步关键操作，都跑一下git status看看结果，比瞎猜强得多。
4.3 git add：把文件放进暂存区
现在用git status查看，你会发现文件还处于未跟踪状态，文件名字前面显示红字untracked。这时候需要让Git开始跟踪这些文件：
bash复制git add .
这个命令把当前目录下所有文件都加入暂存区。如果你只想添加某个文件，可以用：
bash复制git add 文件名.txt
.代表整个目录，最常用。执行完再跑git status，文件名字会变成绿色，表示已经进入暂存区了。
很多新手不理解为什么要先add再commit，直接提交不行吗？这个add相当于把要打包的文件挑出来放到一个篮子里，你可以决定哪些进篮子、哪些不进，比如那些临时文件、日志文件完全可以不放进去。commit则是把这个篮子里的东西正式封存成一个版本。
4.4 git commit：正式记录一个版本
执行：
bash复制git commit -m "首次提交"
-m后面跟的是提交说明，这是必填的。提交说明要写清楚你这次改了什么，比如"添加了项目说明文档"、"修复了登录页面的样式问题"。这样以后翻历史记录时，一眼就能看出每个提交做了什么。
如果忘了加-m，Git会打开一个文本编辑器让你输入说明，新手一般会被困在Vim里出不来。所以一定记得用-m参数。
提交完，git status应该显示工作区整洁，没有待提交的内容了。
4.5 绑定远程仓库：让本地仓库认识GitHub上的家
这一步把本地仓库和GitHub上的远程仓库关联起来：
bash复制git remote add origin https://github.com/你的用户名/你的仓库名.git
origin是远程仓库的默认名称，你可以理解为"给这个远程仓库起了个名字叫origin"。以后推送时就用这个名字指代远程仓库，不用每次都敲一长串地址。
如果这一步操作时不小心填错了地址，可以用下面命令先删掉再重新添加：
bash复制git remote remove origin
检查当前绑定的远程地址：
bash复制git remote -v
会列出所有已绑定的远程仓库地址和名称。
4.6 第一次推送：把本地仓库推送到远程
执行：
bash复制git push -u origin master
或者现在很多新版本默认分支名是main：
bash复制git push -u origin main
你本地分支到底叫master还是main，可以通过git branch命令查看，不带参数时会在当前分支前面标注星号。如果嫌麻烦，也可以直接用更通用的写法：
bash复制git push -u origin HEAD
HEAD表示把当前所在分支推送上去，不用操心分支名到底是master还是main。
我用-u参数，作用是把本地分支和远程分支建立关联关系。加了这个参数之后，下次再推送，只需要敲git push就够，不需要再写origin和分支名。
第一次执行git push，如果你用的是HTTPS地址，会弹出一个登录窗口或者让你在终端里输入GitHub的用户名和密码。要注意的是，现在的GitHub已经不支持用账号密码直接登录代码推送了（2021年8月13日起），必须用Personal Access Token（个人访问令牌）来代替密码。
4.7 生成Personal Access Token并完成认证
这一步很多新手会卡住，因为不知道"密码"已经被GitHub废除了。正确做法是：
- 登录GitHub网页版
- 点击右上角头像，选"Settings"
- 拉到页面左侧，选"Developer settings"
- 点"Personal access tokens"，再选"Tokens (classic)"
- 点"Generate new token"，选"Generate new token (classic)"
- 给token起个名字，比如
my-project-push - 在权限范围里，勾选
repo这一整块（包括repo、workflow等子项） - 点最下面的"Generate token"
- 页面会显示一串以
ghp_开头的字符串，立刻复制保存，这个token只在生成时显示一次，刷新后就看不到了
然后回到终端，在提示输入密码时，粘贴这串token即可。粘贴的时候终端不会显示任何字符，这是正常现象，粘贴后直接回车就行。
注意：token就是你的"一次性密码"，千万不要把它提交到代码里或者发到公开的地方。GitHub检测到token泄露会自动撤销。丢了你再去生成一个，不麻烦，但丢到公开仓库里就有安全隐患了。
推送成功后，终端会显示一行master -> master之类的提示，然后你就可以去GitHub网页上刷新仓库页面，看到文件已经躺在那了。
4.8 节点小结：整个上传流程的命令序列
为了方便你照抄，我把完整命令按顺序列一遍：
bash复制cd /d/my-project
git init
git add .
git commit -m "首次提交"
git remote add origin https://github.com/你的用户名/你的仓库名.git
git push -u origin HEAD
中间的git status可以随时插入查看状态。就这么几行命令，覆盖了完整的上传流程。
5. 上传过程中的常见报错与排查思路
走到这一步，你已经成功把文件推上去了。但实际操作中几乎没人一次全过，我把自己踩过、以及在社区答疑时见过最多的报错整理出来，你遇到就能直接对号入座。
5.1 fatal: remote origin already exists
执行git remote add origin时报这个错，说明你已经绑定过远程仓库了，重复添加会失败。
排查方式：
bash复制git remote -v
如果显示的地址是对的，那就不用管，直接推送。如果地址是旧的、错的，先删除再重新添加：
bash复制git remote remove origin
git remote add origin 正确的地址
5.2 fatal: repository not found
执行git push时报这个错，几乎永远是下面三个原因之一：
- 远程仓库地址拼错了，检查
git remote -v显示的地址是否正确 - 你访问的是别人的私有仓库，GitHub认为你没权限
- 设置了Git代理但代理失效了，这个情况在国内网络环境下比较常见，关掉代理或者检查网络配置
排查思路就一条：挨个核对地址、权限、网络环境。
5.3 remote: Support for password authentication was removed
这就是我前面提到的，你用了账号密码而非token。解决办法就是去生成Personal Access Token，用token当密码。
注意，有些情况下Git会缓存之前输入的错误凭据，导致你一直报同样的错。Windows系统可以用控制面板里的"凭据管理器"，找到git:https://github.com这条，删掉，下次推送时会重新让你输入凭据。
5.4 fatal: refusing to merge unrelated histories
这个报错出现的原因，多数情况下是你在创建仓库时勾选了"Add a README file"或".gitignore"，导致远程仓库有了一次初始提交，而本地仓库的提交历史和它对不上。
解决方式有两种，根据情况二选一：
方式一：强制合并两条历史
bash复制git pull origin master --allow-unrelated-histories
执行后把远程的内容拉下来，合并本地，然后重新推送：
bash复制git push -u origin HEAD
方式二：最省事的重新初始化
如果你本地文件不重要，或者刚创建仓库还没怎么折腾，最快的方法是：删掉本地.git目录和GitHub上的仓库，重新走一遍git init流程，这次创建远程仓库时绝不勾选任何初始化选项。
5.5 error: failed to push some refs to ...
这个报错很笼统，但常见原因是：远程仓库里有本地没有的提交，比如你之前通过网页上传过文件，或者团队其他人推送过代码，而你没有先拉取到本地。
解决办法是先把远程的改动拉到本地，再推送：
bash复制git pull origin master --allow-unrelated-histories
然后再推：
bash复制git push -u origin HEAD
5.6 网络连接GitHub不稳定
访问GitHub偶尔出现响应缓慢或者连接超时，这是实际存在的网络环境问题，不是你的操作问题。常见的处理思路有这样几种：
- 耐心重试几次，尤其是非高峰时段
- 换一个网络环境试试，比如手机热点
- 检查本地网络代理配置是否正常
这个问题属于环境问题，不是一条命令能解决的，心态放平，别在报错里钻牛角尖。
6. 几个值得养成的使用习惯与进一步选择
文件推上去之后，你已经完成了入门。但接下来的使用习惯，决定了你和GitHub相处得顺不顺心。
6.1 每次改动后的标准三步
以后你更新文件，不需要再走一遍init和remote add，只需要：
bash复制git add .
git commit -m "这次改了什么"
git push
这三步就是后续日常开发中最核心的循环。改文件、记录版本、推送到远程，熟练之后几秒就能完成。
6.2 添加.gitignore，别把垃圾文件推上去
你的项目文件夹里可能有一些不需要上传的东西，比如临时文件、日志、本地配置文件、系统自动生成的缩略图。如果统统推上去，仓库会变得很乱。
解决办法是在项目根目录创建.gitignore文件，写上不想被Git跟踪的文件或目录：
code复制node_modules/
.DS_Store
*.log
.gitignore文件本身要提交，这样别人克隆项目时也会自动忽略这些文件。新手阶段只要记住：凡是"本地运行需要但别人不需要"的文件，都该进.gitignore。
6.3 学会查看提交历史
你想看看这个项目改过哪些版本，用：
bash复制git log --oneline
会显示一串提交记录，每个提交前面有一个哈希值，后面是提交说明。这就是你的项目历史档案。
6.4 什么时候切换到SSH方式
我前面建议新手用HTTPS，因为它配置简单，但缺点是每次推送都要输入token（除非你配置凭据缓存）。如果你觉得频繁输入token很烦，可以考虑切换成SSH方式。
SSH的优点是一把密钥走天下，配置一次后推送免密；缺点是第一次生成密钥、把公钥添加到GitHub后台那几步，对新手来说比配token要复杂一点。
如果当前阶段觉得HTTPS+token够用，就先用着，不用急着折腾SSH。等你Git玩熟练了，再切换也不迟。
6.5 从GitHub上把自己仓库拉回本地
如果你在另一台电脑上，想把远程仓库的文件下载到本地，用：
bash复制git clone https://github.com/你的用户名/你的仓库名.git
git clone会把这个仓库整个复制到当前目录，并且自动带上完整的.git记录，不需要再执行git init。
6.6 先写README，让仓库更完整
仓库里最好放一个README.md文件，用Markdown格式写这个项目是做什么的、怎么使用、有哪些功能。README会直接显示在GitHub仓库主页上，不管是别人访问还是你自己日后回来看，都能快速了解这个仓库的情况。
创建README有个小技巧：本地用记事本或编辑器新建文件，内容写好后保存为README.md，然后按标准三步上传即可。
我自己带过不少新手，发现一个规律：凡是能静下心先把"本地仓库、远程仓库、暂存区"这三个概念理清楚的人，后面基本不会遇到太多障碍。反而是那些急着敲命令、出错就慌的人，最容易在同一个坑里反复摔。
所以，如果你现在刚走完一遍流程，我建议你做一件事：把本地仓库删掉，重新走一遍完整的upload流程。第二次你会从容很多，第三次基本上闭着眼都能推上去了。这条路不复杂，就是熟能生巧。