直接推 index.html 到 main 分支即可上线,GitHub Pages 本质是静态托管服务,无需 Jekyll;确保根目录有 index.html、Source 设为 root 的 main 分支、删掉 _config.yml 等干扰文件、用相对路径引用资源、CNAME 文件放根目录、本地预览需 HTTP 服务而非 file://。

直接推 index.html 到 main 分支就能上线,不需要 Jekyll
GitHub Pages 本质就是静态文件托管服务,只要你仓库根目录下有 index.html,选对分支,保存设置后几秒就可访问。很多人误以为必须用 Jekyll,其实纯 HTML/CSS/JS(比如 Bootstrap 官方示例页)完全绕过构建流程,最省事也最稳定。
常见错误现象:404 Not Found 页面、URL 打开空白、提示 “Your site is published at …” 但点不开 —— 基本都是因为没放 index.html 在仓库根目录,或选错了源分支。
- 确保你的项目根目录(不是
src或dist子目录)下存在index.html - 在 GitHub 仓库 Settings → Pages → Source → Branch 选
main(或master,取决于你默认分支名) - Folder 保持默认
(root),不要选/docs或其他子路径,除非你明确把文件放那里了 - 保存后等 30 秒左右,刷新页面,点击生成的 URL 链接(形如
https://).github.io/
_config.yml 和 Jekyll 插件对纯 Bootstrap 网站是干扰项
如果你只是放几个 Bootstrap 页面(比如从 Bootstrap Examples 下载的 starter-template),千万别加 _config.yml 或运行 bundle exec jekyll build。Jekyll 会尝试解析 Liquid 语法、重写链接、插入元数据 —— 这些对原生 HTML 是多余甚至破坏性的。
典型症状:导航栏失效、CSS 路径变成 /assets/css/bootstrap.min.css 却 404、href="#" 被替换成奇怪的相对路径。
- 删掉仓库里所有
_config.yml、_layouts、_includes目录 - 确认所有 CSS/JS 引入路径是相对路径,且文件实际存在(例如
,不是) - 如果用了 Bootstrap 的 JS 组件(如 Collapse、Dropdown),确保已引入
bootstrap.bundle.min.js或配好 Popper
自定义域名和 HTTPS 不需要额外配置,但要注意 CNAME 文件位置
GitHub Pages 对自定义域名支持开箱即用,HTTPS 也自动启用(2018 年起全站强制)。唯一要手动加的,是根目录下的 CNAME 文本文件(无后缀),内容只有一行你的域名,比如 blog.example.com。
在提交旁边记录AI编码会话,以便代理程序可以恢复代码更改的原因、从检查点恢复以及干净地交接工作。
容易踩的坑:CNAME 放在 docs/ 下无效;文件名写成 CNAME.txt 或大小写错误(必须全大写);DNS 解析未生效却反复刷新 GitHub 设置。
-
CNAME文件必须放在仓库根目录,和index.html同级 - 文件内容不能有多余空格、换行或 UTF-8 BOM
- DNS 侧需添加 CNAME 记录指向
(不是 IP).github.io - 修改 DNS 后最长可能需要 72 小时,但通常 1–2 小时内生效;可用
dig blog.example.com CNAME验证
本地预览和路径问题:别信 file:// 双击打开
Bootstrap 的某些功能(如 ScrollSpy、AJAX 加载、部分插件初始化)依赖 HTTP 协议,双击 index.html 用 file:// 打开会失败,控制台报 CORS 或 Failed to load resource。这不是代码问题,是浏览器安全策略。
解决办法很简单:起一个最小 HTTP 服务。无需安装 Node、Python 全家桶,现代浏览器自带支持:
- Chrome / Edge:打开 DevTools → ⚙️ Settings → Preferences → Network → 勾选 “Disable cache (while DevTools is open)” + 用
python3 -m http.server 8000(Python 3 自带) - 或者用 VS Code 安装插件 “Live Server”,右键
index.html→ “Open with Live Server” - 确认地址是
http://localhost:8000,不是file:///xxx/index.html - 检查所有资源路径是否能正常加载(F12 → Network 标签看 200 状态)
真正容易被忽略的是:本地能跑 ≠ GitHub Pages 能跑。因为 GitHub Pages 的 URL 是 https://user.github.io/repo/,所有相对路径都基于这个前缀。如果你的 Bootstrap 页面里写的是 href="about.html",它会请求 /repo/about.html,没问题;但若写了 href="/about.html",就会跳到 /about.html(根目录),404。务必统一用相对路径,不用绝对路径开头的 /。










