GitHub Pages 免费搭建个人博客与项目文档指南

GitHub Pages 是 GitHub 为开发者和开源组织提供的免费静态网站托管服务。无需购买云服务器、无需维护 Web 容器，只要将前端静态代码推送到指定的 GitHub 仓库或分支，几秒钟内即可在全球范围内公开访问。

无论是搭建开发者个人技术博客（如基于 Astro、Hexo、VitePress、Hugo）、开源项目在线 Demo，还是托管一份产品文档，GitHub Pages 都是极佳的高性价比之选。

本教程将详细介绍 GitHub Pages 的基本机制、常见建站方案、自定义域名绑定及 HTTPS 证书全流程配置。

---

一、GitHub Pages 的两类站点类型与命名规范

在开始前，需要明确 GitHub Pages 的两大站点类型：

站点类型	仓库命名规范	访问网址 (URL)	数量限制
用户/组织主站点 (User/Org Site)	<username>.github.io	https://<username>.github.io	每个账号仅限 1 个
项目文档/演示站点 (Project Site)	任意名称（例如 my-project）	https://<username>.github.io/my-project	无限制（每个仓库都可以开启）

提示：如果是第一次搭建个人专属主页或技术博客，强烈建议将仓库名称直接命名为 <你的GitHub用户名>.github.io。

---

二、方案 1：纯静态 HTML 极速上手（5 分钟建站）

如果你只有现成的 HTML/CSS/JS 文件，可以直接通过仓库分支托管：

1. 新建仓库，命名为 <username>.github.io，设为 Public（公开）。
2. 在仓库根目录下创建 index.html 文件：

   <!DOCTYPE html>
   <html lang="zh-CN">
   <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <title>我的个人主页</title>
     <style>
       body { font-family: -apple-system, sans-serif; text-align: center; padding: 50px; }
       h1 { color: #10b981; }
     </style>
   </head>
   <body>
     <h1>欢迎来到我的 GitHub 空间！</h1>
     <p>基于 GitHub Pages 搭建的极简个人站点。</p>
   </body>
   </html>
   

3. 提交代码至 main 分支。
4. 打开仓库页面顶部 Settings -> 左侧导航点击 Pages：
   • Source：选择 Deploy from a branch。
   • Branch：选择 main 分支，目录选择 / (root)。
   • 点击 Save。
5. 等待 1~2 分钟，页面顶部即会显示你的在线网址：https://<username>.github.io。

---

三、方案 2：配合 GitHub Actions 自动化编译部署现代静态站点

对于现代静态站点生成器（如 Astro, VitePress, Hexo, VuePress 等），本地不需要手动执行 build 并提交编译产物，可借助 GitHub Actions 实现“每次 push 自动编译并发布”。

以现代静态博客/文档站为例，创建自动化部署工作流 .github/workflows/deploy.yml：

name: Deploy GitHub Pages

on:
  push:
    branches: [ main ] # 当推送更新到 main 分支时触发构建
  workflow_dispatch:

# 赋予 GitHub Pages 部署所需的权限
permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

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

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Build site
        run: npm run build # 编译产物通常生成在 dist 目录下

      # 将静态产物上传给 Pages 部署组件
      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./dist # 若为 Hexo 通常是 public，若为 VitePress 通常是 .vitepress/dist

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

在仓库 Settings -> Pages 的 Build and deployment 下将 Source 切换为 GitHub Actions 即可。后续只需修改 Markdown 文章并 git push，整个站点就会全自动更新上线！

---

四、绑定自定义独立域名与开启免费 HTTPS

如果你拥有自己的独立域名（例如 blog.example.com 或 example.com），可以无缝绑定到 GitHub Pages：

1. 添加 CNAME 解析记录

登录你的域名解析控制台（如 Cloudflare、阿里云、腾讯云）：

• 若绑定二级域名（如 blog.example.com）：
  • 记录类型：CNAME
  • 主机记录：blog
  • 记录值：<username>.github.io
• 若绑定根域名（如 example.com）：
  • 记录类型：A 记录
  • 记录值：依次添加 GitHub Pages 的官方 Anycast IP：
    • 185.199.108.153
    • 185.199.109.153
    • 185.199.110.153
    • 185.199.111.153

2. 在 GitHub 仓库中填写自定义域名

1. 访问仓库 Settings -> Pages。
2. 找到 Custom domain 输入框，填入你的域名（例如 blog.example.com），点击 Save。
3. 此时仓库根目录会自动生成或更新一个名为 CNAME 的单行文本文件。
4. 等待 DNS 校验通过后，勾选 Enforce HTTPS（GitHub 会自动向 Let’s Encrypt 免费申请 SSL 证书，全自动续签）。

---

五、GitHub Pages 配额与使用规范

GitHub Pages 服务完全免费，但也有合理的防滥用限制：

• 仓库大小建议：推荐保持在 1GB 以内。
• 单月流量限制：官方建议软上限为每月 100GB。
• 单构建超时限制：每次构建任务最长不能超过 10 分钟。
• 禁止场景：不得用于非法内容、钓鱼欺诈或高频商业交易支付接口。
• 国内网络访问建议：若国内访客访问 GitHub Pages 节点（fastly cdn）偶尔存在波动，可将域名接入 Cloudflare CDN 或在站点内引用国内公共 CDN / GH-Proxy 提供的资源镜像，以获得更快的首屏加载体验。