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 文件，可以直接通过仓库分支托管：

新建仓库，命名为 <username>.github.io，设为 Public（公开）。

在仓库根目录下创建 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>

提交代码至 main 分支。
打开仓库页面顶部 Settings -> 左侧导航点击 Pages：
- Source：选择 Deploy from a branch。
- Branch：选择 main 分支，目录选择 / (root)。
- 点击 Save。
等待 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 仓库中填写自定义域名

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

五、GitHub Pages 配额与使用规范

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

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