第 08 章

GitHub Pages

免费托管静态网站——把你的项目变成一个在线主页

一个仓库，一个网址，你的作品集就在线了

作品没地方放

你做了好几个项目，却没有一个能展示的地方

简历没东西写

投实习、申学校，简历上「项目经历」只能写几行字。面试官看不到你实际做的东西长什么样。

不想买服务器

想做个个人主页展示作品，但租服务器、配域名、搞 HTTPS 太麻烦还花钱。学生党只想白嫖。

文档没地方放

给项目写了文档，只在本地能看。想分享给别人，得打包发文件。

本章解决展示问题：用 GitHub Pages 把静态网站免费托管到 用户名.github.io。
重点是动手做一个作品集个人主页——这是学生最实用的产出，也是你学 Actions 自动部署的最佳练手。

开始之前

适合谁

想要一个在线作品集主页
会基本 HTML/CSS，想把它发到网上
学了 Actions（第 07 章）想实际用起来

你将学会

用分支方式部署 Pages
用 Actions 方式部署 Pages（更灵活）
配置自定义域名
用 Jekyll 主题或静态站生成器
构建一个作品集主页实战

本章暂不覆盖

Jekyll 深度定制（进阶）
动态后端（Pages 只支持静态）
企业版高级功能

Pages 是什么

GitHub 的静态网站托管服务——把仓库变成网站

核心特性

免费：每个账号无限站点
自带 HTTPS：不用自己配证书
自动部署：push 即上线
支持自定义域名

网址格式

用户名.github.io：专属主页仓库
用户名.github.io/仓库名：项目子站
自定义域名：绑定后替换上面地址

静态网站意味着只能托管 HTML/CSS/JS/图片，没有后端逻辑。但配合客户端 JS 和第三方 API，能做出的东西远比你想象的多——博客、文档、作品集、甚至 SPA。

两种部署方式

从分支部署 vs 用 Actions 部署

	分支部署	Actions 部署
原理	指定某分支作为网站源	用 workflow 构建并上传产物
适合	纯 HTML、无需构建	需要 build 的项目（React、Vue 等）
配置难度	点几下就行	要写 workflow
灵活性	低	高，可加任意构建步骤

先从简单的分支部署入手，再进阶到 Actions 部署。

专属主页仓库

建一个特殊命名的仓库，获得用户名.github.io 网址

步骤

新建仓库，名字必须是 你的用户名.github.io
clone 到本地
在根目录放一个 index.html
commit 并 push 到 main
等 1 分钟，访问 https://你的用户名.github.io

最简 HTML

<!DOCTYPE html>
<html>
<body>
  <h1>Hello, 我是你的名字</h1>
  <p>这是我的个人主页</p>
</body>
</html>

用户名仓库的特殊性：它的 main 分支自动部署到 用户名.github.io，不用额外配置。这是最快上手 Pages 的方式。

项目子站

任何仓库都能开 Pages，网址是用户名.github.io/仓库名

怎么开

仓库 → Settings → Pages → Source 选 Deploy from a branch → 选分支（如 main）和目录（/root 或 /docs）→ Save。

用途

项目官网 / 落地页
API 文档站
demo 演示页
开源项目的介绍页

注意路径：项目子站的资源路径要用相对路径（./style.css）或带仓库名前缀（/仓库名/style.css）。绝对路径 /style.css 在用户名主页能用，在项目子站会 404。

部署目录

branch 部署时，选 /root 还是 /docs

/ (root)

整个仓库根目录作为网站。适合：纯网站仓库，没有源码混杂。

用户名仓库 xxx.github.io 通常用这个。

/docs

只有 docs 子目录作为网站。适合：项目仓库，源码和文档共存。

把网站文件放 docs/ 文件夹，源码留在外面。

在 Settings → Pages 的 Branch 选项里切换。

Jekyll 主题

Pages 内置 Jekyll——不用写 HTML 也能生成漂亮网站

最简用法

在仓库根目录建 _config.yml：

theme: jekyll-theme-minimal
title: 我的主页

再放几个 .md 文件，Jekyll 自动转成网页。

选主题

官方主题库：pages.github.com/themes。
常见：minimal、cayman、architect、slate。换主题只改 theme: 一行。

Jekyll 适合博客和文档。写 Markdown，自动生成带导航、归档、标签的网站。但定制有学习成本，纯作品集建议直接写 HTML 更可控。

Actions 部署

现代项目用 workflow 构建 + 部署——支持任何静态站生成器

切换部署源

Settings → Pages → Source 选 GitHub Actions

为什么要切

默认是「Deploy from a branch」。要用 Actions 部署，必须先切到「GitHub Actions」源，否则 workflow 上传了产物也不会上线。

切换后

Pages 会等待一个特定 workflow来推送内容。
你需要写一个用 actions/deploy-pages 的 workflow，它有官方提供的模板。

切换后页面会显示提示，并提供「GitHub-provided workflow」按钮，一键生成基础部署 workflow。新手可以直接用这个模板起步。

静态站生成器

用框架写源码，构建出静态站——比手写 HTML 高效

工具	语言	适合
Jekyll	Ruby/MD	博客、文档（内置）
Hugo	Go/MD	极快的博客
VitePress	Vue/MD	技术文档
Astro / Next.js export	JS/TS	现代作品集、SPA

都需要 build 步骤——正好用 Actions 部署。

实战：Vite 部署

把 Vite 项目自动部署到 Pages 的完整 workflow

name: Deploy Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with: { node-version: '20', cache: 'npm' }
      - run: npm install
      - run: npm run build
      - uses: actions/configure-pages@v5
      - uses: actions/upload-pages-artifact@v3
        with: { path: './dist' }

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
    steps:
      - uses: actions/deploy-pages@v5

Vite 配置注意

项目子站要设 base 路径，否则资源 404

用户名主页仓库

部署到根域名 用户名.github.io，不用改 base：

// vite.config.js
export default {
  // 默认 base: '/'
}

项目子站

部署到 用户名.github.io/仓库名，要设 base：

// vite.config.js
export default {
  base: '/仓库名/'
}

否则 JS/CSS 路径错，页面白屏。

白屏排查第一步：F12 看 Network 标签，是不是一堆 404。多半是 base 路径没配。

自定义域名

用自己的域名替代用户名.github.io

在 GitHub 配置

仓库 → Settings → Pages → Custom domain 输入你的域名 → Save → 勾选 Enforce HTTPS。

在域名商配 DNS

子域名（如 www）：加 CNAME 记录指向 用户名.github.io

顶级域名：加 A 记录指向 GitHub Pages IP（官方文档查最新 IP）

建议用 www 子域名 + CNAME，配置最简单稳定。顶级域名 A 记录的 IP 会随 GitHub 更新，偶尔要跟着改。

CNAME 文件

把域名配置持久化——避免每次部署后丢

# 在网站根目录建一个 CNAME 文件（无扩展名）
# 内容只有一行：你的域名

www.example.com

为什么需要

Settings 里配的域名，只对当前部署有效。下次 push 部署后可能被覆盖。把域名写进 CNAME 文件，随仓库走，永久生效。

放在哪

分支部署：网站根目录
Actions 部署：构建产物目录（如 dist/CNAME 或 public/）

作品集实战

从零做一个能展示项目的个人主页

页面结构

Hero 区：名字、一句话介绍、头像
项目展示：卡片网格，每个项目含截图、简介、链接
技能区：你会的技术栈
联系方式：邮箱、GitHub、社交链接

技术选择

最简：纯 HTML + CSS，手动维护
推荐：用 Astro 或 Vite，组件化、好维护
最省事：套 Jekyll 主题，写 Markdown

主页骨架

纯 HTML 的最简作品集结构

<body>
  <header>
    <img src="avatar.jpg" alt="头像">
    <h1>你的名字</h1>
    <p>大三学生 · 全栈方向 · 热爱开源</p>
  </header>

  <main>
    <section id="projects">
      <h2>项目作品</h2>
      <div class="grid">
        <article>
          <img src="project1.png">
          <h3>项目名</h3>
          <p>一句话描述</p>
          <a href="仓库链接">源码</a>
        </article>
        <!-- 更多项目 -->
      </div>
    </section>
  </main>
</body>

作品集要点

让主页真正为你加分

项目要有「链接 + 截图 + 说明」

光写名字没用。每个项目配：在线 demo 链接（也是 Pages！）、截图、一段话说清做了什么、用了什么技术。

响应式

手机打开不能乱。用 CSS media query 或框架的栅格系统。面试官可能在手机上看。

放 GitHub 链接

引导访客去看你的代码。绿油油的贡献图本身就是加分项。

保持更新

做完新项目就加上去。一个 6 个月没动的主页，比没有更糟。

HTTPS 自动配

Pages 自带免费 HTTPS 证书，不用自己申请

默认域名

用户名.github.io 直接是 HTTPS，无需任何配置。证书自动续期。

自定义域名

DNS 生效后，在 Pages 设置里勾 Enforce HTTPS。GitHub 会自动签发 Let's Encrypt 证书，几分钟生效。

强制约束：勾选 Enforce HTTPS 后，所有 HTTP 访问会自动跳转 HTTPS。这是现代网站的标配，浏览器不会标「不安全」。

排错：页面 404

网址打开了却是 404 或空白

排查清单

index.html 是否在部署目录根
仓库名是否正确（用户名仓库必须严格匹配）
首次部署等了 1-2 分钟吗
Actions 部署的话，workflow 跑成功了吗
路径大小写对吗（Linux 区分）

查看部署状态

仓库 → Settings → Pages 顶部显示构建状态。绿色勾表示部署成功，红叉点进去看日志。

Actions 标签里也能看到 deploy workflow 的运行记录。

排错：样式丢失

页面出来了但没样式 / 资源 404

项目子站最常见

根路径引用 /style.css，但实际在 /仓库名/style.css。

修复：改成相对路径 ./style.css，或框架设 base 路径。

构建产物路径错

Actions workflow 里 upload-pages-artifact 的 path 要指向真实构建输出（如 ./dist、./build、./public）。

F12 → Network 标签是排查这类问题的神器。红色项就是加载失败的资源，看它的 URL 路径就知道错在哪。

动手试一试

上线你的第一个个人主页

你的任务

任务：建一个 用户名.github.io 仓库，放上一个作品集主页。

要求：

新建名为 你的用户名.github.io 的仓库
写一个 index.html，含名字、介绍、至少一个项目卡片
push 到 main，1 分钟后访问网址确认上线
进阶：改用 Actions 部署（参考第 13 张幻灯片的 workflow）
进阶：配自定义域名（有的话）

提示

先把纯 HTML 版本跑通，再考虑用框架
用户名仓库的网址就是 https://用户名.github.io

第 08 章

小结

你已经能把项目免费发布到互联网上了

本章要点

两种部署：分支部署（简单）/ Actions 部署（灵活）
用户名仓库 xxx.github.io 自动部署到专属域名
项目仓库 Pages 网址为 用户名.github.io/仓库名
需要 build 的项目用 Actions workflow 部署
自定义域名配 CNAME 文件持久化
作品集主页 = 学生最实用的 Pages 产出

下一步：第 09 章 GitHub CLI —— 用命令行操作仓库、PR、release，把网页操作自动化。

GitHub Pages

作品没地方放

你做了好几个项目，却没有一个能展示的地方

简历没东西写

不想买服务器

文档没地方放

开始之前

适合谁

你将学会

本章暂不覆盖

Pages 是什么

GitHub 的静态网站托管服务——把仓库变成网站

核心特性

网址格式

两种部署方式

从分支部署 vs 用 Actions 部署

专属主页仓库

建一个特殊命名的仓库，获得 用户名.github.io 网址

步骤

最简 HTML

项目子站

任何仓库都能开 Pages，网址是 用户名.github.io/仓库名

怎么开

用途

部署目录

branch 部署时，选 /root 还是 /docs

/ (root)

/docs

Jekyll 主题

Pages 内置 Jekyll——不用写 HTML 也能生成漂亮网站

最简用法

选主题

Actions 部署

现代项目用 workflow 构建 + 部署——支持任何静态站生成器

图：Actions 部署 Pages 的流程

切换部署源

Settings → Pages → Source 选 GitHub Actions

为什么要切

切换后

静态站生成器

用框架写源码，构建出静态站——比手写 HTML 高效

实战：Vite 部署

把 Vite 项目自动部署到 Pages 的完整 workflow

Vite 配置注意

项目子站要设 base 路径，否则资源 404

用户名主页仓库

项目子站

自定义域名

用自己的域名替代 用户名.github.io

在 GitHub 配置

在域名商配 DNS

CNAME 文件

把域名配置持久化——避免每次部署后丢

为什么需要

放在哪

作品集实战

从零做一个能展示项目的个人主页

页面结构

技术选择

主页骨架

纯 HTML 的最简作品集结构

作品集要点

让主页真正为你加分

项目要有「链接 + 截图 + 说明」

响应式

放 GitHub 链接

保持更新

HTTPS 自动配

Pages 自带免费 HTTPS 证书，不用自己申请

默认域名

自定义域名

排错：页面 404

网址打开了却是 404 或空白

排查清单

查看部署状态

排错：样式丢失

页面出来了但没样式 / 资源 404

项目子站最常见

构建产物路径错

动手试一试

建一个特殊命名的仓库，获得用户名.github.io 网址

任何仓库都能开 Pages，网址是用户名.github.io/仓库名

用自己的域名替代用户名.github.io