企业官网建设流程全解析

我到现在还记得第一次往GitHub上传项目时的情景：Git装好了，账号注册好了，远程仓库也建好了，然后卡在"把本地代码弄到远程仓库"这一步，整整折腾了一个下午。网上教程东一句西一句，有的说网页直接拖拽就行，有的甩给我一行git push命令，还有的让去生成SSH key——每个词都认识，连在一起就懵了。后来自己把Git的上传机制摸熟了才发现，GitHub上传项目这件事，难点往往不在技术，而在操作顺序。顺序对了是一马平川，顺序一错就是连环报错。这篇就按我趟过雷之后的经验，从网页上传、命令行推送、GitHub Desktop三个入口，把"怎么把项目传上GitHub"这个事彻底讲明白，顺带覆盖上传文件夹、大文件处理、访问加速、推送失败排查这些大家问得最多的问题。不管你是刚注册账号的新手，还是需要整理常用操作的老手，这篇都有参考价值。

1. 上传前的仓库准备：这些细节决定后续是否顺利

1.1 先想清楚仓库类型和可见范围

GitHub仓库分两种：Public（公开）和Private（私有）。Public仓库全世界都能看见，适合开源项目、个人作品集、学习笔记之类的展示型内容；Private仓库只能自己和受邀协作者看到，适合放还没做完的项目、公司代码、私人配置文件。

免费账号下两者都能创建，Public没有协作者数量限制，Private面向个人使用和小范围协作，超过免费额度会有套餐升级提醒。这个选择在创建仓库时就要定下来，虽然后期可以在Settings -> General -> Danger Zone里改Visibility，但改可见范围会引发一系列权限变化，比如Public仓库改成Private后，已经有star、fork记录的项目会受影响，所以一开始选对最省事。

细节提醒：创建仓库时，如果勾选了"Add a README file"、"Add .gitignore"、"Choose a license"中的任意一项，远程仓库就会带上一个初始commit。如果你打算跟着本文后面的命令行流程走，建议创建时一个都不要勾，让远程仓库保持完全空白。这样第一次push就是纯粹的本地推送到空仓库，能避开最典型的"failed to push some refs"报错。我见过太多新手栽在这个细节上，包括当年的我自己。

1.2 本地项目结构整理与.gitignore配置

上传之前，先低头看一眼你的项目目录。要弄清楚哪些文件应该进仓库，哪些死活不该进。

软件项目里，node_modules、venv、__pycache__、.env、build、dist、.DS_Store、*.log这类文件或目录，都不应该上传。原因有三层：

第一，体积膨胀。一个前端项目的node_modules动辄几万个文件，塞进Git仓库后，每次clone、每次fetch都要拉这一大坨，仓库会臃肿到没法用。而且这些东西在任何一台电脑上都能通过包管理器一键重建，放进仓库纯属自找麻烦。

第二，安全风险。.env文件里通常躺着数据库地址、API密钥、云服务凭证，一旦提交到Public仓库，等于把密钥摆在所有人面前。爬虫扫描工具会盯着GitHub找这类泄露文件，可能在你上传后几分钟内就被人扫走。

第三，团队协作习惯。别人clone你的项目下来，第一件事就是跑npm install或pip install，没有人希望仓库里躺着一堆别人的编译产物。

解决办法是在项目根目录创建一个.gitignore文件：

touch .gitignore

内容按项目类型填写，以下是最常见的通用模板：

node_modules/ venv/ __pycache__/ *.pyc .env .DS_Store dist/ build/ *.log .idea/ .vscode/

提示：.gitignore只对"尚未被Git跟踪"的文件生效。如果某个文件之前已经被git add和git commit提交过了，之后再把它加进.gitignore是没有用的，它依然会被继续跟踪。需要先把它从Git索引中移除：

git rm --cached .env

然后提交一次"从仓库移除敏感文件"的commit，再配合.gitignore才能彻底让它消失。这个坑我踩过，当时公开仓库里躺着两个.env，还好没有真实密钥，否则就不是删文件的问题了。

1.3 写一个不敷衍的README

README是项目的门面。GitHub会自动渲染仓库根目录下的README.md，别人点进你的项目主页，第一屏看到的就是它。很多新手忽略这个东西，觉得代码能跑就行，但实际体验下来，有没有README完全是两个档次的体验。

一份合格的README至少包含这几块：

• 项目是什么：一句话说明这个项目解决什么问题
• 安装方式：依赖什么环境，怎么装依赖
• 启动方式：怎么跑起来
• 使用示例：放一两个最常用的命令或截图
• License：别人能不能用、能不能改，写清楚避免法律麻烦

不需要长篇大论，写清楚核心信息就行。图片可以用相对路径放进docs/images目录一并提交，比外链图床稳定得多。如果你是个开源项目维护者，一份好README的价值等于省下了每天回复重复问题的时间。

2. 命令行推送全流程：最通用、最可靠的上传方式

2.1 安装Git并配置用户信息

命令行是GitHub上传的核心操作，强烈建议每个用GitHub的人都掌握基本面。第一步是安装Git：Windows用户去git-scm.com下载安装包一路Next；macOS可以用Homebrew执行brew install git；Linux直接用系统包管理器apt install git或yum install git。安装完验证一下：

git --version

能输出版本号就说明装好了。接下来不要急着提交代码，先把身份信息配置好：

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

这两个信息会写进每一次commit里。这里有个非常重要的细节：邮箱建议使用GitHub的noreply邮箱。公开仓库里的每个commit都携带提交人邮箱，如果你填的是真实邮箱，很容易被爬虫收集去发垃圾邮件。GitHub在每个账号的Settings -> Emails页面提供了一个专属的noreply地址，格式类似12345678+用户名@users.noreply.github.com，在"Keep my email addresses private"勾选后，它会成为你push时自动使用的邮箱。这个设置在新账号里默认就是开启的，老账号记得检查一下。

2.2 首次推送：从本地已有项目到远程仓库

假设你本地已经有一个项目文件夹，里面还没有任何Git痕迹，远程也已经在网页上建好了一个完全空白的新仓库。完整流程如下：

# 1. 进入项目目录 cd 你的项目文件夹 # 2. 初始化本地Git仓库 git init # 3. 把所有文件加入暂存区 git add . # 4. 生成第一个commit git commit -m "Initial commit" # 5. 添加远程仓库地址（二选一，建议用SSH） git remote add origin git@github.com:用户名/仓库名.git # 6. 把本地分支重命名为main git branch -M main # 7. 推送并建立关联 git push -u origin main

逐条解释一下这些命令到底在干嘛，理解比死记重要得多：

• git init：在当前目录创建一个隐藏的.git文件夹，这个文件夹就是完整的本地仓库数据库，记录所有版本历史。
• git add .：把当前目录下所有文件加入"暂存区"。暂存区是一个中间状态，你可以先挑几个文件进去，也可以全部进去。
• git commit -m "Initial commit"：把暂存区内容固化成一条历史记录。-m后面是提交说明，相当于这次改动的标签。
• git remote add origin ...：把本地仓库和远程仓库建立关联。origin是远程仓库的默认名字，可以改，但整个生态都约定俗成用它，没必要特立独行。
• git branch -M main：把本地默认分支从master重命名为main。GitHub新建仓库的默认分支现在叫main，如果你的Git还是旧版习惯，本地会是master，不rename的话push时会报分支名不匹配。
• git push -u origin main：把本地main分支推向远程。-u表示记住当前分支与远程分支的关联，以后直接敲git push就够了。

关于HTTPS和SSH的选择，直接给结论：

• 新手建议先走HTTPS加Personal Access Token，流程最短，配置最少。
• 如果同一台电脑要长期维护多个仓库，SSH更省心，配置一次之后永久免密。

SSH配置流程：

ssh-keygen -t ed25519 -C "你的GitHub邮箱" cat ~/.ssh/id_ed25519.pub

把输出的公钥全部复制，粘贴到GitHub的Settings -> SSH and GPG keys -> New SSH key里，然后验证：

ssh -T git@github.com

看到Hi 用户名! You've successfully authenticated就说明通了。之后所有git remote add origin都改用git@github.com:用户名/仓库名.git这个SSH格式。

2.3 每次代码更新的标准操作流

推送不是一次性动作，之后每次改动代码，都要走一遍"三段式"：

git add 改动的文件 git commit -m "说明这次改了什么" git push

注意几个习惯：

第一，git add不一定要用.,按需添加比一股脑全加更靠谱。比如你同时在改业务代码和配置文件，可以分开add、分开commit，历史记录会清晰很多。

第二，commit message用祈使句或现在时，比如Fix login bug、Add README、Update dependencies。别用update这种没有信息量的话,多少个commit都叫update，回头查版本谁都分不清。

第三，commit之前先git status看一眼当前状态，再用git diff确认改动内容。养成这个习惯能避免把不该提交的东西混进去。我见过有人把密码文件、数据库备份、甚至几百MB的日志文件commit进去的，都是因为没看status就直接git add .然后git commit。

3. 网页端直接上传：适合什么样的项目和文件

3.1 网页上传的限制与适用场景

网页端上传的思路非常直白：整个项目不经过Git，直接在浏览器里把文件拖进去，填一句说明，点一个按钮，完成上传。适合什么场景？快速放几个小文件、临时补个文档、收到一个单文件PDF想立刻挂到项目里、文件更新频率很低的场景。

但网页上传有硬限制，在这里统一列清楚：

网页端一旦上传失败，报错就是一句Yowza, that's a big file. Try again with a file smaller than 25 MB.，没得商量。所以判断标准很简单：文件小、数量少、结构简单，网页端够用；文件大、数量多、要控制哪些文件进仓库，必须走命令行。

3.2 在网页上创建带路径的文件夹

很多人在网页端找"新建文件夹"按钮，找了半天找不到。这个功能是隐藏式的：点击Add file->Create new file，在文件名输入框里直接输入文件夹名/文件名。比如想创建一个docs目录并放一个说明文件，就在输入框里写：

docs/说明.md

回车之后，系统会自动创建docs文件夹并进入编辑页面。注意，如果只输入docs/是不会被接受的，会提示输入合法文件名，所以必须带上一个真实文件。

这种一层一层手工建文件夹的方式只适合小规模结构。如果你想批量创建多层文件夹，比如src/components/Button/index.js这种深度路径，网页端就非常吃力了。这种项目请直接使用命令行或GitHub Desktop，别在网页端硬凿。

3.3 上传文件夹的正确姿势

网页端确实支持拖拽上传整个文件夹。把文件夹拖进Upload files区域，现代浏览器会保留内部的目录结构，不需要自己一个个建子目录。但我要泼一盆冷水：网页端上传文件夹时，它不会读取你项目里的.gitignore，是按文件系统原样上传的。也就是说，如果你的前端项目里有node_modules，拖进去就是一个灾难，几十万个小文件足以让上传卡到怀疑人生，而且这些文件还会永久留在仓库历史里。

所以网页端上传文件夹，只适合"干干净净的文件夹"：里面就几个文档、几张图片、一个小的子目录结构，没有任何依赖文件、缓存文件。如果项目里带依赖目录或临时文件，正确姿势是先手动清理掉，或者干脆用命令行。既然要用GitHub，这个过滤能力就是刚需，躲不开的。

4. GitHub Desktop：不想敲命令时的图形化方案

4.1 GitHub Desktop的安装与登录

GitHub Desktop是官方出品的图形客户端，相当于给Git套了一层可视化的皮。它把分支、提交、推送、拉取这些操作全部变成了按钮和面板，对刚入门还不熟悉命令行的朋友非常友好。下载地址是desktop.github.com，Windows和macOS都有安装包。

安装完成后第一次打开，会要求授权登录GitHub账号。点Sign in，它会引导你在浏览器里完成授权，然后Desktop自动接管你的Git凭据。这意味着之后所有push操作都不会再反复要求输入账号密码，比命令行配token流程舒服很多。

Desktop还有一个额外价值：它的信息展示方式对理解Git非常有帮助。你能直观地看到每个文件当前处于什么状态、有哪些改动、历史里有几条提交，这些可视化信息能把Git的抽象概念变得具体。很多人说用几天Desktop之后再回去看命令行，思路完全通了。

4.2 用Desktop完成首次推送

场景一：本地有一个项目文件夹，还没有任何Git痕迹。操作为：

1. 打开GitHub Desktop，菜单File->Add Local Repository，选择你的项目文件夹。
2. Desktop会识别出来这是未初始化的目录，弹出一个Create repository按钮，点击它，相当于执行了git init。
3. 左侧会显示当前目录所有文件的改动列表，所有文件都在"待提交"状态。在左下角输入commit信息，比如Initial commit，然后点击Commit to main。
4. 点击右上角Publish repository，选择Public还是Private，点Publish Repository，一气呵成。

这个第四步特别厉害，它同时完成了"在远程创建仓库"和"推送本地内容"两个动作。也就是说，你完全没有必要先在网页上手动建一个空仓库再回来推送，Desktop全包了。

场景二：已经在网页上建好了仓库，想把它克隆到本地再上传。步骤如下：

1. 进入仓库页面，点Code按钮，在下拉菜单里选择Open with GitHub Desktop。
2. Desktop会弹出一个选择本地路径的窗口，确认后开始clone。
3. 克隆完成后，把你的项目文件复制进这个本地目录，Desktop马上会识别出新文件。
4. 照常输入commit信息、点击push即可。

4.3 日常更新与分支切换的可视化操作

Desktop的日常界面主要分两个视图：

Changes视图显示所有未提交的改动。左侧是文件列表，右侧是diff面板，绿色表示新增行，红色表示删除行，一目了然。这个diff功能是我推荐新手用Desktop入门的最重要理由：commit之前先看一遍diff，就能确认自己有没有把不该提交的东西混进去，比如数据库连接配置、本地缓存、临时文件。命令行里要git diff才能看到这些内容，但Desktop把它做成了"点一下就看"的便利功能。

History视图显示所有commit记录。哪个分支在哪个节点做了什么改动，按时间线排下来非常清楚。日常更新就是：改文件 -> 看diff确认 -> 填commit信息 -> 点Push。如果远程有别人推的新改动，push时会提示需要先pull，点一下Pull再push就行。

Desktop适合用来管理常规仓库，但如果项目结构特别复杂，比如大量子目录嵌套、需要精细操作暂存区，还是命令行更灵活。两者不冲突，我现在的习惯是：日常工作用命令行，给新人演示或做Code Review时用Desktop。

5. 大文件、空文件夹和断线重传：上传中的特殊场景

5.1 100MB文件硬限制与Git LFS方案

Git的设计核心是追踪文本内容变化，对大体积二进制文件非常不友好。一个100MB的资源文件提交进去，任何一次构建、任何一次合并都会带着它走一遍，仓库体积和操作速度都会崩溃。因此GitHub设了硬性限制：通过git push上传的单个文件最大100MB，通过网页上传最大25MB，超过直接拒绝。

如果确实需要向项目发布大文件，有两个正规渠道：

第一个是GitHub Release。Release不进入仓库历史，本质是挂在某个版本号下的一批下载附件，适合放安装包、压缩包、模型权重、数据集这类分发物。操作路径：仓库首页Releases->Draft a new release-> 填版本号（比如v1.0.0）-> 把文件拖进附件区域 -> 发布。Release单个文件的上限是2GB，比push大方得多。

第二个是Git LFS（Large File Storage）。如果你的大文件必须始终跟在项目里、每次修改都有版本记录，LFS是标准方案。基本用法：

git lfs install git lfs track "*.psd"

这样会生成一个.gitattributes，以后所有.psd文件都会走LFS存储，普通文本文件还是走常规Git。LFS免费额度是每月1GB存储和1GB带宽，小项目够用，大项目就要评估付费了。

5.2 空文件夹为什么传不上去：.gitkeep的用法

很多新手会碰上这个诡异问题：明明项目里有个assets文件夹，里面是空的，准备先建好结构后面再放东西。结果不管怎么push、怎么上传，远程仓库里就是看不到这个文件夹。

原因很简单：Git只跟踪文件，不跟踪目录。空目录里没有任何文件，Git不会记录它。这不是GitHub的bug，是Git从底层就是这样的设计。因为目录本身不构成数据，只有文件才有内容，目录只是路径描述。

解决办法是给空文件夹放一个占位文件，Git社区约定俗成的名字是.gitkeep：

touch assets/.gitkeep git add assets/.gitkeep git commit -m "Add empty assets folder placeholder"

.gitkeep内容可以是空的，它存在的唯一意义就是让Git知道"这个目录不是空的，我要跟踪它"。之后其他人clone项目下来，assets文件夹会保留。创建好结构后发现页面没反应也不要慌，加个.gitkeep就完事了。

5.3 仓库访问波动和上传慢怎么办

这个问题在热搜里反复出现，"github打不开、官网进不去、下载慢"是困扰大量用户的核心痛点。先明确一个事实：GitHub本身的服务器是稳定的,但部分网络环境对它的访问确实不友好，DNS解析错误、CDN节点路由绕路都可能导致网页打不开或clone龟速。这属于网络波动和DNS层面的问题，解决思路也从这两方面入手。

按顺序试这几个常规手段：

1. 刷新本地DNS缓存。Windows执行ipconfig /flushdns，macOS执行sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder。很多"网页打不开"其实是本地缓存了一个错误的DNS解析结果，清掉就好了。

2. 把DNS切换到公共DNS。在系统网络设置里把DNS改为223.5.5.5（阿里DNS）或114.114.114.114（114DNS）。这个操作立竿见影，能解决相当一部分访问失败和打开慢的问题。

3. clone和release下载速度慢时，可以使用第三方公开加速服务。比如ghproxy这类GitHub仓库加速站，用法是在仓库地址前加一段前缀：

git clone https://ghproxy.com/https://github.com/用户名/仓库名.git

这类服务只加速clone和下载，不参与网页登录和push操作。对GitHub镜像站，认准长期维护的知名站点，不要随便输入账号密码，安全第一。

4. push超时严重时，把push动作拆散。改一点推一点，避免一个包含上千个文件的大push在连接中途挂掉导致整体失败。经验是：一次push几十个小文件，成功率远高于一次push几千个文件。大目录结构下，先分批add、分批commit、分批push也能有效规避连接断开。

5. 如果你只是想下载某个仓库的最新代码而不是参与开发，甚至可以不装Git，直接点仓库首页的Code->Download ZIP，避免整个Git传输过程。这个方式在下载release资源时同样适用。

6. 推送失败高频报错排查手册

6.1 password authentication已被移除：改用token

这是HTTPS推送遇上的最经典报错，原文长这样：

remote: Support for password authentication was removed on August 13, 2021. Please use a personal access token instead.

原因一句话：2021年8月之后，GitHub彻底不再接受用账号密码进行HTTPS推送，必须用Personal Access Token（个人访问令牌）。很多新手第一次走HTTPS被卡死，就是还在用账号密码填充用户名和密码框。

正确路径是：

1. GitHub网页右上角头像 -> Settings -> Developer settings -> Personal access tokens -> Tokens (classic)
2. Generate new token (classic) -> 勾选repo、workflow等权限 -> 生成
3. 生成后token只完整显示一次，立即复制保存
4. push时用户名正常输入GitHub用户名，密码框粘贴token（不是账号密码）

如果不想每次push都输入token，执行一次：

git config --global credential.helper store

之后第一次输入token会被记住，后续免密。注意这个命令是明文存在本地配置里的，自己的个人电脑没问题，公用电脑慎开。

6.2 failed to push some refs：远端已有本地没有的提交

报错长这样：

error: failed to push some refs to 'https://github.com/用户名/仓库名.git' hint: Updates were rejected because the remote contains work that you do not have locally.

原因通常是创建仓库时勾选了README、.gitignore或License，远程产生了初始commit，而本地是另外初始化的独立仓库，两边历史对不上。解决办法是把远程的初始提交合进来：

git pull --rebase origin main git push -u origin main

--rebase会把本地提交"垫"到远程提交的上面，保持一条直线历史。如果pull的时候提示unrelated histories，加参数：

git pull origin main --allow-unrelated-histories

然后提交合并结果，再push。这正好印证了前面说的：新手创建仓库时一个文件都不要勾，远程空白仓库能避开这整套麻烦。

6.3 refusing to merge unrelated histories：两个毫无交集的仓库

报错原文：

fatal: refusing to merge unrelated histories

原因更彻底：本地仓库和远程仓库的根节点完全不同，Git找不到共同祖先，于是拒绝合并。常见于远程仓库已经有内容（比如建仓库时勾了README），本地又是一个从git init开始的全新仓库。解法：

git pull origin main --allow-unrelated-histories

这个参数的意思是"我明确知道两个历史毫无关联，请你强制合并"。合并过程中如果出现冲突，手动解决后：

git commit -m "Merge remote repository" git push -u origin main

注意，这种合并会产生一次包含两边完整文件结构的提交，如果两边存在同名文件，用--allow-unrelated-histories时会以合并冲突形式要求你选择保留哪一方。处理完一次性提交即可。

6.4 本地分支名和远程不一致

报错症状：

error: src refspec main does not match any

原因：本地默认分支是master（老版本Git的默认命名），远程默认分支是main（GitHub的默认命名），两边没有对齐。Git提示找不到名为main的本地分支。解法就一条命令：

git branch -M main

-M是--move --force的缩写，强制把当前分支改名。改名后再git push -u origin main就顺了。这个坑在新版Git上少见，因为新版初始化时默认分支名也是main了，但老电脑、老项目里还是有概率碰到。

6.5 子目录里自带.git导致整个目录变成"子模块链接"

场景比较隐蔽：你的项目里某个子目录本身是个Git仓库，里面有隐藏的.git文件夹。此时在根目录执行git add .，Git会把这个子目录识别成一个"embedded git repository"（嵌入式仓库）。push之后你会在远程仓库里看到该目录显示为绿色小方块图标，点进去没有任何文件内容，只有一个指向某个commit的不可追踪链接。

原因：Git检测到子目录里有独立的.git，认为它是另一个仓库，就按"子模块引用"处理了。

处理取决于你的意图：

• 如果这个子目录是要独立维护的项目，把它正式声明为子模块（submodule），用git submodule add <仓库地址> <目录>，这样两个仓库的版本关系能被正确维护。
• 如果只是想让子目录作为当前项目的一部分，解决方案就是把子目录里的.git删掉：注意它是隐藏文件，Windows资源管理器默认看不见，macOS Finder也默认不显示，命令行里ls -la下拉一下就能看到。删掉后再git rm -r --cached清理子目录缓存，重新git add .、commit、push。

教训一句话：上传前先检查项目里有没有隐藏的.git目录。用find . -name ".git"扫一遍最稳，避免push后才发现子目录只剩一个空壳。

GitHub上传项目这条路，我前前后后走了好几年，最深的体会就是：不要一开始就追求把所有Git命令背下来，先把add、commit、push、pull这四个动作的先后逻辑搞清楚，遇到报错再针对场景查解法，比抱着命令手册死记硬背效率高得多。另外，别怕推送失败——Git的报错信息虽然密，但每一条都在告诉你该往哪里走，报错里的英文看个半懂也能推断出七八分。如果这篇文章能让你的第一次上传从两个小时缩短到十分钟，那我写的这些排错记录就算没白费。