你打开 GitHub 页面知道怎么新建仓库也知道怎么创建文件可真要把一个本地开发好的项目文件夹完整传上去很多人会突然卡住。网页上只有“Upload files”没有“Upload folder”这种一眼就能看懂的入口于是不少人走弯路先把文件一个个传传着传着就乱套或者干脆去搜第三方工具其实 GitHub 本身已经在网页端支持了文件夹直接上传只是入口藏得比较深。这篇文章就把“上传文件夹到 GitHub”这件事彻底讲明白。全文基于标准 GitHub 网页端和官方 Git 工具不涉及任何非官方渠道和第三方辅助手段。主要覆盖三种方式网页端拖拽上传、主流命令行 Git 操作、GitHub Desktop 客户端操作每一步都配上关键界面的文字说明最后再集中盘点上传过程中最容易让人心态爆炸的几个报错场景和排查链路。适合刚接触 GitHub 的新手、第一次部署个人项目的大学生、以及平时只用网页端但想系统理解 Git 流程的开发者。1. 上传文件夹之前先理解 GitHub 的存储逻辑1.1 “仓库”才是 GitHub 里的文件夹很多人第一次用 GitHub心里想的是“我要把这个文件夹传到网站上”。但 GitHub 的最小组织单元不是文件夹而是仓库Repository。一个仓库在本地可以对应一个目录这个目录下面的所有子文件夹、文件、历史修改记录共同构成仓库的内容。你在本地看到的层级是这样的my-project/ ├── src/ │ ├── components/ │ └── utils/ ├── docs/ ├── package.json └── README.md传到 GitHub 之后GitHub 并不会把最外层的my-project/显示成“文件夹”而是把src/、docs/、package.json、README.md这些当作仓库根目录下的内容。理解这一点很重要——你要上传的文件夹本身应该作为 GitHub 仓库的根目录内容去准备而不是把“文件夹外套一个文件夹”整个丢上去。很多新手传完之后发现 GitHub 上多了一层嵌套就是没有搞清楚仓库与本地目录的对应关系。1.2 三种上传方式各自适合谁同是上传文件夹不同场景下最优解是不一样的上传方式上手难度适合场景核心特点网页端拖拽上传最低一次性上传、不打算长期维护无需安装软件但只适合一次小规模上传命令行 Git 操作中等长期开发、需要版本管理一次配置之后随时同步最主流的工程师用法GitHub Desktop偏低想可视化操作又想保留版本能力官方客户端不敲命令也能完成大部分流程我见过不少初学者在网页端拖拽上传成功一次之后就把它当成了唯一方式。短期没问题但一旦项目进入持续迭代网页端上传的弊端会非常明显你改了一个文件想更新远程仓库网页端只能要么删除重传要么逐文件覆盖完全没有版本记录。走到那一步你还是要回来学命令行。所以我下面虽然把网页端写在最前面但命令行和桌面端才是真正值得花时间掌握的东西。2. 方式一网页端拖拽上传零命令行入门2.1 新建仓库时的关键设置网页端上传的第一步是先在 GitHub 右上角点号选择New repository。这里有几个设置项需要说明一下它们不是随便填的Repository name仓库名。建议和本地文件夹同名方便对应。比如本地文件夹叫my-project仓库名也写my-project。Description描述可选。填上之后会给仓库一个一句话说明在仓库列表页和分享链接时都能看到。Public / Private公开仓库任何人都能看私有仓库只有自己和被邀请的协作者能看。如果只是学习用途选 Public 没问题如果有敏感代码或者不想被搜索到选 Private。Add a README file是否同时生成 README 文件。很多教程会建议勾上因为 README 会让仓库更规范但如果你打算马上上传本地文件夹而且本地已经自带 README就不要勾避免后续出现文件冲突。新仓库创建页面中间的.gitignore和 license 选择动手上传本地已有项目时可以不选本地文件夹里该带的东西都已经带了。2.2 拖拽上传的完整操作与界面说明仓库创建完成后会进入一个空仓库页面里面通常会有一段建议你“connect to GitHub / push an existing repository / import code”的提示文字。注意这段提示区域它就是网页端传文件的入口所在页面中央会出现一段带快捷链接的说明其中有一个uploading an existing file链接点它就会跳到上传页。更直接的方式是仓库页面点Add file下拉菜单选择Upload files。进入上传页之后你会看到一个虚线框上面写着 “Drag files here to add them to your repository” 或 “choose your files”。把你本地的整个项目文件夹直接拖进这个区域。是的整个文件夹可以一次拖进去子目录结构会自动保留。拖动完成后页面上会列出所有待上传文件同时上方有一个 Commit changes 区域需要你填写Commit message提交说明。默认内容通常是 “Add files via upload”。选好提交说明后点绿色的Commit changes按钮。这个过程中GitHub 会自动为这个仓库生成一个main分支默认分支你拖进去的所有文件会一次性出现在根目录下。由于这个页面是“提交”的逻辑不是“保存草稿”的逻辑所以点完按钮之后文件就已经进入仓库别人如果能看到这个仓库立刻就能看到全部内容。2.3 网页端上传的两条硬性限制网页端上传用起来傻瓜但限制也非常明确提前知道能省去很多排查时间。第一单个文件不能超过 100MB。GitHub 对所有通过网页端、Git 命令推送的内容都有 100MB 单文件限制超过这个大小会直接拒绝。如果一个文件刚好 90MB 左右表面上能传上去但仓库性能会受影响。真正的大文件要往前走 Git LFS 或者存储在其他对象存储平台这是后话。第二拖拽上传在文件数量较多时会比较吃力。如果你的项目有几千个小文件比如某个 node_modules 目录、构建产物目录网页端上传页会卡顿甚至超时。这类目录本来也不应该被传到 GitHub 上正确做法是本地先用.gitignore过滤掉具体在命令行部分会讲。3. 方式二命令行 Git 操作正式走入开发者的日常3.1 为什么要专门学命令行网页端拖拽看着方便但真实项目里大家几乎不会用网页端去“上传文件夹”原因很实在网页端适合一次性导入但项目一旦开始迭代每次改文件都要打开网页效率太低。网页端无法保留同一文件的历史版本你覆盖一个文件后原来的版本就消失在时间线里Git 的可追溯能力完全发挥不出来。网页端对文件名大小写、目录移动、大批量改名这些操作支持不友好命令行里一个mv就能解决的问题网页端可能要折腾半天。所以如果这篇文章只让你记住一件事那就是GitHub 的灵魂在 Git 本身而上传文件夹只是 Git 里的一个小操作。命令行方式学会了等于你拿到了这个工具链的完整使用权。3.2 本地仓库初始化的完整命令序列假设你本地有一个项目目录叫my-project里面已经写好了代码。打开终端Windows 用 Git BashmacOS/Linux 直接开 Terminal依次执行cd /path/to/my-project # 进入项目目录 git init # 把当前目录初始化为 Git 仓库执行完git init后目录里会出现一个隐藏的.git文件夹它记录着仓库的全部版本信息平时不要动它也不需要提交它。接下来你需要检查一下当前目录里所有文件的状态git status这条命令会显示当前目录里哪些文件是“未跟踪”状态它们会以红色文字列出来。如果你在列表中看到node_modules/、.dist/、__pycache__/这类明显是依赖包或构建产物的东西就要先创建.gitignore文件把它们排除掉而不是全部一股脑提交进去。3.3 .gitignore 的创建与作用.gitignore是 Git 项目里的一个特殊配置文件写着哪些文件或文件夹不需要纳入版本管理。它的格式很简单一行一个规则# 依赖目录 node_modules/ # 构建产物 dist/ build/ # 系统文件 .DS_Store # 环境变量配置通常包含密钥 .env # Python 缓存 __pycache__/ *.pyc创建方式是直接在项目根目录新建一个.gitignore文件把上述内容复制进去再按需增减。这样后续执行git add .的时候Git 会自动跳过这些目录不会把几万个依赖文件推上 GitHub。这一步很关键。很多上传时显示“文件太多”“上传超时”的新手项目十有八九是没写.gitignore就把整个依赖目录拖了进去。3.4 标准的提交与推送流程当文件状态检查完毕就可以正式提交了git add . # 把当前目录所有文件加入暂存区 git commit -m feat: 初始化项目 # 创建提交记录 git branch -M main # 将默认分支名改为 main git remote add origin https://github.com/你的用户名/仓库名.git git push -u origin main这里解释几个关键点懂原理之后出现报错你会更容易定位。git add .是把文件放入暂存区这个操作不会立刻提交可以理解为“打包准备中”。git commit -m 说明才真正打了一个提交包其中的说明文字最好能清晰描述这次提交做了什么比如feat: 初始化项目、fix: 修复登录接口超时问题。这样后续回看历史记录时每一条提交在改什么一目了然。git remote add origin是把本地仓库和一个远程仓库地址关联起来origin是默认的远程仓库名。地址需要在 GitHub 仓库主页拿到格式通常是https://github.com/用户名/仓库名.git或者 SSH 形式的gitgithub.com:用户名/仓库名.git。git push -u origin main则是把本地main分支推送到远程origin的main分支。参数-u会建立本地分支与远程分支的关联之后你在本地直接输入git push就能完成推送不用每次带参数。执行完git push之后运行git status如果提示 “Your branch is up to date”再刷新 GitHub 仓库页面就能看到全部文件按照本地目录结构排列好了。3.5 首次推送时的身份验证问题第一次执行git push时终端通常会弹出一个登录窗口或者要求输入用户名密码。需要特别注意的是现在的 GitHub 已经不再支持使用账号密码进行 Git 操作。你需要用以下两种方式之一完成身份验证Personal Access Token个人访问令牌在 GitHub 设置里选择 Developer settings - Personal access tokens生成一个令牌复制后当作密码粘贴进终端。SSH 密钥在本地生成 SSH 密钥对把公钥配置到 GitHub 的 SSH keys 设置中。配置完成后远程地址要使用 SSH 形式。我个人的建议是如果你主要在个人电脑上开发直接配置 SSH 密钥最省心。提交推送时不需要反复验证而且 token 过期或者忘记刷新带来的“push 突然失败”问题会少很多。生成命令也不复杂ssh-keygen -t ed25519 -C 你的邮箱example.com一路回车之后把生成的公钥默认路径在~/.ssh/id_ed25519.pub内容复制到 GitHub 的 Settings - SSH and GPG keys 里即可。4. 方式三GitHub Desktop 客户端图形界面里的版本控制4.1 为什么推荐官方桌面客户端命令行虽然专业但不是所有人都愿意每天面对终端。GitHub 官方推出的 GitHub Desktop 客户端给了一条中间路线用图形界面完成仓库同步、提交、推送、分支切换等常见操作底层依然使用 Git 逻辑不会让你失去版本控制能力。如果你之前完全没用过 GitHello World 项目又不需要复杂的合并操作桌面端可能是体验最好的入口。它安装后直接登录 GitHub 账号免去 token 和 SSH 配置。4.2 用桌面端上传本地文件夹的步骤安装并登录 GitHub Desktop 后点击左上角File-Add Local Repository选择你本地项目文件夹所在的路径。软件会识别到这个目录还不是 Git 仓库询问是否要创建一个仓库点Create a repository这一步相当于执行了git init。仓库创建完成后桌面端主界面会列出当前目录的所有变更文件。这里可以直观看到每个文件是新增、修改还是删除状态。界面下方有Summary和Description两个输入框分别对应提交说明的标题和正文填好之后点Commit to main。提交完成后点击右上角的Publish repository或Push origin会弹窗询问仓库名称和 Public/Private 设置确认后文件就会推送到 GitHub。桌面端好处是你随时能看到“接下来会发生什么”——比如提交前能预览文件列表推送前能看到缺少远程仓库这些信息对新手极其友好。4.3 桌面端与命令行混用的注意事项实际开发中很多人是两种方式混着用的日常提交推送用桌面端遇到复杂历史处理比如 rebase、cherry-pick时切回命令行。这种情况完全可行因为桌面端和命令行操作的是同一个.git目录状态是双向同步的。需要注意的一点是如果你在同一仓库里既用桌面端又用命令行建议不要同时打开两个工具进行操作。Git 的部分操作是串行的两个工具同一时间修改同一份状态文件偶尔会出现 index.lock 文件冲突导致报错 “Unable to create …/index.lock: File exists.”。遇到这个报错把桌面端退出再等一两秒删除.git/index.lock重新操作即可。5. 上传文件夹时最典型的报错与排查链路5.1 fatal: refusing to merge unrelated histories这是新手最容易撞到的一面墙。场景往往是你在 GitHub 网页端先创建了一个仓库还勾选了生成 README之后又在本地执行了git init并提交了本地文件最后git pull或者git push时Git 认为本地和远程两个仓库没有任何共同的历史于是拒绝合并报出refusing to merge unrelated histories。排查思路很简单本地仓库和远程仓库是两条互不相关的历史线。要打通它们有两种方案如果本地内容才是你真正想保留的远程那个仓库只是空壳或者只有一个初始 README建议直接在本地删除远程关联然后重新关联一个空的远程仓库git remote rename origin old-origin git remote add origin https://github.com/用户名/新仓库名.git git push -u origin main如果确实需要把本地和远程两边历史强行合并可以在git pull时加参数git pull origin main --allow-unrelated-histories但我不推荐新手为了保留两边历史而强行合并除非你已经完全理解合并产生冲突的后果。上传文件夹这件事保持本地历史干净比保留远程那几个初始文件重要得多。5.2 remote: error: File is larger than 100 MB前面提到过这个限制真遇到时先不要慌按下面的顺序自查先找到那个超大的文件git rev-list --objects --all | grep -E $(git count-objects -vH | grep size-pack)这个命令逻辑有点绕更简单的做法是检查项目里是不是有模型文件、视频、压缩包等大文件。理论上超过 100MB 的文件就不应该出现在常规 Git 仓库里。如果这个文件是误传进来的需要在提交历史里把它彻底移除。注意只删除文件再提交一次还不够因为文件还残留在历史记录中。用下面这套命令处理比较稳妥谨慎操作最好先备份整个目录git filter-branch --index-only --force --index-filter \ git rm --cached --ignore-unmatch 大文件路径 \ --prune-empty -- --all清理完成后再正常git add .、提交、推送。如果文件确实需要保留在项目里那就配置 Git LFS。GitHub 默认免费额度是 1GB 存储和每月 1GB 流量个人项目通常够用。5.3 fatal: Authentication failed for https://github.com/...场景是执行git push时明明输入了正确的用户名密码却始终报身份验证失败。原因上文已经提过GitHub 不接受账号密码作为 Git 提交凭证。解决思路检查远程地址是不是 https 形式如果是改成 SSH 形式再重试git remote set-url origin gitgithub.com:用户名/仓库名.git如果坚持用 HTTPS必须在弹出的验证框里输入 Personal Access Token 而不是密码。token 生成时可以勾选repo权限范围过期时间按自己需要选我一般选 90 天到期后换一个新的即可。5.4 上传后 GitHub 页面看不到内容有几次用户明明本地执行了git push终端也显示成功但刷新 GitHub 网页却发现什么变化都没有。排查顺序可以这样走先确认推送的分支名。GitHub 新建仓库默认分支是main如果你的本地分支还停留在master推送后内容都在master分支上网页默认显示main分支自然看不到。用git branch -M main改名后重新推送。再确认是否推到了正确的远程地址。执行git remote -v检查 origin 对应的 URL 是不是目标仓库。之前我在一个项目里把远程地址填错成了另一个同名仓库导致推送成功但文件出现在完全无关的仓库里排查了好一阵。最后确认文件是否真的被提交了。git log --oneline -5看一下最近的提交记录如果显示nothing to commit或者没有提交记录说明文件只进入了暂存区还没有变成一次提交。6. 结合我多次实操经验总结的几条建议在这几种方式都来回用过多轮之后我自己的日常流程已经固定下来了分享出来供你参考。新项目开始的第一天就执行git init并立刻创建.gitignore和README.md。不要等项目写了一半才想起来初始化仓库——等到文件几百个的时候才开始做版本管理初始化时那一大堆文件会毫无信息量地全部积成一条提交以后想定位某段代码是哪次改动引入的难度会大很多。每次提交时尽量让提交说明有语义。哪怕你只有一个人写代码三个月后回看历史记录“update”和“update again”这种提交说明基本帮不上忙而一句“fix: 修复用户头像上传后无法显示的问题”能让你少花很多时间去翻代码差异。如果遇到不确定应该用网页端、命令行还是桌面端的时候问自己一个问题一个月后我还会往这个仓库里加东西吗如果有这个可能直接选择命令行或者桌面端并把远程关联好。网页端拖拽上传在今天看确实爽快但从长期维护的角度看它只适合不打算继续更新的静态一次性导入。上传文件夹这件事本身等你把仓库、提交、分支、远程这几个概念全部串起来之后回头看会发现它只是 Git 日常操作里最简单的一环。上面这些坑我都亲自踩过写下来希望能帮你把这些隐蔽的弯路一次绕过去。