如何手动为 GitHub 仓库创建 GitHub Pages 页面?

更新时间 2026-10-30

不用自动页面生成器，也可以手动创建 GitHub Pages 站点：在仓库中推送一个名为 gh-pages 的分支，GitHub 就会用该分支的内容生成页面。页面内容可以是常规 HTML，也可以交给 Jekyll 处理，从而获得全站页头页脚和博客支持。onceupon.github.io 这个站点本身就是 GitHub Pages 的默认欢迎页，其说明文字正是这套手动流程的原始出处。

手动创建的核心步骤

1. 准备内容

先在本地准备要发布的文件。最小可用结构是一个 index.html：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8">
  <title>我的项目页</title>
</head>
<body>
  <h1>Hello GitHub Pages</h1>
</body>
</html>

预期结果：本地打开该文件能看到页面内容，说明文件本身没有问题。

2. 创建并推送 gh-pages 分支

在仓库目录下执行：

git checkout --orphan gh-pages
git add .
git commit -m "create gh-pages"
git push origin gh-pages

--orphan 用于创建一个没有历史记录的新分支，避免把主分支的源码一并发布出去。推送成功后，GitHub 会识别 gh-pages 分支并开始构建页面。

3. 验证

推送后等待构建完成，访问 https://<用户名>.github.io/<仓库名>/。如果页面显示的是你提交的 index.html 内容，说明手动创建成功。若显示 404，先确认分支名拼写是否为 gh-pages，再检查仓库的 Pages 设置是否指向该分支。

用 Jekyll 获得页头页脚和博客

GitHub Pages 原生支持 Jekyll。相比在每个 HTML 文件里复制导航和页脚，Jekyll 允许你只写一次布局：

_layouts/default.html   ← 全站页头、页脚、导航
index.md                ← 首页内容
_posts/2024-01-01-hello.md  ← 博客文章

页面文件开头加上 front matter（两行 --- 之间的配置），Jekyll 就会套用布局。这样新增文章只需放进 _posts，页头页脚自动复用，博客列表也能由 Jekyll 生成。

需要注意：Jekyll 对文件命名和目录结构有约定，_posts 中的文件名必须符合 年-月-日-标题.md 格式，否则文章不会被识别。

两种方式怎么选

维度	纯 HTML	Jekyll
上手成本	低，会写 HTML 即可	需要了解 front matter 和目录约定
多页面维护	页头页脚需逐页复制	布局写一次，全站复用
博客支持	需自己实现列表和归档	内置文章与列表机制
适合场景	单页介绍、演示页	文档站、带文章的项目主页

如果只是给项目放一个说明页，纯 HTML 足够；如果预计会持续增加页面或文章，直接用 Jekyll 更省后续维护成本。

常见卡点

分支名错误：必须是 gh-pages，写成 gh_page 或 gh-pages/ 都不会生效。
内容没进分支：确认 git push 的目标是 origin gh-pages，而不是主分支。
Jekyll 文件未被处理：检查 front matter 是否存在、_posts 文件名是否符合日期格式。
构建后仍显示旧内容：Pages 构建有延迟，稍等后强制刷新再验证。

遇到问题时，GitHub Pages 官方文档提供了分支与 Jekyll 的详细说明，也可以联系 GitHub 支持协助排查。