1. 为什么要把文件夹传到 GitHub先弄懂核心思路很多人在接触 GitHub 之前可能只是在网上下载过开源软件或者看过别人分享的项目链接。等到自己手里有一个完整的项目文件夹想把它传到 GitHub 上托管、备份、给同学评审或者发布成开源项目时才发现操作起来比想象中麻烦。尤其是文件夹里文件一多网页端拖拽上传经常中途断掉命令行又不知道该敲什么很容易卡在第一步。这篇分享就是围绕“上传文件夹到 GitHub”这件事把网页端和命令行两种方式都拆开讲清楚。我会尽量按照一步步配图的思路把每个操作节点、每条命令的含义、每一个容易踩坑的地方都说明白。不管你是第一次接触 Git 的纯新手还是之前只会在网页上点来点去、想补上命令行这块短板的开发者这篇内容都可以直接拿来参考。先说核心结论如果文件夹里文件数量不多比如几十个以内用网页端拖拽上传最快如果文件夹结构复杂、文件数量多、之后还要持续更新那就老老实实用 Git 命令行。两种方式不冲突甚至组合使用很常见——平时用命令行提交偶尔在网页端改一行配置或传一个小文件。1.1 网页拖拽和命令行到底选哪个很多人上来就会问GitHub 网页上不是也有 Upload files 按钮吗为什么还要学 Git 命令这个问题的答案取决于你“上传文件夹”这个动作是一次性的还是长久的。网页端上传的本质是一个手动把文件搬运到仓库的过程你打开仓库页面点 Upload files然后把文件拖进网页。听起来挺方便但一旦文件多、体积大或者文件夹嵌套多层网页端就开始力不从心。浏览器上传断掉一次、网络抖动一下整个流程就要重来。而且网页端默认不会保留你本地的 Git 提交历史如果本地已经有项目演进过程这些记录就丢了。命令行上传则完全不一样。它背后是 Git 这套版本管理工具在工作本地所有文件先被 Git 记录下来形成一个一个提交commit然后一次性推送到 GitHub。这就像你在本地写日记Git 帮你把每一天的记录归档好网络好的时候一起寄出去网页端则像是你手动一份一份复印邮寄简单但很笨重。所以我的建议是分场景一次性分享、文件少可以网页端拖拽文件多、结构复杂、将来还要继续改必须先学会命令行。这篇文章会把两种方式都讲透你按自己的情况选就行。1.2 一个比喻理解 Git 和 GitHub 的关系很多教程上来就教你敲命令却不解释为什么要有这套东西。我习惯用一个比喻Git 是你的本地“时光机备份系统”GitHub 是你的“云端共享仓库”。你在本地建好一个文件夹Git 可以让这个文件夹的每一个阶段变化都被记录成一个快照。你改了一行代码保存一次过几天又改了一行再保存一次。每一次保存就是一次 commit。这些 commit 都留在你本地完全不需要网络。而 GitHub 是一个远程仓库当你想把本地这些快照同步到云端让同事看到、让别的电脑拉取或者单纯防止电脑硬盘坏了就用 git push 把本地记录推送上去。所以“上传文件夹到 GitHub”这个过程用行话说其实是把本地文件夹初始化成 Git 仓库 → 提交一次版本快照 → 关联到 GitHub 上的远程仓库 → 把自己本地的快照推送上去。理解了这个流程后面所有命令都是在执行这几个动作。怕就怕不了解全貌的人敲完 git init 就不知道下一步干嘛或者 push 的时候报错也不知道去哪查。2. 动手前的环境准备任何实操类教程环境出问题都会让后面的步骤全部白费。所以我把准备阶段单独拿出来说不想让环境问题成为劝退原因。2.1 注册账号与安装 Git 客户端GitHub 账号的注册这里不展开去官网首页就能看到注册入口用邮箱注册、验证一下邮箱就行。注册好之后要记住你的用户名因为后续远程仓库地址里会用到。本地则需要安装 Git 客户端。Windows 用户去 Git 官网下载对应版本安装的时候一路默认选项即可macOS 用户装了 Homebrew 的话可以 brew install git也可以直接下载官方安装包。安装完成后在终端或命令行里输入 git --version能看到版本号说明安装成功。这一步容易出问题的是Windows 用户安装完 Git 之后进入 Git Bash 还是命令提示符里操作我的经验是统一用 Git Bash它模拟了 Linux 终端环境路径解析、命令兼容性都更好也方便后续使用常见的 Unix 命令。如果在 cmd 或者 PowerShell 里操作部分命令的写法或路径分隔符会有差异容易让新手困惑。2.2 配置身份信息名字和邮箱Git 在每次提交时都会记录一个作者信息这个信息就来自你本地的全局配置。第一次安装完 Git 后必须设置一下否则提交时可能会报错或者提交记录里显示的不是你想展示的名字。打开终端分别执行git config --global user.name 你的GitHub用户名 git config --global user.email 你的注册邮箱这里有一个细节Git 本地配置的身份信息最好和 GitHub 账号保持一致。这样推送出去后提交记录上的作者信息才正确对应到你的账号。如果你在本机同时处理多个项目想对某个项目单独设置不同身份可以去掉 --global在项目目录内重新执行一次配置作用范围就变成只对当前仓库生效了。2.3 SSH 密钥配置免密推送的关键第一次推送时很多人的第二道坎就是认证问题。GitHub 提供了两种常见认证方式HTTPS 和 SSH。HTTPS 方式最简单推送时输入 GitHub 的用户名和密码现在更常用的是 Personal Access Token简称 PAT即可不需要额外配置缺点是每次推送都要输凭据配置了凭据管理器才能免密。SSH 方式则是通过密钥对进行身份认证本地生成一对私钥和公钥公钥放到 GitHub 账号的 SSH Keys 设置里之后 push 和 pull 都不用再输密码一劳永逸。我推荐大家用 SSH 方式。生成密钥的命令是ssh-keygen -t ed25519 -C 你的注册邮箱一路回车即可。生成后使用 cat ~/.ssh/id_ed25519.pub 查看公钥内容复制它然后到 GitHub 页面右上角头像 → Settings → SSH and GPG keys → New SSH key粘贴保存。最后验证ssh -T gitgithub.com如果显示 Hi 你的用户名! Youve successfully authenticated...说明 SSH 已经通了。提示如果你在生成密钥时设置了 passphrase每次使用私钥时还会要求输入。图省事可以留空安全性要求高的话设置一个也不算坏事。我日常个人项目都留空公司电脑按公司规定来。3. 用命令行上传文件夹详细实操环境准备完成后就可以正式操作了。这部分会从创建本地仓库开始一步步走到成功推送到 GitHub。中间涉及几条核心命令每条我都会解释含义而不仅仅是让你照着输入。3.1 第一步初始化本地仓库并提交假设你本地有一个文件夹叫 my-project里面是你准备好的项目文件。先在终端里进入这个文件夹cd /path/to/my-project然后在项目根目录里初始化 Git 仓库git init执行后项目目录下会多出一个隐藏的 .git 文件夹Windows 下默认隐藏需要在文件管理器里开启“显示隐藏项目”才能看到。这个 .git 文件夹就是 Git 的本地数据库里面记录着所有版本快照和配置信息。这时候你可以先看一眼当前项目里有哪些文件git status这个命令会列出所有未跟踪的文件和改动。初次使用的人常常忽略这一步直接 commit结果把一些不该提交的临时文件也提交上去了。所以建议养成习惯git status 能帮你先确认状态。如果有不想提交的文件比如本地开发产生的临时文件、日志、编译产物、密钥等就要在项目根目录创建一个 .gitignore 文件把需要忽略的内容写进去。比如node_modules/ dist/ *.log .env这个文件可以说是 Git 项目里的“安检名单”写到里面的路径和规则都会被 Git 自动忽略。没有 .gitignore 的项目传到 GitHub 上往往带一堆垃圾文件别人看着头疼自己也容易传错。确认要提交的文件没问题后先把它们加入暂存区git add .这条命令把当前目录下所有未忽略的文件都加入暂存区。如果只想提交某个具体文件可以用 git add 文件名。暂存区这个东西你可以理解为一个“待打包区”——文件先放到这里确认无误后再统一打包成一个 commit。接着提交git commit -m 第一次提交项目文件双引号里的内容是本次提交的说明。命名建议写清楚这次改了什么方便以后回看。首次提交我一般喜欢写成 init project 或 项目初始化简明扼要。到这里本地仓库已经建立完成文件也完成了第一次版本快照。3.2 第二步创建远程仓库并关联本地搞定了接下来在 GitHub 上创建一个空的远程仓库。登录 GitHub点击页面右上角的 号选择 New repository。仓库名建议和本地文件夹名保持一致方便识别。描述可以随便写选 Public 还是 Private 按你的需求来——想公开分享给所有人看就选 Public只想自己或协作者看到就选 Private。有一个关键点初始化仓库的页面会问你是否要添加 README、.gitignore 或 license。如果你打算先把本地文件夹推上来这些都不要勾选保持空仓库状态否则后续容易遇到本地和远程历史不一致的问题。创建完毕后GitHub 会显示一个页面里面有几段代码其中包含远程仓库地址。这时候回到本地终端把远程仓库关联到本地git remote add origin gitgithub.com:你的用户名/仓库名.git如果你想用 HTTPS 方式地址就是 https://github.com/你的用户名/仓库名.git。用哪个取决于你前面配置的是 SSH 还是 HTTPS 凭据。SSH 方式推荐使用上面的 git 开头地址。关联完可以用 git remote -v 查看当前仓库关联了哪些远程地址。看到两条记录fetch 和 push说明关联成功。3.3 第三步推送本地代码到远程远程仓库关联好了现在做真正的“上传”动作git push -u origin main这里有一个高频坑很多教程里写的是 git push -u origin master其中 master 是旧版 Git 的默认分支名。而 GitHub 在 2020 年后把新仓库默认分支名改成了 main。你的本地仓库在 git init 后默认分支名取决于你 Git 客户端配置或版本可能是 master也可能是 main。如果不确定先看git branch命令行会显示当前所在分支。如果你的本地分支是 master但 GitHub 仓库默认分支是 main直接推送时可能出错。解决方式很简单推之前先把本地分支改名执行git branch -M main这条命令把当前分支重命名为 main。-M 是大写的 M表示强制重命名即使目标分支已存在也会覆盖。改完再执行推送git push -u origin main-u 参数的意思是“记住本次推送对应的远程分支”以后你只需要 git push 就能直接推送不必每次写完整分支名。第一次推送成功后回到 GitHub 仓库页面刷新就能看到文件夹里的所有文件都传上去了。3.4 后续更新项目怎么推送上传一次文件夹只是开始。项目是活的过几天你又改了代码、加了文档想同步到 GitHub。这时候流程比第一次简单很多不需要再初始化、再关联远程只需要三步git add . git commit -m 这次改了什么 git push很简单对吧git add 把改动放入暂存区git commit 生成一次新快照git push 把快照同步到远程。很多教程会把“使用 Git 管理项目”包装得很复杂其实日常高频操作就是这三条命令。需要注意的一点git add . 会把当前项目目录下所有有变动的文件都加进去如果只想提交部分文件请改成 git add 具体路径。提交信息也尽量描述清楚因为 commit 记录会长期保留在仓库历史里写得太随意过几个月你自己都看不懂当初改了什么。4. 网页端直接上传文件夹适合小批量场景如果只是临时想传一个文件夹里面文件不多、体积不大直接走网页端会更快。这种方式不用装 Git不用敲命令浏览器打开就能操作。4.1 网页端创建仓库并上传文件网页端上传的前提是先有一个仓库。如果你还没建按上一节的方法创建一个空仓库然后进入仓库页面点击 Add file → Upload files就会进入拖拽上传页面。这时候你可以把整个文件夹直接拖进浏览器的上传区域。GitHub 会自动遍历文件夹里的所有文件并保留文件夹层级结构。拖进去之后页面底部会要求你写一条提交信息默认是 Add files via upload可以改成一个更清晰的文件描述。最后点击 Commit changes上传就完成了。这个流程看起来很轻松但有几个限制需要提前知道网站对单次上传文件大小有限制单文件超过 100MB 会直接失败实际上我建议超过 50MB 就别用网页端了上传过程依赖网络稳定性中途断网会全部重来另外网页端也不支持拖拽上传空文件夹因为 Git 本身不跟踪空目录。4.2 网页端如何建文件夹文件名加斜杠很多人不知道网页端加文件时文件名里如果带了斜杠 /GitHub 会自动认为这个文件放在对应的子目录里从而实现直接新建文件夹的效果。比如我要在仓库里建一个 docs 文件夹里面放一个 README.md只需要在文件名输入框里写docs/README.mdGitHub 会在提交时自动创建 docs 这个目录结构。这个技巧在没有本地环境、只想快速整理仓库目录结构时非常实用。不过它也确实有局限一次只能建一条路径如果目录层级特别深操作起来繁琐而且无法直接创建空文件夹必须放至少一个文件占位。常见的做法是先在文件夹里放一个 README.md 或 .gitkeep 文件让目录被 Git 跟踪。4.3 网页端上传的限制与取舍网页端上传毕竟不是一个为“大规模代码托管”设计的路径。文件多了以后上传列表会有很多行每传一个文件都会发起一次请求浏览器可能卡顿甚至崩溃。而且网页端没有办法处理文件名冲突、覆盖更新、历史记录保留这类精细控制。我见过不少朋友用网页端传文件传完当时觉得很顺利等到改了一个文件想再更新时发现只能把整个文件重新上传一遍仓库里还留着旧文件。相比之下命令行方式天然就处理了“变更”而不是“重新上传”这件事所以日常维护项目命令行才是正路。所以在我的实践里网页端的定位是“应急工具”临时补一个 README、改一行错误配置、传一两张图片这时候效率是比命令行高的。但如果是一个文件夹、一个项目打包上传请用命令行方式完成。两者组合使用才是效率最高的状态。5. 常见问题与排查技巧上传文件夹这件事动作本身不难难的是遇到报错不知道怎么处理。我把自己这几年实际操作中高频踩坑的问题整理成一个速查表遇到问题可以按图索骥。5.1 高频报错对照表报错信息出现原因解决方式fatal: not a git repository当前目录不是 Git 仓库确认是否执行过 git init是否在正确的项目目录里error: src refspec main does not match any本地没有 main 分支或没有提交过任何内容先执行 git add . 和 git commit再推送failed to push some refs远程有本地没有的提交记录先 git pull --rebase origin main再 pushrepository not found远程仓库地址写错或没有权限检查仓库名、用户名是否一致确认是否 Private 仓库Permission denied (publickey)SSH 密钥未配置或公钥未添加到 GitHub重新检查 ssh-keygen 生成的公钥确认添加到 GitHub 设置里remote origin already exists已经关联过远程仓库先 git remote remove origin再重新关联unable to access ... SSL certificate problem本机网络或 Git 配置异常检查网络环境如果公司内网有特殊设置咨询网管或更新 Git 版本这套速查表覆盖了纯新手上路时 90% 的报错场景。遇到报错先别慌把关键错误信息复制出来在表格里找一找大多数都能定位到原因。5.2 每次都要输密码文件太大这些坑提前避开使用 HTTPS 方式推送时第一次会让你输入用户名和密码但现在已经不能用账号密码直接认证了而要用 Personal Access TokenPAT。如果你发现密码输进去报错大概率就是没换成 token。生成 PAT 的路径是 Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token生成时勾选 repo 权限然后把生成的字符串当密码用。注意这个 token 只显示一次一定要复制保存。另一个高频问题是大文件。GitHub 对单文件有 100MB 的硬限制而仓库整体体积也不适合做得太大。如果你项目里有超过 50MB 的文件比如模型文件、数据集、视频素材强烈不建议直接推到普通 Git 仓库。Git 对大文件的处理效率极低仓库体积膨胀后每次 clone 和 fetch 都会变慢团队成员体验也很差。这种情况应该用 Git LFSLarge File Storage或者换用其他对象存储服务把大文件单独托管。Git LFS 的接入方式不复杂安装插件后在项目里用 git lfs track *.zip 之类的命令声明哪些文件走 LFS 即可。还有一个很多人容易忽略的点文件名大小写。Git 默认情况下不区分文件名大小写变化比如你本地把 README.md 改成 readme.md推上去后在 GitHub 上可能仍然显示旧名字。解决方法是 git config core.ignorecase false 或执行 git mv 强制改名。这个问题在团队协作时尤其容易引发混乱因为不同操作系统对大小写的处理方式不一致。5.3 让仓库保持整洁的几个习惯项目传上去只是起点仓库能不能保持清爽靠的是日常习惯。我这里分享几个自己坚持了很久的原则。第一凡是生成物都不进仓库。编译产物、依赖包、日志文件、IDE 配置文件这些全部写进 .gitignore。别人 clone 项目后自己重新安装依赖、编译生成即可仓库里只保留源代码和必要配置。这样仓库体积小、对比清晰review 起来也轻松。第二提交粒度要小。不要攒了一个月的改动一次性 commit那样提交信息根本没法起。理想状态是一次提交对应一个完整的小功能或一次 bug 修复提交信息里说清楚“做了什么”和“为什么做”。这个习惯在出问题时特别有用回溯排查时会轻松得多。第三推送前先看 git status。我见过太多人闭着眼睛 git add . 然后 push结果把 .env 密钥文件推到了公开仓库过了一个小时才有人提醒。养成推送前 git status 确认一遍的好习惯能避开很多无法挽回的泄露事故。最后再分享一个小技巧上传完整个文件夹之后很多人不知道还有一个常用组合在 GitHub 仓库页面按一下句号键英文状态下的 .浏览器会直接打开一个在线版的代码编辑器你可以在网页上直接修改文件、新建文件甚至执行 Git 操作。配合之前讲的“文件名加斜杠建目录”技巧基本能覆盖所有应急场景。再配合命令行推送日常代码整个工作流就非常顺了。我个人在实际操作中的体会是上传文件夹到 GitHub真正难的从来不是命令而是理解 Git 的工作流。一旦你明白了本地提交和远程仓库的关系后面所有命令都只是不同场景下的重复组合。按这篇文章的方式先把第一个文件夹传上去再跑通一次日常更新剩下的就是在使用中慢慢加深理解了。