1. 项目概述用 GitHub Pages 零成本发布个人网站不是“上传就完事”的幻觉你有没有过这种经历花一晚上用 HTML CSS 写了个干净利落的个人作品页本地双击index.html看着挺美但想发给朋友、投简历、贴在社交主页上——卡住了。没有域名没有服务器连个能复制粘贴的链接都拿不出来。这时候有人告诉你“GitHub 就能免费帮你搞定”你点开 GitHub 页面新建仓库、拖文件、点 Settings……五分钟后页面显示 404。你开始怀疑是不是自己漏了哪步是不是 HTML 写错了是不是网络问题甚至怀疑 GitHub Pages 是不是又悄悄改规则了。我从 2017 年起用 GitHub Pages 部署过 37 个静态站点——学生作业展示页、开源项目文档站、小团队内部知识库、甚至临时活动落地页。踩过的坑比写过的 HTML 标签还多。这篇文章不讲“GitHub 是什么”这种百科式定义也不复述官网文档里藏得极深的默认行为逻辑。我要带你拆解的是为什么你按教程操作却总卡在最后一步为什么明明文件结构一模一样别人能访问你的就是 404为什么改个 CSS 路径整个页面就白屏这些问题背后不是你手速慢而是 GitHub Pages 的部署机制有三套并行的“隐性规则”它们不写在欢迎页上却直接决定你的 URL 能不能被浏览器打开。核心关键词是Deployment——但这个词在这里不是动词而是名词它指代一个完整、可验证、可复现的交付闭环。它包含三个不可割裂的环节源码组织规范Source Layout→ 构建触发条件Build Trigger→ 域名解析路径URL Resolution。绝大多数人只盯着第三步的 URL却把前两步当成“随便放就行”的背景板。结果就是文件传上去了Settings 里也勾选了 Pages但 GitHub 根本没启动构建流程或者构建完了却找不到入口文件。这篇文章要做的就是把这三层规则全部摊开用你本地就能验证的方式一条一条对齐。你不需要懂 Git 命令行不需要装 Node.js甚至不需要注册域名——但你必须理解GitHub Pages 不是 FTP 上传工具它是一个基于 Git 提交历史的静态站点编译服务。它的“部署”本质是让 GitHub 的服务器读取你的代码仓库执行一次轻量级构建再把输出结果挂载到特定子域名下。这个过程有且仅有两种合法启动方式一种叫User/Organization Pages对应username.github.io另一种叫Project Pages对应username.github.io/repo-name。你选错其中任何一种后续所有操作都会变成无效劳动。下面我们就从最致命的第一步——仓库命名与类型选择——开始深挖。2. 部署模式深度拆解User Pages 与 Project Pages 的本质区别与选型逻辑很多人第一次部署失败根源不在代码而在创建仓库时随手输的一个名字。GitHub Pages 的两种模式不是“功能开关”而是由仓库命名规则硬编码绑定的底层架构。你无法在 Settings 里把一个普通项目仓库强行切换成 User Pages就像你不能把一辆自行车的车架焊接到高铁轨道上。我们必须先搞清这两条路的物理边界再决定往哪条道上开车。2.1 User Pages个人品牌主页的“唯一身份证”User Pages 的仓库名必须严格等于username.github.io其中username是你的 GitHub 用户名全小写无空格无特殊字符。例如我的用户名是zhangsan那么仓库名必须是zhangsan.github.io。注意这不是建议这是强制校验。如果你创建了一个叫my-portfolio的仓库然后在 Settings → GitHub Pages 里手动选 master branch它依然不会生成https://zhangsan.github.io/这个根域名地址——因为 GitHub 的路由系统压根不会为这个仓库分配根域名权限。为什么设计成这样因为 User Pages 的定位非常明确它是你在 GitHub 上的个人数字身份主页。就像你的邮箱是namedomain.com这个username.github.io就是你在开发者世界的“邮箱地址”。它天然具备两个特性第一全局唯一性。全世界只能有一个zhangsan.github.io这保证了你的个人品牌不会被冒用第二零路径层级。访问https://zhangsan.github.io/时GitHub 会直接查找该仓库根目录下的index.html不接受任何子路径重写。你不能通过配置让它指向/src/index.html或/dist/index.html它只认/index.html。实操中最大的陷阱是有人为了图省事在 User Pages 仓库里塞进多个项目比如把博客、作品集、简历全放在一个仓库里然后用不同 HTML 文件做导航。这会导致严重问题——所有页面的相对路径引用比如link relstylesheet hrefcss/style.css在根域名下是正确的但一旦你点击某个链接跳转到/blog/index.htmlCSS 路径就会变成https://zhangsan.github.io/blog/css/style.css而实际文件还在/css/style.css。浏览器找不到页面就变白板。所以 User Pages 仓库的黄金法则是它只适合承载一个单一、自洽的前端应用且所有资源引用必须以根路径/开头或使用绝对路径。我见过太多人在这里栽跟头最后不得不把一个仓库拆成三个。2.2 Project Pages项目独立站点的“沙盒容器”Project Pages 的仓库名可以是任意合法名称比如my-awesome-app、>python3 -m http.server 8000然后访问http://localhost:8000。这模拟了 GitHub Pages 的静态服务行为——它不运行 Jekyll只 serve 文件。如果这里能正常显示说明你的文件结构和路径 100% 正确如果不行问题一定在结构上。第三步检查 GitHub 仓库的“Raw”视图进入你的 GitHub 仓库点击index.html文件再点右上角的 “Raw” 按钮。浏览器会直接显示 HTML 源码。如果能看到完整的 HTML 内容说明文件已正确上传如果显示 404说明你可能传到了错误的分支或者文件名大小写错了GitHub 对大小写敏感。这三步做完你的部署成功率会从 50% 直接拉到 95%。剩下的 5%通常是网络缓存或 GitHub 的全球 CDN 更新延迟等 2 分钟再刷就行。4. 实操全流程详解从零创建到 URL 可访问的每一步细节现在我们把前面所有原理落地成一份可逐字照抄的操作清单。我会用一个真实场景演示为一个刚写好的个人作品集页面纯 HTML/CSS/JS部署到 GitHub Pages。全程不依赖任何命令行全部用 GitHub 网页界面完成确保小白也能跟上。关键细节我会标出“为什么这么操作”避免你成为只会复制粘贴的机器人。4.1 创建仓库命名即命运一步错步步错操作步骤登录 GitHub点击右上角→New repository在Repository name输入框严格按你的需求输入如果你要做个人主页如zhangsan.github.io这里必须填zhangsan.github.io把zhangsan替换成你的用户名如果你要做项目页如my-portfolio这里就填my-portfolioDescription可以写“Personal portfolio website”不重要但建议写方便日后搜索关键设置Public单选框必须打勾Private 仓库无法启用 GitHub PagesInitialize this repository with a README不要勾选因为我们要上传自己的index.htmlREADME 会干扰初始结构.gitignore和Add a license全部留空我们不需要为什么这样设置不勾选 README是为了避免 GitHub 自动生成一个README.md文件占据根目录。虽然它不影响index.html但会增加一个不必要的文件且如果你后续用命令行推送可能引发合并冲突。保持根目录“干净”是减少意外的第一步。而 Public 是硬性要求——GitHub Pages 的服务协议明确规定只有公开仓库才能获得 Pages 功能这是平台策略不是 bug。4.2 上传文件拖拽不是万能的结构才是命门操作步骤进入刚创建的空仓库页面你会看到 “Quick setup — if you’ve done this before” 提示忽略它点击绿色按钮Add file→Upload files把你本地的整个项目文件夹包含index.html、css/、js/等全部选中拖拽到上传区域确保所有文件都显示在上传预览区特别检查index.html是否在最顶层没有被包在子文件夹里滚动到页面底部Commit changes区域Commit message填 “Initial commit: add portfolio site”Commit directly to the master branch保持选中点击Commit changes为什么强调“拖拽到最顶层”GitHub 的网页上传有个反直觉行为如果你拖拽的是一个文件夹它会把整个文件夹作为子目录上传。比如你拖拽my-portfolio/文件夹结果仓库里会出现my-portfolio/index.html而不是你需要的index.html。正确做法是在文件管理器里进入你的项目文件夹全选index.html、css/、js/等所有文件和文件夹然后拖拽这些“个体”而不是拖拽父文件夹。这样它们才会平铺在仓库根目录。4.3 启用 GitHub PagesSettings 里的隐藏开关操作步骤上传完成后点击仓库顶部的Settings标签页不是 Code 标签在左侧菜单滚动到底部点击Pages不是GitHub Pages注意名称在Source区域你会看到一个下拉菜单如果你创建的是 User Pages仓库名username.github.io直接选择Deploy from a branch→Branch: master→Folder: /(root)如果你创建的是 Project Pages仓库名my-portfolio同样选择Deploy from a branch→Branch: master→Folder: /(root)不要选gh-pages分支那是老式做法master 分支更直观点击Save页面会自动刷新几秒后你会看到一个绿色提示条Your site is ready to be published at https://zhangsan.github.io/或Your site is ready to be published at https://zhangsan.github.io/my-portfolio/为什么Folder: /(root)是唯一正确选项这个设置决定了 GitHub Pages 从仓库的哪个位置开始查找index.html。/(root)表示根目录正是我们前面强调的“index.html必须在根目录”的物理实现。如果你误选了/docs它就会去找docs/index.html而你的文件在根目录自然 404。这个选项看似简单却是 80% 的 404 错误的直接原因。4.4 验证与调试当 URL 显示 404 时三分钟定位法即使你完美执行了以上步骤首次访问 URL 仍可能显示 404。别慌按这个顺序查90% 的问题能在 3 分钟内解决第一步确认 GitHub Pages 构建状态回到Settings → Pages页面查看Build and deployment区域是否有黄色警告图标如果有点开它会显示构建日志。最常见的错误是File not found: /index.html→ 说明index.html不在根目录检查上传步骤Invalid YAML in _config.yml→ 说明_config.yml有语法错误删掉它或修复缩进Page build failed→ 通常因_config.yml引用了不存在的插件加.nojekyll文件解决第二步用 “Raw” 链接验证文件存在性在 GitHub 仓库里点击index.html文件点右上角Raw按钮复制浏览器地址栏的 URL形如https://raw.githubusercontent.com/username/repo-name/master/index.html在新标签页打开这个 Raw 链接。如果能看到 HTML 源码证明文件已正确上传如果 404说明上传失败或分支选错第三步检查浏览器控制台Console访问你的 GitHub Pages URL如https://zhangsan.github.io/按F12打开开发者工具切换到Console标签如果看到Failed to load resource: the server responded with a status of 404 ()后面跟着css/style.css说明 CSS 路径错了。此时回看你的index.html确认link标签的href是css/style.css不是./css/style.css或/css/style.css前者多余后者在 User Pages 外会错实操心得我给自己定了一条铁律——每次修改index.html后必用python3 -m http.server 8000本地测试再推送到 GitHub。因为本地服务能 100% 复现 GitHub Pages 的路径解析逻辑而浏览器双击打开则不能file:// 协议限制。这条习惯帮我避开了至少 20 次线上 404。5. 常见问题与独家排查技巧那些官方文档不会告诉你的真相GitHub Pages 的文档写得像教科书但现实中的问题往往藏在文档的缝隙里。下面这些是我从 37 次部署中提炼出的“血泪经验”全是官方文档闭口不提但你迟早会撞上的硬核问题。5.1 问题速查表症状、原因、解决方案症状可能原因解决方案我的实测耗时URL 打开是 GitHub 默认 404 页面不是你的 404.htmlGitHub Pages 服务未启用或构建从未成功进入Settings → Pages确认Source已保存且Build and deployment区域无红色错误提示若无提示手动点Save强制触发构建30 秒URL 打开是你的 404.html但index.html确实存在index.html文件名大小写错误如Index.html或上传到了子目录在 GitHub 仓库里直接点击index.html看能否打开若不能说明文件名或路径错用Raw链接验证1 分钟页面白屏Console 显示 CSS/JS 404HTML 中的资源路径用了绝对路径/css/style.css但在 Project Pages 下应为相对路径css/style.css检查index.html中所有link和script的href/src属性删除开头的/User Pages 则必须加/2 分钟修改后刷新页面没变化还是旧版GitHub 的全球 CDN 缓存尤其对 CSS/JS 文件缓存时间长达 10 分钟在 CSS/JS 链接后加版本参数如link relstylesheet hrefcss/style.css?v1.0.1或强制刷新CtrlF50 分钟预防胜于治疗点击链接跳转后CSS 全丢页面变白板使用了相对路径../css/style.css但跳转后当前路径层级变了统一改用根路径/css/style.cssUser Pages或同级相对路径css/style.cssProject Pages避免../3 分钟5.2 独家技巧让部署稳如磐石的三个小动作技巧一用?ts参数强制刷新 CDNGitHub Pages 的 CDN 缓存很顽固有时改了 CSS刷新几十次还是旧样式。最简单的破局法在浏览器地址栏 URL 末尾加?ts123数字随意然后回车。这会让 CDN 认为是新请求绕过缓存。我常用?ts$(date %s)Mac/Linux一秒生成时间戳永不重复。技巧二在index.html里加一行“部署时间戳”在index.html底部加一行!-- Deployed at: 2023-10-15 14:22:35 --每次推送前手动更新这个时间。这样你一眼就能看出当前页面是哪个版本避免“我以为推了其实没推”的乌龙。这个习惯让我少查了 5 次 Git 日志。技巧三用curl命令行验证部署状态Windows 也可用在终端Mac/Linux或 PowerShellWindows里执行curl -I https://zhangsan.github.io/查看返回的 HTTP 头。如果看到HTTP/2 200说明服务正常如果看到HTTP/2 404说明还没构建好如果看到HTTP/2 301说明你可能用了重定向需要检查 CNAME。这个命令比刷网页快十倍是我上线前的必检项。5.3 那些年我们信了的“伪常识”伪常识一“必须用gh-pages分支”老教程里常说要把代码推到gh-pages分支。这是过时的。GitHub 早在 2016 年就支持从master或main分支直接部署且更稳定。gh-pages分支现在主要用于需要分离源码和构建产物的场景如 VuePress 项目对纯静态页是过度设计。伪常识二“CNAME文件必须放在根目录”是的但它还有个隐藏规则CNAME文件内容必须是纯域名不能带http://或https://且末尾不能有/。比如你要绑定my-site.comCNAME文件内容只能是my-site.com多一个空格、多一个斜杠都会导致绑定失败。我曾为一个空格调试了 40 分钟。伪常识三“GitHub Pages 不支持 HTTPS”完全错误。GitHub Pages强制启用 HTTPS且自动续期证书。你访问http://username.github.io会被 301 重定向到https://。这是平台级保障无需任何配置。如果你的页面里有http://的资源链接浏览器会直接拦截Mixed Content导致白屏。所以检查所有外部链接把http://换成https://或用协议相对链接//cdn.jsdelivr.net/npm/jquery3.6.0/dist/jquery.min.js。最后分享一个真实教训去年我帮一个设计师部署作品集她坚持要用http://链接 Dribbble 的图片结果在 Chrome 里白屏Safari 却正常。折腾半天才发现是 Mixed Content 拦截。我把所有http://换成https://问题瞬间消失。这件事让我明白部署不是终点而是把你的网站放进真实用户浏览器环境的第一步。兼容性、安全性、缓存策略这些“看不见的层”往往比写 HTML 更决定成败。
1. 项目概述用 GitHub Pages 零成本发布个人网站不是“上传就完事”的幻觉你有没有过这种经历花一晚上用 HTML CSS 写了个干净利落的个人作品页本地双击index.html看着挺美但想发给朋友、投简历、贴在社交主页上——卡住了。没有域名没有服务器连个能复制粘贴的链接都拿不出来。这时候有人告诉你“GitHub 就能免费帮你搞定”你点开 GitHub 页面新建仓库、拖文件、点 Settings……五分钟后页面显示 404。你开始怀疑是不是自己漏了哪步是不是 HTML 写错了是不是网络问题甚至怀疑 GitHub Pages 是不是又悄悄改规则了。我从 2017 年起用 GitHub Pages 部署过 37 个静态站点——学生作业展示页、开源项目文档站、小团队内部知识库、甚至临时活动落地页。踩过的坑比写过的 HTML 标签还多。这篇文章不讲“GitHub 是什么”这种百科式定义也不复述官网文档里藏得极深的默认行为逻辑。我要带你拆解的是为什么你按教程操作却总卡在最后一步为什么明明文件结构一模一样别人能访问你的就是 404为什么改个 CSS 路径整个页面就白屏这些问题背后不是你手速慢而是 GitHub Pages 的部署机制有三套并行的“隐性规则”它们不写在欢迎页上却直接决定你的 URL 能不能被浏览器打开。核心关键词是Deployment——但这个词在这里不是动词而是名词它指代一个完整、可验证、可复现的交付闭环。它包含三个不可割裂的环节源码组织规范Source Layout→ 构建触发条件Build Trigger→ 域名解析路径URL Resolution。绝大多数人只盯着第三步的 URL却把前两步当成“随便放就行”的背景板。结果就是文件传上去了Settings 里也勾选了 Pages但 GitHub 根本没启动构建流程或者构建完了却找不到入口文件。这篇文章要做的就是把这三层规则全部摊开用你本地就能验证的方式一条一条对齐。你不需要懂 Git 命令行不需要装 Node.js甚至不需要注册域名——但你必须理解GitHub Pages 不是 FTP 上传工具它是一个基于 Git 提交历史的静态站点编译服务。它的“部署”本质是让 GitHub 的服务器读取你的代码仓库执行一次轻量级构建再把输出结果挂载到特定子域名下。这个过程有且仅有两种合法启动方式一种叫User/Organization Pages对应username.github.io另一种叫Project Pages对应username.github.io/repo-name。你选错其中任何一种后续所有操作都会变成无效劳动。下面我们就从最致命的第一步——仓库命名与类型选择——开始深挖。2. 部署模式深度拆解User Pages 与 Project Pages 的本质区别与选型逻辑很多人第一次部署失败根源不在代码而在创建仓库时随手输的一个名字。GitHub Pages 的两种模式不是“功能开关”而是由仓库命名规则硬编码绑定的底层架构。你无法在 Settings 里把一个普通项目仓库强行切换成 User Pages就像你不能把一辆自行车的车架焊接到高铁轨道上。我们必须先搞清这两条路的物理边界再决定往哪条道上开车。2.1 User Pages个人品牌主页的“唯一身份证”User Pages 的仓库名必须严格等于username.github.io其中username是你的 GitHub 用户名全小写无空格无特殊字符。例如我的用户名是zhangsan那么仓库名必须是zhangsan.github.io。注意这不是建议这是强制校验。如果你创建了一个叫my-portfolio的仓库然后在 Settings → GitHub Pages 里手动选 master branch它依然不会生成https://zhangsan.github.io/这个根域名地址——因为 GitHub 的路由系统压根不会为这个仓库分配根域名权限。为什么设计成这样因为 User Pages 的定位非常明确它是你在 GitHub 上的个人数字身份主页。就像你的邮箱是namedomain.com这个username.github.io就是你在开发者世界的“邮箱地址”。它天然具备两个特性第一全局唯一性。全世界只能有一个zhangsan.github.io这保证了你的个人品牌不会被冒用第二零路径层级。访问https://zhangsan.github.io/时GitHub 会直接查找该仓库根目录下的index.html不接受任何子路径重写。你不能通过配置让它指向/src/index.html或/dist/index.html它只认/index.html。实操中最大的陷阱是有人为了图省事在 User Pages 仓库里塞进多个项目比如把博客、作品集、简历全放在一个仓库里然后用不同 HTML 文件做导航。这会导致严重问题——所有页面的相对路径引用比如link relstylesheet hrefcss/style.css在根域名下是正确的但一旦你点击某个链接跳转到/blog/index.htmlCSS 路径就会变成https://zhangsan.github.io/blog/css/style.css而实际文件还在/css/style.css。浏览器找不到页面就变白板。所以 User Pages 仓库的黄金法则是它只适合承载一个单一、自洽的前端应用且所有资源引用必须以根路径/开头或使用绝对路径。我见过太多人在这里栽跟头最后不得不把一个仓库拆成三个。2.2 Project Pages项目独立站点的“沙盒容器”Project Pages 的仓库名可以是任意合法名称比如my-awesome-app、>python3 -m http.server 8000然后访问http://localhost:8000。这模拟了 GitHub Pages 的静态服务行为——它不运行 Jekyll只 serve 文件。如果这里能正常显示说明你的文件结构和路径 100% 正确如果不行问题一定在结构上。第三步检查 GitHub 仓库的“Raw”视图进入你的 GitHub 仓库点击index.html文件再点右上角的 “Raw” 按钮。浏览器会直接显示 HTML 源码。如果能看到完整的 HTML 内容说明文件已正确上传如果显示 404说明你可能传到了错误的分支或者文件名大小写错了GitHub 对大小写敏感。这三步做完你的部署成功率会从 50% 直接拉到 95%。剩下的 5%通常是网络缓存或 GitHub 的全球 CDN 更新延迟等 2 分钟再刷就行。4. 实操全流程详解从零创建到 URL 可访问的每一步细节现在我们把前面所有原理落地成一份可逐字照抄的操作清单。我会用一个真实场景演示为一个刚写好的个人作品集页面纯 HTML/CSS/JS部署到 GitHub Pages。全程不依赖任何命令行全部用 GitHub 网页界面完成确保小白也能跟上。关键细节我会标出“为什么这么操作”避免你成为只会复制粘贴的机器人。4.1 创建仓库命名即命运一步错步步错操作步骤登录 GitHub点击右上角→New repository在Repository name输入框严格按你的需求输入如果你要做个人主页如zhangsan.github.io这里必须填zhangsan.github.io把zhangsan替换成你的用户名如果你要做项目页如my-portfolio这里就填my-portfolioDescription可以写“Personal portfolio website”不重要但建议写方便日后搜索关键设置Public单选框必须打勾Private 仓库无法启用 GitHub PagesInitialize this repository with a README不要勾选因为我们要上传自己的index.htmlREADME 会干扰初始结构.gitignore和Add a license全部留空我们不需要为什么这样设置不勾选 README是为了避免 GitHub 自动生成一个README.md文件占据根目录。虽然它不影响index.html但会增加一个不必要的文件且如果你后续用命令行推送可能引发合并冲突。保持根目录“干净”是减少意外的第一步。而 Public 是硬性要求——GitHub Pages 的服务协议明确规定只有公开仓库才能获得 Pages 功能这是平台策略不是 bug。4.2 上传文件拖拽不是万能的结构才是命门操作步骤进入刚创建的空仓库页面你会看到 “Quick setup — if you’ve done this before” 提示忽略它点击绿色按钮Add file→Upload files把你本地的整个项目文件夹包含index.html、css/、js/等全部选中拖拽到上传区域确保所有文件都显示在上传预览区特别检查index.html是否在最顶层没有被包在子文件夹里滚动到页面底部Commit changes区域Commit message填 “Initial commit: add portfolio site”Commit directly to the master branch保持选中点击Commit changes为什么强调“拖拽到最顶层”GitHub 的网页上传有个反直觉行为如果你拖拽的是一个文件夹它会把整个文件夹作为子目录上传。比如你拖拽my-portfolio/文件夹结果仓库里会出现my-portfolio/index.html而不是你需要的index.html。正确做法是在文件管理器里进入你的项目文件夹全选index.html、css/、js/等所有文件和文件夹然后拖拽这些“个体”而不是拖拽父文件夹。这样它们才会平铺在仓库根目录。4.3 启用 GitHub PagesSettings 里的隐藏开关操作步骤上传完成后点击仓库顶部的Settings标签页不是 Code 标签在左侧菜单滚动到底部点击Pages不是GitHub Pages注意名称在Source区域你会看到一个下拉菜单如果你创建的是 User Pages仓库名username.github.io直接选择Deploy from a branch→Branch: master→Folder: /(root)如果你创建的是 Project Pages仓库名my-portfolio同样选择Deploy from a branch→Branch: master→Folder: /(root)不要选gh-pages分支那是老式做法master 分支更直观点击Save页面会自动刷新几秒后你会看到一个绿色提示条Your site is ready to be published at https://zhangsan.github.io/或Your site is ready to be published at https://zhangsan.github.io/my-portfolio/为什么Folder: /(root)是唯一正确选项这个设置决定了 GitHub Pages 从仓库的哪个位置开始查找index.html。/(root)表示根目录正是我们前面强调的“index.html必须在根目录”的物理实现。如果你误选了/docs它就会去找docs/index.html而你的文件在根目录自然 404。这个选项看似简单却是 80% 的 404 错误的直接原因。4.4 验证与调试当 URL 显示 404 时三分钟定位法即使你完美执行了以上步骤首次访问 URL 仍可能显示 404。别慌按这个顺序查90% 的问题能在 3 分钟内解决第一步确认 GitHub Pages 构建状态回到Settings → Pages页面查看Build and deployment区域是否有黄色警告图标如果有点开它会显示构建日志。最常见的错误是File not found: /index.html→ 说明index.html不在根目录检查上传步骤Invalid YAML in _config.yml→ 说明_config.yml有语法错误删掉它或修复缩进Page build failed→ 通常因_config.yml引用了不存在的插件加.nojekyll文件解决第二步用 “Raw” 链接验证文件存在性在 GitHub 仓库里点击index.html文件点右上角Raw按钮复制浏览器地址栏的 URL形如https://raw.githubusercontent.com/username/repo-name/master/index.html在新标签页打开这个 Raw 链接。如果能看到 HTML 源码证明文件已正确上传如果 404说明上传失败或分支选错第三步检查浏览器控制台Console访问你的 GitHub Pages URL如https://zhangsan.github.io/按F12打开开发者工具切换到Console标签如果看到Failed to load resource: the server responded with a status of 404 ()后面跟着css/style.css说明 CSS 路径错了。此时回看你的index.html确认link标签的href是css/style.css不是./css/style.css或/css/style.css前者多余后者在 User Pages 外会错实操心得我给自己定了一条铁律——每次修改index.html后必用python3 -m http.server 8000本地测试再推送到 GitHub。因为本地服务能 100% 复现 GitHub Pages 的路径解析逻辑而浏览器双击打开则不能file:// 协议限制。这条习惯帮我避开了至少 20 次线上 404。5. 常见问题与独家排查技巧那些官方文档不会告诉你的真相GitHub Pages 的文档写得像教科书但现实中的问题往往藏在文档的缝隙里。下面这些是我从 37 次部署中提炼出的“血泪经验”全是官方文档闭口不提但你迟早会撞上的硬核问题。5.1 问题速查表症状、原因、解决方案症状可能原因解决方案我的实测耗时URL 打开是 GitHub 默认 404 页面不是你的 404.htmlGitHub Pages 服务未启用或构建从未成功进入Settings → Pages确认Source已保存且Build and deployment区域无红色错误提示若无提示手动点Save强制触发构建30 秒URL 打开是你的 404.html但index.html确实存在index.html文件名大小写错误如Index.html或上传到了子目录在 GitHub 仓库里直接点击index.html看能否打开若不能说明文件名或路径错用Raw链接验证1 分钟页面白屏Console 显示 CSS/JS 404HTML 中的资源路径用了绝对路径/css/style.css但在 Project Pages 下应为相对路径css/style.css检查index.html中所有link和script的href/src属性删除开头的/User Pages 则必须加/2 分钟修改后刷新页面没变化还是旧版GitHub 的全球 CDN 缓存尤其对 CSS/JS 文件缓存时间长达 10 分钟在 CSS/JS 链接后加版本参数如link relstylesheet hrefcss/style.css?v1.0.1或强制刷新CtrlF50 分钟预防胜于治疗点击链接跳转后CSS 全丢页面变白板使用了相对路径../css/style.css但跳转后当前路径层级变了统一改用根路径/css/style.cssUser Pages或同级相对路径css/style.cssProject Pages避免../3 分钟5.2 独家技巧让部署稳如磐石的三个小动作技巧一用?ts参数强制刷新 CDNGitHub Pages 的 CDN 缓存很顽固有时改了 CSS刷新几十次还是旧样式。最简单的破局法在浏览器地址栏 URL 末尾加?ts123数字随意然后回车。这会让 CDN 认为是新请求绕过缓存。我常用?ts$(date %s)Mac/Linux一秒生成时间戳永不重复。技巧二在index.html里加一行“部署时间戳”在index.html底部加一行!-- Deployed at: 2023-10-15 14:22:35 --每次推送前手动更新这个时间。这样你一眼就能看出当前页面是哪个版本避免“我以为推了其实没推”的乌龙。这个习惯让我少查了 5 次 Git 日志。技巧三用curl命令行验证部署状态Windows 也可用在终端Mac/Linux或 PowerShellWindows里执行curl -I https://zhangsan.github.io/查看返回的 HTTP 头。如果看到HTTP/2 200说明服务正常如果看到HTTP/2 404说明还没构建好如果看到HTTP/2 301说明你可能用了重定向需要检查 CNAME。这个命令比刷网页快十倍是我上线前的必检项。5.3 那些年我们信了的“伪常识”伪常识一“必须用gh-pages分支”老教程里常说要把代码推到gh-pages分支。这是过时的。GitHub 早在 2016 年就支持从master或main分支直接部署且更稳定。gh-pages分支现在主要用于需要分离源码和构建产物的场景如 VuePress 项目对纯静态页是过度设计。伪常识二“CNAME文件必须放在根目录”是的但它还有个隐藏规则CNAME文件内容必须是纯域名不能带http://或https://且末尾不能有/。比如你要绑定my-site.comCNAME文件内容只能是my-site.com多一个空格、多一个斜杠都会导致绑定失败。我曾为一个空格调试了 40 分钟。伪常识三“GitHub Pages 不支持 HTTPS”完全错误。GitHub Pages强制启用 HTTPS且自动续期证书。你访问http://username.github.io会被 301 重定向到https://。这是平台级保障无需任何配置。如果你的页面里有http://的资源链接浏览器会直接拦截Mixed Content导致白屏。所以检查所有外部链接把http://换成https://或用协议相对链接//cdn.jsdelivr.net/npm/jquery3.6.0/dist/jquery.min.js。最后分享一个真实教训去年我帮一个设计师部署作品集她坚持要用http://链接 Dribbble 的图片结果在 Chrome 里白屏Safari 却正常。折腾半天才发现是 Mixed Content 拦截。我把所有http://换成https://问题瞬间消失。这件事让我明白部署不是终点而是把你的网站放进真实用户浏览器环境的第一步。兼容性、安全性、缓存策略这些“看不见的层”往往比写 HTML 更决定成败。
![[C++]内存管理：串顺序存储的内存回收](http://pic.xiahunao.cn/yaotu/[C++]内存管理：串顺序存储的内存回收)
