GitHub Pages与Jekyll搭建静态网站全指南-代码聚汇网

GitHub Pages与Jekyll搭建静态网站全指南

二号猎人·2026-08-09·阅读 22 GEO检测（免费）

GitHub PagesJekyll静态网站

|难度：普通|阅读约 17 分钟

1. 为什么选择GitHub Pages搭建个人站点

在技术圈混了这么多年，见过太多人花大价钱买服务器、折腾各种建站工具，最后网站没做出来，倒是把热情消耗殆尽了。直到2013年我第一次把项目文档托管到GitHub Pages，才发现原来搭建个人网站可以如此简单——不需要服务器运维、不需要数据库管理，甚至不需要信用卡支付，一个Git账号就能拥有专属的username.github.io域名站点。

GitHub Pages本质上是一个静态网站托管服务，它直接读取你GitHub仓库里的HTML、CSS和JavaScript文件，自动构建并发布到互联网。与WordPress这类动态网站不同，静态网站的所有内容都是预先生成好的文件，访问时无需实时计算，这使得GitHub Pages具有三个杀手级优势：

完全免费：不像VPS或云主机需要按月付费，GitHub Pages对公开仓库完全免费（私有仓库也有3000次/月的免费构建额度）
零运维成本：不用操心服务器安全补丁、数据库备份、负载均衡这些琐事
天然版本控制：所有修改通过Git提交记录管理，随时可以回滚到历史版本

我自己的技术博客就是用GitHub Pages搭建的，从2015年运行至今，经历了从纯手工编写HTML到使用Jekyll静态生成器的完整演进过程。最让我惊喜的是，即便在访问量突然暴增的情况下（比如某篇文章被Hacker News推荐），GitHub的CDN也能轻松应对，完全不用担心服务器崩溃的问题。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 创建你的第一个GitHub Pages站点

2.1 前置条件准备

在开始之前，你需要确保本地环境已经安装好以下工具（以macOS为例，其他系统类似）：

bash复制# 检查Git是否安装
git --version
# 如果没有安装，用Homebrew安装
brew install git

# 注册GitHub账号（如果还没有）
# 然后配置本地Git用户信息
git config --global user.name "你的GitHub用户名"
git config --global user.email "你的GitHub注册邮箱"

注意：GitHub Pages要求仓库必须设置为Public（除非你使用付费账户）。如果你需要完全私有的站点，可以考虑Netlify或Vercel等替代方案。

2.2 创建专属仓库

登录GitHub后，按照以下步骤创建你的Pages仓库：

点击右上角"+" → "New repository"
在Repository name中输入username.github.io（把username替换为你的GitHub用户名）
选择Public（重要！）
勾选"Add a README file"
点击Create repository

这个特殊的仓库命名规则是GitHub Pages的约定——当你创建username.github.io这样的仓库时，GitHub会自动将其识别为个人站点仓库，并将master/main分支的内容发布到互联网。

2.3 本地开发环境搭建

我强烈建议在本地先测试网站效果，而不是直接推送到GitHub等待构建。下面是具体操作：

bash复制# 克隆仓库到本地
git clone https://github.com/username/username.github.io
cd username.github.io

# 创建首页文件
echo "<h1>Hello World!</h1>" > index.html

# 本地测试（需要安装Python3）
python3 -m http.server 8000

现在打开浏览器访问http://localhost:8000，你应该能看到大大的"Hello World!"标题。这个简单的HTML文件就是你的网站雏形。

3. 使用Jekyll打造专业博客

虽然直接写HTML也能建站，但维护起来非常麻烦。Jekyll作为GitHub Pages官方支持的静态网站生成器，可以让你用Markdown写文章，自动生成导航、分类等复杂功能。

3.1 安装Jekyll环境

在macOS上安装Jekyll需要先安装Ruby环境：

bash复制# 安装Homebrew（如果尚未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 通过Homebrew安装Ruby
brew install ruby

# 将Ruby添加到PATH
echo 'export PATH="/usr/local/opt/ruby/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 安装Jekyll和Bundler
gem install --user-install bundler jekyll

Windows用户可以通过RubyInstaller安装，Linux用户建议使用rbenv或RVM管理Ruby版本。

3.2 创建Jekyll站点

在你的仓库目录下运行：

bash复制jekyll new .

这会生成一个标准的Jekyll项目结构：

code复制.
├── _config.yml       # 站点配置文件
├── _posts/           # 博客文章目录
├── _site/            # 生成的静态文件
├── .gitignore        # Git忽略规则
├── Gemfile           # Ruby依赖管理
├── Gemfile.lock      # 依赖版本锁
└── index.md          # 首页内容

3.3 关键配置解析

打开_config.yml文件，这些配置项最值得关注：

yaml复制title: 你的网站标题       # 显示在浏览器标签和页眉
description: 网站描述     # 用于SEO
baseurl: ""            # 如果站点不在根目录需要修改
url: ""                # 你的GitHub Pages地址，如"https://username.github.io"

# 构建设置
markdown: kramdown     # Markdown解析引擎
plugins:              # 使用的Jekyll插件
  - jekyll-feed
  - jekyll-seo-tag

实际项目中我发现，每次修改_config.yml后需要重启Jekyll服务才能生效，这是新手常踩的坑。

3.4 编写第一篇博客

在_posts目录下创建文件，命名格式必须为YYYY-MM-DD-title.md：

markdown复制---
layout: post
title:  "我的第一篇博客"
date:   2023-07-20 14:30:00 +0800
categories: jekyll update
---

## 欢迎来到我的博客

这里是使用Markdown编写的正文内容...

- 列表项1
- 列表项2

{% highlight ruby %}
def print_hi(name)
  puts "Hi, #{name}"
end
print_hi('Tom')
#=> prints 'Hi, Tom' to STDOUT.
{% endhighlight %}

启动本地预览服务：

bash复制bundle exec jekyll serve

访问http://localhost:4000就能看到带导航栏、时间线和语法高亮的专业博客了。

4. 高级定制与部署技巧

4.1 自定义域名配置

虽然username.github.io已经很好记，但绑定自己的域名会让站点更专业：

在域名注册商处添加CNAME记录：

code复制yourdomain.com CNAME username.github.io
www.yourdomain.com CNAME username.github.io

在仓库根目录创建CNAME文件（无后缀），内容为：
```
code复制yourdomain.com
```
在GitHub仓库Settings → Pages中确认自定义域名

我遇到过DNS缓存导致生效延迟的问题，建议使用dig yourdomain.com命令检查解析是否正确，有时需要等待48小时才能全球生效。

4.2 使用GitHub Actions自动化构建

虽然GitHub Pages会自动构建Jekyll站点，但有时我们需要更复杂的构建流程。比如，我的博客需要额外处理图片压缩：

yaml复制# .github/workflows/build.yml
name: Build and Deploy

on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Set up Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: 2.7
      - name: Install dependencies
        run: |
          gem install bundler
          bundle install
      - name: Build with Jekyll
        run: |
          bundle exec jekyll build
          # 这里可以添加图片压缩等自定义步骤
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./_site

4.3 解决常见构建错误

GitHub Pages构建失败时，邮件会收到通知。最常见的几个错误和解决方法：

依赖冲突：GitHub Pages使用固定版本的Jekyll和插件，解决方法是在Gemfile中指定：
```
ruby复制gem "github-pages", group: :jekyll_plugins
```
然后运行bundle update github-pages
构建超时：如果站点太大，可能超过10分钟构建限制。我的优化方案：
- 使用jekyll-include-cache插件缓存部分内容
- 将图片等资源移到CDN
- 减少实时生成的集合(collection)
自定义插件被禁用：GitHub Pages只支持白名单内的插件。替代方案：
- 本地构建后推送_site文件夹
- 改用GitHub Actions构建
- 使用等效的JavaScript方案

5. 从个人博客到项目文档

GitHub Pages不仅适合个人博客，还是托管项目文档的绝佳选择。我的开源项目就采用如下结构：

code复制docs/
├── _config.yml      # 独立配置
├── _includes/       # 复用组件
├── _layouts/        # 文档专用模板
├── assets/          # 静态资源
└── index.md         # 文档首页

在项目设置中启用GitHub Pages并选择docs目录作为源，就能获得类似https://username.github.io/projectname的文档站点。

对于技术文档，我推荐使用这些Jekyll插件（通过GitHub Actions构建）：

jekyll-remote-theme：直接使用文档主题如Just-the-Docs
jekyll-seo-tag：自动生成SEO标签
jekyll-relative-links：自动转换相对链接
jemoji：支持GitHub风格的表情符号

一个专业的文档配置示例：

yaml复制# docs/_config.yml
theme: just-the-docs
plugins:
  - jekyll-remote-theme
  - jekyll-seo-tag
  - jekyll-relative-links
  - jemoji

just_the_docs:
  # 启用搜索功能
  search: true
  # 自定义导航
  nav_order:
    - index.md
    - getting-started.md
    - api-reference.md

这种设置能让你的项目文档看起来和Vue.js、React等顶级开源项目的文档一样专业。