企业官网建设流程全解析

刚把本地一个写了两星期的项目文件夹往GitHub上拖，网页转了几个圈，最后只传上去几个散文件，其余全部超时——这是很多人第一次“GitHub上传文件夹”的真实体验。“上传文件夹”四个字听着简单，实际上涉及网页端操作、命令行Git、仓库权限、文件大小规则、认证方式这些东西。这篇博文我按自己的实战经验，把GitHub上传文件夹这件事从头到尾捋一遍：新手可以先绕过命令行用网页端，追求效率和安全就得掌握标准Git流程，再往后还会遇到大文件、海量小文件、报错排查这类进阶问题。适合刚接触GitHub、想把整个项目文件夹完整推到远端仓库的人看，也适合已经会基础操作但一直被各种报错卡住的读者对照排查。

提示：全文以公开仓库为默认场景，私有仓库的认证逻辑会顺带说明。

1. 网页端拖拽上传：新手最容易踩的隐形雷区

1.1 网页端到底能传什么、不能传什么

GitHub网页端的仓库页面确实支持直接把文件夹从本地拖进浏览器窗口，松开鼠标后它会自动递归上传里面的文件。这个功能对特别小的文件夹、临时分享场景来说够用，但它有四个硬限制，很多人传着传着就翻车。

第一，单文件超过100MB直接拒绝，超过50MB会收到警告。GitHub对网页上传的文件大小控制比命令行更严：命令行上限是单文件100MB，网页拖拽在几十MB以上的文件上就经常不稳定。第二，通过拖拽一次上传的文件数量不宜太多，几百个以上的小文件很容易在传输过程中超时，页面卡在“Uploading files”再没反应。第三，拖拽上传会把整个文件夹完完整整塞进仓库根目录，如果你想先整理目录结构、排除掉某些不需要的文件夹，网页端做不到——你得先传上去再在网页里一个一个删。第四，空文件夹根本不会被Git跟踪，Git本身就不认识“空目录”这种概念，网页端、命令行都一样。

明白了这四条，你就知道网页端的定位是应急与演示，不是一个正经项目进仓库的方案。临时分享代码片段、给学生展示小练习、验证一个思路的产出，这些场景用它没问题；但凡这个文件夹是你打算持续维护的项目，网页端连入门都算不上。真正的上传入口在你的本机终端里，也就是第2章要展开的标准Git流程。

1.2 空文件夹与.gitkeep的隐藏规则

Git不跟踪空文件夹这一点值得单独说。很多人本地项目里建了一堆空的目录用来规划未来结构，比如logs/、uploads/、temp/，推到GitHub上一看全没了，还以为是上传失败。

这是Git的设计逻辑：Git跟踪的是文件内容的变化，目录只是“装有这些文件的路径前缀”。目录里没有任何文件，就没有任何需要记录的内容。解决办法很经典：往空目录里放一个占位文件，行业惯例叫.gitkeep，名字没有特殊含义，只是约定俗成，内容是空的或一行注释都可以：

mkdir -p logs uploads temp touch logs/.gitkeep uploads/.gitkeep temp/.gitkeep git add . git commit -m "keep directory structure"

提交之后再看，这些目录就都在了。这也是为什么你不要在网页端辛辛苦苦创建空文件夹——它一刷新就消失，因为Git根本不认。

1.3 什么情况下网页端还能凑合用

我自己对网页端的使用原则：单个文件夹小于5MB、文件数量小于20个、不需要排除文件、且只是临时共享代码片段时，用网页拖拽快速传一次完全没问题。比如你写了个小的Python脚本文件夹想给朋友看，三个文件加起来几十KB，直接拖进去，写个简短commit message，点Commit changes，搞定。

但一旦文件夹里有node_modules、构建产物、上万个图片素材这类东西，网页端就是给自己挖坑。老老实实走命令行，下面这个标准流程才是主力方案。

2. 命令行上传：从git init到git push的标准链路

2.1 先别急着敲命令：环境与仓库准备

命令行上传文件夹，本质是把本地文件夹变成一个Git仓库，再和一个远端仓库建立关联，最后把提交推上去。整个过程只需要装好Git，不需要其他环境。

安装Git之后，第一步先设置身份信息，Git会把这两个信息写进每一次提交记录里。很多人忽略这步，提交时弹“Please tell me who you are”的红色报错，卡在原地：

git config --global user.name "你的用户名" git config --global user.email "你的邮箱"

同一个开发机只设置一次，全局生效。这两行不设置的话，即使git commit临时能过，提交记录里也会出现一堆怪异的默认值，协作时非常难追溯。

同时去GitHub网页端新建一个空仓库，建议不要勾选“Add a README file”，后面会少一个合并冲突的坑（具体原因在第5章说）。仓库建好之后，页面上会给你一个远程地址，形式通常是 https://github.com/用户名/仓库名.git，先复制下来备用。

2.2 从git init到git push的完整七步

下面这段标准流程是我每次上传文件夹都会走的完整链路，一步一步解释每条命令在干什么：

# 1. 进入你的项目文件夹 cd /path/to/your/project # 2. 把当前文件夹初始化为Git仓库 git init # 3. 把文件夹里所有文件加入暂存区 git add . # 4. 查看将要提交的文件列表，确认没有不该传的东西 git status # 5. 提交，写一句有意义的说明 git commit -m "initial commit: import project folder" # 6. 把默认分支命名为main（GitHub默认分支名是main） git branch -M main # 7. 关联远端仓库，然后推送 git remote add origin https://github.com/用户名/仓库名.git git push -u origin main

第3步的git add .把当前目录下所有内容加入暂存区。之所以用“暂存区”这个说法，是因为Git把提交分成了两步：先选择要提交的内容（add），再打包成一次提交（commit）。这个设计让你有机会在提交前反悔——只要还没commit，随时可以git reset把文件撤出暂存区。

第6步的-M是强制重命名当前分支到main。早期Git默认分支名是master，现在主流平台默认用main，这一行是把本地分支名统一过去，避免后续推送到远端时分支名对不上。

第7步里-u的含义是“设上游”，告诉Git本地的main分支跟踪远端的main分支。设置之后，以后每次推送只要敲git push就行，不用再带参数。

2.3 提交粒度与commit message的基本功

一次提交应该只做一件事，这句话是Git协作里最容易被忽略的规范。上传整个文件夹时，第一次提交写“initial commit”没毛病，但后续你更新文件夹里某几个文件，最好按功能拆分提交，而不是攒一堆改动再一次性commit。

打个比方：Git的提交记录就像是项目的时间轴，commit message是这条时间轴上的注释。别人（包括三个月后的你自己）顺着时间轴看代码演进，靠的就是这些注释。如果你的commit message全是“update”“fix”“aaa”，时间轴就废了。上传文件夹这种操作本身，我一般会写清楚来源和内容，比如import campaign landing project with build scripts，之后每次改动对应写fix: correct image path in header这样的句式。

3. 项目文件夹的整理与忽略规则：传之前先做减法

3.1 .gitignore到底在解决什么问题

一个真实的项目文件夹里，并不是所有东西都需要上传。依赖目录、系统缓存、编译产物、本地配置文件这些传上去只会让仓库膨胀，还可能把个人敏感信息暴露到公开仓库里。.gitignore文件就是用来在源头排除这些东西的。

在项目根目录创建.gitignore，一行一条忽略规则：

# 依赖目录 node_modules/ vendor/ # 构建产物 dist/ build/ *.class # 缓存与日志 .DS_Store *.log cache/ # 环境与密钥配置 .env config/credentials.json

规则里的node_modules/表示忽略整个目录，*.log表示忽略所有log扩展名文件，!开头表示例外不忽略，比如!.env.example可以让环境变量样例保留在仓库里。

实际效果是：你的文件夹还是完整的，但git add的时候会自动跳过这些规则内命中的内容。传一个Node.js项目，node_modules动辄几百MB上万个文件，不忽略的话第一次push就会卡死，推送完成仓库也会巨大无比。

3.2 不该传的敏感文件：一个必须说的红线

公开仓库默认全世界可见，很多人在上传文件夹时顺手把数据库配置、云服务密钥、token一起推上去了，几秒钟内就可能被爬虫扫到。这里有一个硬建议：push之前先过一遍git status，看到config/credentials.json、.env、id_rsa这类文件，立刻写进.gitignore并移出文件夹。

如果已经push上去了，别以为“把文件删掉再提交一次”就安全。历史提交里还留着这个文件，任何人翻git log都能看到。稳妥做法是把敏感内容在本地改成无实际价值的占位值，再提交一次覆盖，并立即去对应平台轮换密钥。也不要试图用强推覆盖历史——那是另一个更深的坑，普通用户不碰为妙。

3.3 文件夹体积控制与提交顺序

单个提交包含的文件总量也有隐性成本。Git对每个文件的改动都会做压缩和索引，一个commit塞进20000个文件，Git在操作时会明显变慢。拆成几个批次提交会更稳：

# 第一批：核心源码 git add src/ docs/ git commit -m "add source code and docs" # 第二批：资源与配置样例 git add assets/ config/*.example git commit -m "add assets and example configs" git push

分批提交不只是为了绕过限制，更是为了让远端仓库的提交历史可读。你把“源代码”“文档”“资源文件”分开提交，每条记录都是清晰的主题，后续排查问题要回滚也会精确很多。

4. 大文件与海量小文件：两种特殊场景的应对

4.1 GitHub对文件大小的硬限制与LFS的引入

GitHub对单个文件的上限是100MB，超过100MB的push会被直接拒绝，报错信息类似remote: error: File xxx is 123.45 MB; this exceeds GitHub's file size limit of 100.00 MB。

有的项目就是离不开大文件，比如训练好的模型文件、离线数据包、设计素材。这时该考虑Git LFS（Large File Storage）。LFS的思路是把大文件的真实内容存到单独的存储服务，仓库里只保留一个轻量的“指针文件”，这样克隆仓库时不会因为几个大文件就拖垮所有人。

启用方式很简单：

git lfs install git lfs track "*.psd" "*.zip" "models/*.bin" git add .gitattributes git commit -m "track large files with git lfs"

执行后根目录会生成一个.gitattributes文件，记录了哪些类型的文件走LFS。之后正常add、commit、push就行，大文件会被自动替换成指针上传。要注意，免费额度对LFS存储和下载流量有上限，数据资产特别大的项目，先用LFS还是直接不用Git管理大文件，需要掂量一下。

4.2 海量小文件的真正瓶颈在提交方式

比单文件过大更常见的坑是“文件数量多，但每个都很小”，比如一个图片素材库有十万张缩略图。这种情况下真正的瓶颈不是GitHub的远端限制，而是本地Git的提交效率——每轮commit都要递归遍历所有文件并计算校验值。

我的经验是分级处理：第一，把不该由Git管理的海量资源用.gitignore滤掉，改用网盘或对象存储分发；第二，必须入库的资源按主题分目录，一个目录一个commit，避免让Git一次性索引全部资源；第三，遵循增量提交的节奏，而不是一次堆积。

如果这个文件夹本身就是一个“文件型仓库”，比如纯文档库、纯素材库，数量级在几万文件以上，很多人会选择用sparse checkout或者干脆把仓库拆成多个子仓库。具体拆法因项目而异，总原则是先想清楚“哪些东西只是本地产物，哪些东西是仓库的真正资产”。

4.3 克隆与上传后的校验意识

上传完成后不要急着关终端，花十秒验证一下：

git status git log --oneline -5 git ls-files | wc -l

git status应该显示工作区干净（nothing to commit, working tree clean）；git log能看到你最近的提交记录；git ls-files | wc -l统计远端实际跟踪了多少文件。这组命令基本能确认“文件夹确实完整上传，没有漏文件、没有意外多出文件”。实际项目里，我最常发现的问题就是漏了某个子目录——而这三条命令一分钟内就能定位。

5. 踩坑实录：五次经典翻车与根因排查

5.1 fatal: repository not found 不是仓库不存在

push时看到fatal: repository 'https://github.com/xxx/yyy.git' not found，七成情况不是仓库真不存在，而是认证没通过。Git把“未认证”和“仓库不存在”合并成了同一条提示。

排查链路是：先确认仓库地址有没有拼错用户名和仓库名；再确认仓库是公开还是私有，私有仓库必须完成认证；最后确认认证方式。做一次git remote -v看当前绑定地址，再用浏览器登录GitHub检查是否有访问权限。这个报错还常见的场景是第一次push时口令输入错误，本机凭据缓存记住了失败的登录信息，后面一直拿错误口令访问。这时候用git remote set-url origin重新设置一次远端地址，或者清理本机的凭据缓存，重新走认证流程。

5.2 refusing to merge unrelated histories 的来龙去脉

如果在远端仓库初始化时勾选了“Add a README file”或“.gitignore”，而本地仓库又是从git init独立初始化的，那么两个仓库各有一个完全独立的第一次提交，彼此没有共同祖先。你直接执行git push origin main，Git会提示远端包含本地没有的提交（non-fast-forward），需要先整合远端内容；等你执行git pull origin main，它就会抛出fatal: refusing to merge unrelated histories。

我处理这件事的顺序是：先彻底理解为什么——Git合并要在两个分支之间找到共同基点，没有共同基点它是不会机械地合并的，这个保护机制避免了历史被污染。然后按情况选方案：最干净的办法是不要让远端先有提交，本地直接push到空仓库；但如果你想保留远端的README等初始提交，就做一次“允许无关联历史”的拉取合并：

git pull origin main --allow-unrelated-histories git push origin main

执行之后两个独立历史被合并为一个大历史，从GitHub看仓库记录会有一条奇怪的“合并”节点，但不影响后续使用。这个方法虽然能解决问题，我还是建议新项目新建仓库时一律不勾选README，让本地作为历史起点，干净省事。

5.3 密码登录为什么失效：认证方式的演进

很多老教程让你用账号密码做push认证，现在已经过时了。GitHub出于安全原因不再接受账号密码直接作为git操作的认证凭据，你必须使用Personal Access Token（个人访问令牌）或者SSH key。

Token方式：在GitHub账户设置里生成一个新token，权限勾选repo（仓库读写），生成后复制保存。push时如果提示输入用户名和密码，用户名填你的GitHub用户名，密码位置粘贴这个token而不是账号密码。Token的粒度可以控制，比密码安全得多。

SSH方式则更进一步：本地生成一对密钥，把公钥配到GitHub账户里，push时用SSH地址git@github.com:用户名/仓库名.git，之后全程免输密码。我个人更推荐SSH，因为一次配置长期使用，且在终端里不被反复打断。

5.4 网络中断与传输超时的恢复策略

上传大文件夹过程中，最常见的现实打击是传输中断。Git的push不是“一次性原子操作”，它会分批传输对象，中断后通常可以重试，Git能识别哪些对象已传到远端，从断点继续上传。所以我遇到超时的第一反应不是清空重来，而是把原来的push命令原样再执行一次，多数情况能续传完成。

如果反复失败，说明当前网络波动确实严重，这时减少单次推送体积更有效：把大commit拆成多个小commit逐个push，每个小commit传输时间短，失败重试的成本也低。还有一个隐藏技巧是适当调大HTTP缓冲：

git config http.postBuffer 524288000

这一行把http.postBuffer从默认值调大到500MB，对走HTTPS协议、带宽尚可但经常中途断开的场景很管用。缓冲区变大不代表一次性塞入所有数据，但能减少因小缓冲导致的传输中止。

5.5 报错速查：一张表对照翻车现场

我把上面几个典型问题整理成一张速查表，遇到报错先对着看，能省不少排查时间。

6. 桌面客户端与命令行：到底哪个更适合你

6.1 GitHub Desktop：可视化方案的取舍

如果你对终端指令有天然抵触，GitHub Desktop是官方提供的桌面客户端，把add、commit、push这几个核心动作变成按钮。安装登录后，选择本地文件夹，点击“Create repository”初始化，然后界面上会清晰列出改动文件列表、提交输入框、push按钮，整套流程和命令行走的是同一个底层逻辑，只是把每一步可视化了。

Desktop的优势是：文件改动一目了然，误提交之前能直接看到；分支切换、合并这些高频操作不用记命令；对“只想把文件夹传上去”的用户来说，它比命令行零门槛。缺点也很明显：大仓库和复杂历史时性能不如命令行灵活，自动化能力几乎为零，一旦遇到5.1到5.4那种底层问题，你还是得回到命令行去诊断。我的建议是：先让它帮你建立“暂存、提交、推送”的心智模型，之后迟早要补一点命令行基础。

6.2 其他客户端工具的定位差异

市面上还有很多第三方Git图形客户端，有的偏重于单仓库的日常提交，有的偏重多仓库管理和可视化分支图。它们和GitHub Desktop的本质差别在于：GitHub Desktop只围绕GitHub平台优化，第三方工具大多能同时对接多个托管平台，界面也更花哨。

但无论用哪个图形工具，底层跑的仍然是同一套Git命令。你看到的是按钮，实际执行的还是git add、git commit、git push。我会建议新手不要同时装太多客户端，先把一个工具用熟，否则很容易混淆“到底是工具的问题还是Git的问题”。

6.3 我的最终建议：先网页端理解概念，再命令行建立习惯

如果让我给一个清晰的上手路径：第一次用网页拖拽传一个迷你文件夹，感受一下仓库是什么；第二次用GitHub Desktop把一个真项目传上去，理解提交和推送的可视化过程；第三次开始，强制自己用命令行做同样的操作，直到git status变成下意识动作。

命令行没有想象中可怕，日常高频操作翻来覆去就那五六个命令。一旦你习惯了命令行，写脚本批量提交、排查报错、操作复杂分支都会变得顺畅，这也是很多从业者最终留在命令行的原因——不是装，是真的高效。

最后分享一点我自己的体会：GitHub上传文件夹这事的核心，不在一开始能不能传上去，而在传上去之后这个仓库对你和别人是不是依然清晰可用。我在带新人时反复强调一句话——“你如何对待Git提交历史，别人就会如何看待你的代码质量。”上传只是第一步，把目录整理干净、敏感文件隔离、提交信息写明白，这些在按下push之前多花十分钟，会让后续所有人在这个仓库上节省大量时间。我个人的习惯是把第一次push当成一次“交付”，交付前必看git status和git diff摘要，确认没有多余文件才松手。这个习惯坚持下来，你基本不会再遇到“传上去发现传错了”的尴尬事。