先把一个常见误会解开所谓“上传本地网页到GitHub网址”并不是把某个网页文件直接“贴”到GitHub的某个链接上而是把整个本地网页项目推送push到GitHub仓库里再借助GitHub自带的Pages托管服务自动生成一个以github.io结尾的公开网址。别人访问这个网址就能直接看到你的页面。这篇文章会按真实操作顺序完整走一遍从零到上线全过程创建仓库、本地初始化Git、推送到远端、开启GitHub Pages、处理404报错。同时会把我在实际使用中踩过的坑一起写进去比如分支名不统一导致的推送失败、部署完页面打不开、超过100MB的文件被拒绝等。每个坑都有对应的排查思路和解决方案不是只给命令而是把为什么这样做也讲清楚。如果你是一个刚接触GitHub、手里正好有一个做好的静态网页哪怕只是单页的HTML文件想让它有一个任何人都能访问的公网地址这篇文章可以直接照着做。1. 弄清楚核心逻辑本地项目、Git仓库、Pages服务三者是什么关系很多新人之所以觉得上传这个动作难是因为把三个概念混在了一起。先花两分钟把这层关系理清后面所有命令都不会再让你迷茫。1.1 本地项目你电脑上那堆网页文件本地项目就是你写的网页文件集合通常至少包含一个index.html还可能带css、js、images等文件夹。它现在只存在于你电脑的某个目录里没有经过任何版本管理改坏了只能靠手动备份。我们要做的第一步就是让这一堆文件夹变成一个“被Git管理的仓库”。1.2 Git仓库给项目配上时间机器Git是一个版本管理工具它会把你项目里每一次有意义的修改记录成一个版本就像给文件打了许多存档点。你随时可以回到任何一个存档点不需要再靠“最终版_第三版_真最终版”这种命名方式来折磨自己。本地项目本身是一堆文件但一旦在文件夹里执行了git init这个文件夹就多了一个隐藏的.git目录从此Git开始记录这个项目的每一次变更。注意仓库不只是GitHub上的概念你本地执行过git init之后本地就已经存在一个仓库了。GitHub上的仓库本质上是你本地仓库的一份“远端备份和协作副本”。1.3 GitHub Pages把仓库里的网页变成公网网址GitHub仓库本身允许存放网页文件但仓库默认只是个存储空间不会自动把里面的网页展示给你看。Pages是GitHub提供的一项静态托管服务你只要在仓库设置里开启PagesGitHub就会把这个仓库指定分支通常是main分支里的内容当成一个网站来发布。Pages只会处理静态文件不会执行后端代码。纯HTML、CSS、JavaScript写出来的网页完全没有问题这也正是大部分个人主页、项目介绍页、简历页的选择。托管的原理也不复杂GitHub把仓库根目录当作站点根目录默认读取index.html作为首页。所以你的项目里首页必须叫index.html否则最后打开网址会得到一条404。把这三个概念串起来整个过程就是一句话在本地把网页文件夹变成Git仓库推送到GitHub远端仓库再让GitHub Pages把仓库内容发布成网站。接下来每一步都是围着这个主线走。2. 出发前的准备工作账号、Git客户端和本地项目检查正式动手之前有三个准备项需要检查。缺一个后面都会卡住提前确认好能省掉不少返工。2.1 注册可用的GitHub账号GitHub账号在官网注册即可流程不复杂邮箱验证那步可能会遇到延迟多试几次垃圾邮件里也看一眼。用户名一旦确定后续会直接出现在Pages域名里比如我注册的用户名是exampleuser那生成的默认网址就是https://exampleuser.github.io。用户名取一个简洁和自己相关的英文组合项目展示时也会显得更专业。需要提醒的是这里涉及的网络访问问题我在第8章会单独展开说排查思路这条先不用急着解决注册阶段只要能正常打开网页、收到邮件验证就行。如果打不开的情况反复出现稍后再一并处理。2.2 安装Git客户端Windows、macOS、Linux三种安装方式Git是一个命令行工具安装完成后在你的项目文件夹里右键就能看到Git Bash Here或Open Git Terminal here之类的选项。这就是我们操作Git的入口。三个主流系统的安装方式分别如下系统安装方式注意事项Windows下载Git for Windows安装包一路默认选项即可安装时如果让选默认编辑器建议选Notepad或Visual Studio Code不要选Vim新手容易卡在Vim操作出不来macOS安装Homebrew后执行brew install git或直接去Git官网下载macOS版安装包安装Xcode命令行工具时也会附带GitLinuxDebian系执行sudo apt install gitRedHat系执行sudo yum install git安装完执行git --version确认版本安装完成后在Git Bash里执行git --version能输出版本号就说明安装成功。不需要急着学一堆Git命令本篇只用到那六七个最基础的足够了。2.3 检查本地项目是否符合静态托管条件先打开自己的网页项目文件夹确认以下几点入口文件必须叫index.html。如果你只有一个home.html或myweb.html请先把它重命名成index.html否则Pages开启后访问根路径看不到任何内容。项目里的引用路径比如link relstylesheet hrefcss/style.css尽量使用相对路径。如果你的路径写的是C:\Users\xxx\css/style.css或file:///...这类绝对路径或本地路径部署到线上后资源会全部加载失败页面会变成没有样式的纯文本。确认文件夹里没有超过100MB的单个文件。GitHub单个文件上限是100MB超过这个限制推送时会被直接拒绝。如果确实有大文件比如演示视频、数据集建议放到网盘或者后续用Git LFS这个我在第8章细说。检查完这三项准备工作就算完成。接下来创建一个远端仓库来承接你的本地项目。3. 在GitHub上创建仓库命名直接决定你最后的访问网址登录GitHub之后创建仓库的操作都在网页右上角。3.1 新建仓库的完整入口和配置项选择点击页面右上角那个加号图标在下拉菜单里选择New repository进入仓库创建页面。这里有几项配置需要逐一确认Repository name仓库名这是最关键的一项。如果你的目标是得到一个形如https://用户名.github.io这样的专属网址仓库名必须严格写成用户名.github.io注意用户名与GitHub账号大小写完全一致。用户名是exampleuser仓库名就写exampleuser.github.io。对照组如果你给仓库随便起名叫myweb那最后的访问地址会变成https://用户名.github.io/myweb/多出一层路径视觉效果和输入成本都不一样。Public还是Private公开还是私有GitHub Pages在免费版账号下要求仓库必须设为Public才能开启Pages服务。如果你以后想升级到Pro私有仓库也能开Pages但在免费阶段先把仓库设为Public是最省事的。仓库公开只是代码公开可看不会影响你的页面功能。Add a README file默认不要勾选。很多教程会建议加但如果你本地项目已经是一个完整的仓库远端再初始化一个README文件会导致本地与远端历史不一致第一次推送时要额外处理冲突。先不勾推完代码后想补README再去编辑页面里手动加就行。Add .gitignore默认不选。这个文件是用于排除不需要上传的文件可以直接在自己项目的Windows资源管理器里手动创建也可以在后续有需要时再补。Choose a license如果这是你的开源项目或教程示例选一个开源许可证如MIT很合适如果只是个人网页不选也没问题。配置完成后点击Create repository。创建成功后页面会跳到一个带Git命令提示的界面上面列出了git remote add origin、git branch -M main、git push -u origin main这几行命令。此刻仓库还是空的我们需要回到本地项目把内容推上去。3.2 为什么网页端直接传文件夹的体验并不好在创建仓库的页面或仓库首页其实有一个上传文件的入口允许直接拖拽文件夹到网页里。这个方式对新手的吸引力很大不用碰命令行。但你实际传过几次就会发现它的局限文件一多网页上传不仅慢而且一旦传错某个文件只能通过网页逐个删除重传没有任何版本记录更关键的是它没法解决后续“改了几行代码再更新网站”的更新流程每次都得重新传一遍。而用Git推送更新网页只需在本地改完代码后执行git add、git commit、git push三连整个版本的修改记录都会在仓库的Commit里追溯。这也是把整个文件夹“传”上去真正推荐的姿势——虽然你看着是在敲命令但本质上是在上传一个完整、可维护、有历史的项目而不是一堆孤立文件。4. 本地项目变Git仓库init、add、commit的顺序为什么要这样走如果你此前完全没接触过Git把这一章当成最简单的入门即可。这三个命令不是随机敲的它们对应着Git工作流里三个不同的阶段。4.1 阶段一git init让文件夹进入Git视线打开Git Bash先进入项目文件夹。进入方式有两种文件管理器里进入项目目录后右键选择Git Bash Here或者在Git Bash里用cd命令切过去。然后执行git init执行后文件夹多了.git目录Git开始跟踪这个目录下所有文件的改动。这一步的实质是让项目进入“待观察”状态还没有任何版本记录一切从零开始。4.2 阶段二git add挑选要记录的文件所有文件现在都处于未跟踪状态untracked。执行git add .注意命令最后那个点表示“把当前目录下所有文件都加入暂存区”。你也可以指定某个具体文件比如git add index.html但既然是整个网页项目上传用git add .一次搞定更省事。一个实用的检查命令是git status。它会显示当前哪些文件已被跟踪、哪些还没加入。我个人的习惯是在add之后执行一次git status确认列出的文件都是项目需要的尤其检查有没有把一些临时文件、缓存文件、node_modules这类大目录意外加进来。如果看到有明显不该上线的文件比如本地配置、账号密码在提交之前把它放进.gitignore这个问题我在第8章细讲。4.3 阶段三git commit拍下第一个存档点暂存区准备好了执行git commit -m 第一次提交-m后面的内容是这条提交的说明文字最好写清楚这次干了什么比如“添加完整网页结构”而不是写“1111”这种无意义内容。良好的提交信息在你以后翻版本历史的时候极其有用。可以把整个流程理解为拍照git add是让人物站好队暂存区git commit是按下快门生成一个不可变的时间戳快照。快门按下去之后这一步的改动就被永久记录在Git时间线里了想回滚、想对比差异都行。4.4 提交前必须配置的身份信息如果这是你第一次在电脑上执行Git提交直接运行git commit时会提示需要配置user.name和user.email。没有这两项Commit操作会被Git拦下报错信息类似Please tell me who you are。执行git config --global user.name 你的GitHub用户名 git config --global user.email 你注册GitHub的邮箱--global表示全局生效配一次以后这台机器上的所有Git仓库都会使用这个身份。这里填的邮箱最好和GitHub注册邮箱一致这样推送上去的提交记录能正确关联到你的GitHub账号否则会出现“推送成功但仓库Contributors里没有你”的诡异情况。配置完之后再执行一次git commit -m 第一次提交。现在本地仓库已经有了第一个版本该和远端仓库建立联系了。5. 打通本地与远端HTTPS加Token推送的全过程本地仓库和GitHub仓库此时还互不相识需要用git remote命令把两者关联起来然后执行推送。5.1 关联远端仓库地址在GitHub创建好仓库后页面会显示一个仓库地址。复制HTTPS格式的地址形如https://github.com/exampleuser/exampleuser.github.io.git。回到Git Bash执行git remote add origin https://github.com/exampleuser/exampleuser.github.io.git这里origin是一个习惯性叫法表示“远端仓库”。你把它理解成一个快捷方式以后说origin就是指向这个仓库地址。此后再执行git remote -v应该能看到关联的地址信息说明关联成功。5.2 把主干分支统一成main避免分支名不一致的坑GitHub现在默认的主分支名叫main但早些版本的Git在本地执行git init时初始分支名可能是master。两个名字对不上推送时就会遇到“推送失败、找不到远端分支”的报错。统一分支名在推送前执行git branch -M main-M是大写表示强制重命名当前分支。不管之前叫master还是什么这一条命令都会把它改成main。为什么要这么强调我在协助别人排查问题的时候遇到过不止一次本地明明已经commit了推送也提示成功但打开GitHub仓库网页却什么都看不到最后发现是推到了一条隐藏的master分支上而Pages配置的却是main分支。这个问题在第一步就规避掉后面少很多麻烦。5.3 首次推送为什么推荐HTTPS加Token而不是SSH执行推送命令git push -u origin main-u的作用是把本地main分支和远端main分支关联起来以后直接敲git push就能推送不用每次带远程分支名。首次推送时Git会要求你验证身份。关于身份验证新手很容易在HTTPS和SSH之间纠缪。我的建议是第一次先走HTTPS加Token个人访问令牌原因是流程直观不涉及生成密钥对这种额外步骤。SSH虽然配置一次后不用每次输凭据但它需要你在本地生成公钥私钥再把公钥粘贴到GitHub后台密钥管理出错时对新手不太友好。HTTPS加Token的代价是每次推送要输入一次用户名和Token实际使用中忍受度还好。5.4 Personal Access Token的创建步骤Token的生成入口在GitHub网页右上角头像下的Settings里具体路径如下进入Settings。左侧菜单拉到最底部选Developer settings。选择Personal access tokens下的Tokens (classic)。点Generate new token选Generate new token (classic)。在Note里填一个说明比如“上传网页用”。Expiration生命周期按需选我建议选90 days而不是No expiration。Token泄露是真实风险定期过期相当于给账号多一层保护。勾选权限范围repo这一整组基本就够用了。如果你项目里有GitHub Actions相关工作流还要勾上workflow权限否则后续自动化流程会失败。点页面底部的Generate token这时会显示一串形如ghp_xxxxxx的字符串。它只会显示这一次关掉页面后就再也看不到了务必要先复制到本地备用。把Token复制到剪贴板然后在Git Bash里第一次推送弹出用户名提示时输入你的GitHub用户名作为Username密码提示处粘贴这串Token。注意粘贴Token时界面不会显示任何内容这是正常的直接回车即可。5.5 推送时的常见错误远端有本地没有的提交如果在创建GitHub仓库那一刻勾选了Add a README file或者你在网页端手动添加过其他文件推送时Git会拒绝执行并提示类似failed to push some refs的信息。原因很简单远端有了一个本地不存在的提交而本地也有一个远端没有的提交两边历史分叉了。解决办法是先把远端的内容拉到本地合并git pull --rebase origin main--rebase的作用是把你本地的提交“搬”到远端最新提交之上而不是生成一个多余的合并节点历史更干净。执行完再跑一次git push -u origin main通常就能成功。推送过程中另一个常见的当场卡住情况是网络超时这个同样放在第8章统一说。推送完成后打开GitHub仓库主页刷新后就能看到项目文件已经在里面了。到这里“上传到GitHub仓库”这一步已经完成但还没生成那个能访问的网址——下一步才是整个流程的高潮。6. 开启GitHub Pages从仓库到公网网址的临门一脚仓库里已经有代码了现在要让GitHub把仓库当网站展示出来。6.1 设定部署分支和目录进入你刚创建的仓库页面点击顶部菜单的Settings在左侧边栏找到Pages注意这个单词后面带个s。在这个页面里能看到一个Build and deployment区块Source下拉框默认是Deploy from a branch就用这个选项不要动。点击下方的Branch下拉菜单把None改成main后面的目录下拉框保持/(root)不变意思是部署仓库根目录里的内容。点击Save保存。到这里Pages已经开启了GitHub会开始构建网站并发布。构建过程一般只需要一两分钟刷新Pages设置页面顶部会出现一条蓝色横幅显示你的站点地址https://exampleuser.github.io。把这个地址复制到新标签页打开网页就上线了。这个过程背后的逻辑值得点一句main分支代表你部署的“版本”/(root)代表你部署的“目录”。你以后每做一次修改并推送到main分支GitHub都会自动重新构建一遍这个站点不需要手动重复设置。6.2 仓库命名不同访问路径就不同这一点非常关键很多人部署成功却打不开就是栽在这里如果仓库名是用户名.github.io那Pages地址就是https://用户名.github.io直接访问根路径即可。如果仓库名是别的比如my-web-project那Pages地址就会多出一层目录变成https://用户名.github.io/my-web-project/。而且这个带路径的地址在设置页面通常也能够看到只写仓库根域名反而会得到404。所以如果你创建的是非github.io仓库名的项目最后访问时请带上仓库名这个子路径。还有一种容易被忽略的情况GitHub Pages默认是大小写不敏感的但仓库名如果用了一些特殊字符访问路径就格外需要保持一致。6.3 免费方案下的可见性要求前面创建仓库时选Public的决策在开启Pages时正好见效。免费版GitHub账号只有在仓库是Public情况下Pages设置里的Enforce HTTPS等选项才能正常启用。如果你误把仓库设成了PrivatePages页面会提示无法发布或功能受限。如果遇到这种情况直接去仓库Settings下的General最底部把仓库可见性改成Public即可。开启Enforce HTTPS的选项默认就是打开状态一般不需要你去操作。等到页面能访问后浏览器地址栏里那把锁意味着你用的是自动签发的HTTPS证书。如果以后绑定自定义域名这个选项依然要保留开启避免访问时出现安全警告。6.4 部署成功但页面空白先回本地验证偶尔会遇到一种情况Pages设置页面都提示发布成功了打开网址却是一张白纸或什么都没有。这种时候先别急着怀疑部署配置回到本地用浏览器直接打开项目里的index.html先确认本地页面能否正常显示、是否存在console报错。如果本地都报错那线上基本也会报错问题就不在部署而是源代码里原本就有资源路径或脚本执行的问题。比较典型的本地正常、线上白屏的情况是CSS或JS文件用了绝对路径比如href/css/style.css而Pages站点根目录下并没有这个/css目录正确写法应该是hrefcss/style.css或者href./css/style.css。这类问题通过浏览器F12开发者工具看Network面板里有没有404的资源就能立刻定位。7. Page not found的全链路排查从仓库名一路查到浏览器缓存这个章节直接面向最让人头疼的情况设置都弄好了网址也开了但点开就是404 Page not found。GitHub的404页面很有辨识度一个灰色感叹号标志加一行字。出现这个结果的原因有不少按下面顺序逐一排查基本都能定位到。7.1 第一关仓库名无误吗打开仓库主页确认仓库名。如果仓库名不是用户名.github.io那你的Pages地址必然是https://用户名.github.io/仓库名/你访问的如果是裸根域名404是必然结果。这个判断十秒钟就能完成却是出现频率最高的问题没有之一。7.2 第二关Pages真的开启成功了吗重新进入仓库Settings-Pages看是否有报错提示或Your site is live at的字样。如果页面上方显示的是Your site has not been published说明设置没有保存成功或部署未完成。常见于分支选错了比如默认分支是main但在Pages配置里选了master或者没有点Save。改回来再等一下。7.3 第三关分支和目录选择是否与仓库实际内容匹配检查Pages配置里的分支是否为main目录是否为/(root)。如果你的代码推到了master分支而Pages配置的是main那站点永远只有空内容。这种情况并不少见尤其是老旧教程还在用master新手照做后两边名字对不上。用git branch查看当前分支并统一成main是解决思路。7.4 第四关首页文件是否叫index.htmlPages站点是在仓库根目录找index.html当首页的。如果你的首页叫default.html或page.html访问根地址就会404。另外还要注意Linux服务器环境下文件名大小写敏感Index.html和index.html是两个不同的文件。仓库里如果只有一个Index.htmlPages依然找不到。把文件重命名为小写index.html再推送一次。7.5 第五关GitHub Actions构建是否报错跳过以前的源码提交方式GitHub现在还会用Actions来执行Pages部署。你可以到仓库的Actions标签页看有没有正在运行或已经失败的workflow。如果部署工作流出错了会在日志里给出具体原因。有些错误是仓库中某个文件路径过长有些是缺少某个依赖日志会直接指出。这是排查Pages 404时很容易忽略的入口但往往最直接。7.6 第六关等一下并清掉浏览器缓存GitHub Pages从推送到生效存在几秒到几分钟的延迟。如果你刚刚部署完立刻访问遇到404可以先等两分钟再试。排除掉站点本身的因素后浏览器缓存也会导致你一直看到旧的404页面。使用CtrlF5执行一次强制刷新或者直接开一个无痕窗口访问往往立竿见影。按这套链路走一遍绝大多数Page not found都能找到答案。排查的核心心态是不要慌着改设置先逐层确认“仓库名对不对、Pages开没开、分支对不对、入口文件有没有、构建成功没”这五关全过站点就一定出得来。8. 顺手解决两个高频问题GitHub访问不稳定和大文件推不上去最后补充两个我在实际使用中最常遇到的环境问题。它们不是Git操作本身的问题但处理不好会让人误以为自己的部署流程出了问题。8.1 GitHub访问慢或打不开的合规应对思路GitHub的服务器部分部署在境外国内网络环境访问它时偶尔会出现打不开、下载慢、图片加载不出来的情况。这属于跨境网络链路的客观情况不是什么神秘故障也不需要做什么特殊操作。我自己的处理习惯是避开高峰时段工作日晚间是国际网络访问高峰期很多页面卡住和这个时段高度相关。如果只是临时看文档、传小文件换个时间通常就好了。刷新DNS解析在Windows命令行执行ipconfig /flushdns把本机的DNS缓存清掉有时能解决“映射到一个不可用IP”导致打不开的问题。换一个公共DNS把系统网络设置里的DNS改成223.5.5.5阿里DNS或119.29.29.29腾讯DNS有时比默认DNS更稳定。改完同样建议刷新一下DNS缓存。下载发布包或大文件时优先使用国内高校或开源站提供的镜像下载源比如清华大学的开源软件镜像站等。这类镜像站通常会把GitHub上热门项目的Release安装包做一份同步下载速度会明显更快。需要特别提醒的是不要为了图快使用来路不明的第三方“加速工具”或“镜像网站”。这些站点可能夹带恶意脚本还有窃取账号密码的风险尤其是需要你输入GitHub账号密码或Token的那种碰都不要碰。GitHub官方支持的加速方式就是通过配置里的CDN设置和镜像站这些信息会有官方说明沉淀。8.2 推送大文件被拒100MB限制与Git LFSGitHub对单文件有100MB的硬限制超过这个大小推送命令会直接报错并拒绝。网站里如果集成了体积较大的演示视频、安装包、数据集很容易触发这个限制。解决方案按优先级排列如果这个文件不是项目必需可以把它从仓库中移除改用外部链接引用。如果必须保留在仓库里使用Git LFSLarge File Storage。安装Git LFS插件后项目里执行git lfs track *.zip把大文件类型的扩展名登记进LFS后续推送时Git会把这些文件走独立的存储通道不受100MB限制。但GitHub LFS免费额度只有1GB存储和每月1GB流量对个人小项目足够对大文件要谨慎使用。如果只是想分享一个文件给人看不要放进仓库传到网盘发链接更方便也避免了Git仓库体积失控。Git仓库一旦存过大文件Git历史里会永久携带它即使后来删掉仓库体积也不会缩小所以一开始就要拦住。8.3 .gitignore让不必要和敏感文件永远不进仓库配合git add .使用.gitignore这个文件的作用是“排除掉某些文件或目录不让git add .误加它们”。项目里常见的写入内容有node_modules/ .DS_Store *.log .env dist/其中.env这类文件尤其要注意建议一开始就把所有环境变量、密钥、数据库口令文件都写进.gitignore。GitHub仓库一旦设为Public全世界都能看到仓库内容任何一次误提交都会变成公开泄露事故。等推上去再发现哪怕删掉文件历史里依然能找到原文安全上十分被动。把.env扼杀在add之前是最稳妥的做法。写在最后一点长期使用的体会这套流程走通一遍之后你就会发现更新网站的思路彻底变了。本地改代码、git add、git commit、git push四条命令循环往复你的网页每次更新都会在仓库里留下记录不怕改坏、不怕误删、不怕回到旧版本。GitHub Pages本身是免费的没有服务器成本对一个个人项目或作品集来说再合适不过。我最初把第一个页面推上去的时候也经历了打不开、404、分支名对不上一连串问题。现在回头想那些坑多数不是“不会写代码”导致的而是概念没理顺、步骤顺序错了。希望这篇按实际操作顺序写的教程能帮你把从本地到上线这条路一次走通。