跳至主要內容

GitHub Pages部署

bug君2025/7/17...大约 6 分钟

GitHub Pages部署

GitHub Pages是GitHub提供的静态网站托管服务，可以用来托管个人博客、项目文档或个人/组织网站，完全免费且易于使用。

GitHub Pages基础

类型与URL

GitHub Pages有三种基本类型：

  1. 用户/组织站点：

    • 仓库名必须为username.github.io（其中username是你的GitHub用户名）
    • 发布自主分支（通常是main或master）
    • 访问URL：https://username.github.io

  2. 项目站点：

    • 可以是任何仓库名
    • 可以发布自任何分支或特定文件夹
    • 访问URL：https://username.github.io/repository-name

  3. 企业站点：

    • 适用于GitHub Enterprise用户
    • 遵循与用户/组织站点类似的规则

支持的内容类型

GitHub Pages支持以下类型的内容：

  • 纯HTML/CSS/JavaScript静态网站
  • 使用Jekyll构建的静态站点（GitHub内置支持）
  • 使用其他静态站点生成器（如Hugo、Gatsby等）构建的站点，但需要通过CI/CD流程部署

个人博客搭建

使用Jekyll创建博客

Jekyll是GitHub Pages原生支持的静态站点生成器，非常适合创建博客。

方法1：使用Jekyll主题选择器

  1. 创建仓库：username.github.io
  2. 进入仓库设置，找到"Pages"选项
  3. 在"Build and deployment"部分，选择分支和文件夹
  4. 点击"Choose a theme"选择一个Jekyll主题
  5. 编辑自动创建的index.md文件

方法2：从头开始创建Jekyll站点

  1. 安装Jekyll和相关依赖：

    gem install jekyll bundler

  2. 创建新的Jekyll站点：

    jekyll new my-blog
cd my-blog

  3. 本地测试站点：

    bundle exec jekyll serve

  4. 创建GitHub仓库并推送：

    git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/username/username.github.io.git
git push -u origin main

编写博客内容

Jekyll博客文章使用Markdown格式，存放在_posts目录下，文件名格式为YYYY-MM-DD-title.md。

示例文章：

---
layout: post
title: "我的第一篇博客文章"
date: 2023-01-01
categories: blog
---

这是我的第一篇博客文章。

## 二级标题

- 列表项1
- 列表项2

[链接文本](https://example.com)

![图片描述](https://example.com/image.jpg)

自定义博客外观

  1. 修改配置文件：编辑_config.yml文件

    title: 我的博客
description: 分享技术和生活
author: 你的名字

# 社交媒体链接
social:
  twitter: yourusername
  github: yourusername

# 主题设置
theme: minima

  2. 自定义CSS：创建或编辑assets/css/style.scss文件

    @import "{{ site.theme }}";

// 自定义样式
body {
  font-family: 'Open Sans', sans-serif;
}

.site-header {
  background-color: #2c3e50;
}

  3. 添加页面：在根目录创建.md或.html文件

    ---
layout: page
title: 关于我
permalink: /about/
---

这是关于我的页面。

项目文档部署

GitHub Pages是托管项目文档的理想选择，可以让用户直接在线浏览你的项目文档。

基于项目仓库部署文档

  1. 在项目仓库中创建docs目录
  2. 在docs目录中添加文档文件（HTML或Markdown）
  3. 在仓库设置中启用GitHub Pages：
    • 进入仓库的"Settings"选项卡
    • 找到"Pages"部分
    • 在"Source"下选择分支（通常是main或master）和文件夹（/docs）
    • 点击"Save"

使用文档生成工具

MkDocs部署

MkDocs是一个简单的Markdown文档站点生成器。

  1. 安装MkDocs：

    pip install mkdocs

  2. 创建项目：

    mkdocs new my-project-docs
cd my-project-docs

  3. 编辑mkdocs.yml配置文件：

    site_name: 我的项目文档
theme: readthedocs

nav:
  - 首页: index.md
  - 安装指南: installation.md
  - API参考: api.md

  4. 编写文档内容，保存在docs目录下

  5. 本地预览：

    mkdocs serve

  6. 构建静态站点：

    mkdocs build

  7. 部署到GitHub Pages：

    mkdocs gh-deploy

Docsify部署

Docsify是一个无需构建过程的文档站点工具。

  1. 安装Docsify：

    npm install -g docsify-cli

  2. 初始化项目：

    docsify init ./docs

  3. 编辑docs/index.html：

    <!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>我的项目文档</title>
  <meta name="description" content="项目文档">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/vue.css">
</head>
<body>
  <div id="app"></div>
  <script>
    window.$docsify = {
      name: '我的项目',
      repo: 'https://github.com/username/repo',
      loadSidebar: true,
      subMaxLevel: 2,
    }
  </script>
  <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
</body>
</html>

  4. 创建侧边栏配置文件docs/_sidebar.md：

    * [首页](/)
* [指南](guide.md)
* [API参考](api.md)

  5. 本地预览：

    docsify serve docs

  6. 将docs目录推送到GitHub仓库，并在仓库设置中启用GitHub Pages

使用GitHub Actions自动部署文档

可以设置GitHub Actions工作流来自动构建和部署文档：

name: Deploy Documentation

on:
  push:
    branches: [ main ]
    paths: [ 'docs/**' ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.x'
          
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install mkdocs mkdocs-material
          
      - name: Deploy documentation
        run: mkdocs gh-deploy --force

自定义域名配置

你可以使用自己的域名替代默认的github.io域名。

设置自定义域名

  1. 在域名注册商处添加DNS记录：

    • 对于apex域（如example.com）：
      • 添加A记录，指向GitHub Pages的IP地址：
        185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153
    • 对于子域（如docs.example.com）：
      • 添加CNAME记录，指向username.github.io

  2. 在GitHub仓库中配置：

    • 方法1：在仓库设置中的"Pages"部分，填写"Custom domain"字段
    • 方法2：在发布分支的根目录创建名为CNAME的文件，内容为你的域名：
      example.com

启用HTTPS

对于自定义域名，GitHub Pages提供免费的HTTPS支持：

  1. 确保DNS记录已正确设置
  2. 在仓库的"Settings" > "Pages"中，勾选"Enforce HTTPS"选项
  3. 可能需要等待几小时让SSL证书生效

域名迁移与维护

  1. 更改域名：

    • 更新DNS记录
    • 更新仓库中的CNAME文件或GitHub设置

  2. 排查问题：

    • 检查DNS传播（可能需要24-48小时）
    • 验证A记录或CNAME记录是否正确
    • 确认CNAME文件内容正确且没有多余空格或换行

  3. 维护注意事项：

    • 确保域名注册不过期
    • 定期检查DNS设置是否正确
    • 如果更换GitHub用户名，需要更新CNAME记录

高级技巧与最佳实践

使用自定义404页面

创建一个名为404.html或404.md的文件在网站根目录：

---
permalink: /404.html
---

<!DOCTYPE html>
<html>
<head>
  <title>页面未找到</title>
</head>
<body>
  <h1>404 - 页面未找到</h1>
  <p>抱歉，您访问的页面不存在。</p>
  <a href="/">返回首页</a>
</body>
</html>

SEO优化

  1. 添加站点地图：

    • 对于Jekyll站点，添加jekyll-sitemap插件到_config.yml：

      plugins:
  - jekyll-sitemap

    • 对于其他站点，生成sitemap.xml并放在根目录

  2. 添加robots.txt：

    User-agent: *
Allow: /
Sitemap: https://example.com/sitemap.xml

  3. 使用适当的元标记：

    <meta name="description" content="网站描述">
<meta name="keywords" content="关键词1, 关键词2">
<meta name="author" content="作者名">

性能优化

  1. 最小化CSS和JavaScript：

    • 使用压缩工具减小文件大小
    • 考虑使用CDN加载常用库

  2. 优化图片：

    • 压缩图片文件
    • 使用适当的图片格式（WebP、JPEG、PNG）
    • 提供响应式图片

  3. 延迟加载：

    • 对非关键资源使用延迟加载
    • 使用loading="lazy"属性加载图片

集成评论系统

由于GitHub Pages只支持静态内容，需要使用第三方服务添加评论功能：

  1. Disqus：

    <div id="disqus_thread"></div>
<script>
var disqus_config = function () {
  this.page.url = PAGE_URL;
  this.page.identifier = PAGE_IDENTIFIER;
};
(function() {
  var d = document, s = d.createElement('script');
  s.src = 'https://EXAMPLE.disqus.com/embed.js';
  s.setAttribute('data-timestamp', +new Date());
  (d.head || d.body).appendChild(s);
})();
</script>

  2. Utterances（基于GitHub Issues）：

    <script src="https://utteranc.es/client.js"
        repo="username/repo-name"
        issue-term="pathname"
        theme="github-light"
        crossorigin="anonymous"
        async>
</script>

  3. Giscus（基于GitHub Discussions）：

    <script src="https://giscus.app/client.js"
        data-repo="username/repo-name"
        data-repo-id="R_kgDOHwwwww"
        data-category="Announcements"
        data-category-id="DIC_kwDOHwwwww4CAUTx"
        data-mapping="pathname"
        data-reactions-enabled="1"
        data-emit-metadata="0"
        data-theme="light"
        crossorigin="anonymous"
        async>
</script>

使用GitHub Actions进行高级部署

对于需要构建步骤的复杂站点，可以使用GitHub Actions：

name: Deploy to GitHub Pages

on:
  push:
    branches: [ main ]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '16'
          
      - name: Install and Build
        run: |
          npm ci
          npm run build
          
      - name: Deploy
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          branch: gh-pages
          folder: build
          clean: true
最近更新：
贡献者: zhengwj
Made by bug君 with ❤️
Copyright © 2025 bug君