GitHub Pages
GitHub Pages 是 GitHub 提供的免费静态网站托管服务，适合搭建个人博客、项目文档、作品集等。
概述
GitHub Pages 的核心特点：
- 免费托管：公开仓库免费使用
- 自定义域名：支持绑定自己的域名
- HTTPS 支持：自动提供 SSL 证书
- Jekyll 支持：内置 Jekyll 静态网站生成器
- Actions 集成：支持自动化部署
使用限制
| 项目 | 限制 |
|---|---|
| 源仓库大小 | 建议 1GB 以内 |
| 构建时间 | 10 分钟 |
| 月流量 | 100GB（软限制） |
| 文件数量 | 建议不超过 100,000 个 |
| 用户/组织站点 | 每个账户仅限一个 |
禁止用途
GitHub Pages 不适合用于：
- 商业用途的电商网站
- 高流量的生产应用
- 敏感数据的存储和传输
- 任何违反 GitHub 服务条款的内容
站点类型
用户/组织站点
仓库名必须是 <username>.github.io，访问地址为 https://username.github.io。
每个账户只能有一个用户或组织站点。
项目站点
任意仓库都可以启用 Pages，访问地址为 https://username.github.io/repo-name。
一个账户可以有多个项目站点。
快速开始
创建用户站点
- 创建名为
<username>.github.io的仓库 - 添加
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>
</head>
<body>
<h1>Hello, GitHub Pages!</h1>
<p>欢迎访问我的个人网站。</p>
</body>
</html>
- 在仓库 Settings > Pages 中选择部署分支
- 等待几分钟后访问
https://username.github.io
创建项目站点
- 进入仓库 Settings > Pages
- 选择 Source：
- Deploy from a branch：从分支部署
- GitHub Actions：使用 Actions 部署
- 选择分支和目录（根目录或
/docs） - 保存后等待部署完成
部署方式
从分支部署
直接从仓库分支部署静态文件：
Settings > Pages > Source > Deploy from a branch
选择分支和目录后，GitHub 会自动构建和部署。每次推送到该分支都会触发新的部署。
使用 GitHub Actions 部署
推荐使用 Actions 部署，支持更多构建工具：
name: Deploy to GitHub Pages
on:
push:
branches: [main]
permissions:
contents: read
pages: write
id-token: write
concurrency:
group: "pages"
cancel-in-progress: true
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: 设置 Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- name: 安装依赖
run: npm ci
- name: 构建
run: npm run build
- name: 配置 Pages
uses: actions/configure-pages@v4
- name: 上传产物
uses: actions/upload-pages-artifact@v3
with:
path: ./dist
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
needs: build
steps:
- name: 部署到 GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
静态网站生成器
React 应用
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- run: npm ci
- run: npm run build
- uses: actions/upload-pages-artifact@v3
with:
path: ./build
需要在 package.json 中设置 homepage：
{
"homepage": "https://username.github.io/repo-name"
}
Vue 应用
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- run: npm ci
- run: npm run build
- uses: actions/upload-pages-artifact@v3
with:
path: ./dist
配置 vite.config.js：
export default defineConfig({
base: '/repo-name/',
})
Next.js 静态导出
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- run: npm ci
- run: npm run build
- uses: actions/upload-pages-artifact@v3
with:
path: ./out
配置 next.config.js：
const nextConfig = {
output: 'export',
basePath: '/repo-name',
}
Docusaurus
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- run: npm ci
- run: npm run build
- uses: actions/upload-pages-artifact@v3
with:
path: ./build
配置 docusaurus.config.js：
module.exports = {
url: 'https://username.github.io',
baseUrl: '/repo-name/',
}
Jekyll
Jekyll 是 GitHub Pages 内置支持的生成器，直接推送 .md 文件即可。
创建 _config.yml：
title: 我的博客
description: 个人技术博客
theme: minima
创建文章 _posts/2024-01-01-hello-world.md：
---
layout: post
title: "Hello World"
date: 2024-01-01
---
这是我的第一篇博客文章。
GitHub Pages 会自动将 Markdown 转换为 HTML。
自定义域名
配置自定义域名
- 在仓库 Settings > Pages > Custom domain 中填写域名
- 在域名服务商处配置 DNS：
Apex 域名（如 example.com）：
A 记录：
185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153
子域名（如 www.example.com）：
CNAME 记录：username.github.io
配置文件
在仓库根目录创建 CNAME 文件：
www.example.com
HTTPS
GitHub Pages 自动为自定义域名提供 HTTPS 证书。配置自定义域名后，勾选 "Enforce HTTPS"。
DNS 配置生效后，证书可能需要几分钟到几小时才能颁发。
部署最佳实践
使用 gh-pages 分支
将构建产物推送到 gh-pages 分支：
name: Deploy
on:
push:
branches: [main]
jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- run: npm ci
- run: npm run build
- name: 部署到 gh-pages
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./dist
预览部署
为 Pull Request 创建预览部署：
name: Preview
on:
pull_request:
types: [opened, synchronize, reopened]
permissions:
contents: read
pages: write
id-token: write
pull-requests: write
jobs:
preview:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- run: npm ci
- run: npm run build
- name: 部署预览
uses: rossjrw/pr-preview-action@v1
with:
source-dir: dist
自定义 404 页面
创建 404.html 文件自定义 404 页面：
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<title>页面未找到</title>
</head>
<body>
<h1>404 - 页面未找到</h1>
<p>抱歉，您访问的页面不存在。</p>
<a href="/">返回首页</a>
</body>
</html>
常见问题
404 错误
检查以下项目：
- 文件名是否为
index.html - 分支和目录配置是否正确
- 是否等待了足够时间（通常几分钟）
- 构建是否成功（查看 Actions 日志）
样式加载失败
检查 base 或 homepage 配置是否正确：
// Vite
base: '/repo-name/'
// React (package.json)
"homepage": "https://username.github.io/repo-name"
// Next.js
basePath: '/repo-name'
刷新页面 404
SPA 应用需要配置重定向。创建 404.html 重定向到 index.html，或使用 HashRouter。
构建失败
查看 Actions 日志，常见原因：
- 依赖安装失败
- 构建命令错误
- 输出目录不正确
- 构建时间超过 10 分钟
自定义域名证书问题
- 确保 DNS 配置正确
- 等待 DNS 传播（可能需要几小时）
- 检查 CNAME 文件是否正确
Jekyll 高级配置
主题配置
在 _config.yml 中设置主题：
theme: minima
# 或使用远程主题
remote_theme: pages-themes/[email protected]
插件
GitHub Pages 支持的插件：
plugins:
- jekyll-seo-tag
- jekyll-sitemap
- jekyll-feed
排除文件
exclude:
- README.md
- .github/
- node_modules/
默认值
defaults:
- scope:
path: ""
type: "posts"
values:
layout: "post"
author: "Your Name"
安全考虑
敏感信息
不要在 GitHub Pages 网站上存储或展示：
- API 密钥
- 密码
- 个人身份信息
- 任何敏感数据
所有源代码都是公开的（对于公开仓库）。
noindex 配置
如果不想被搜索引擎索引，在 _config.yml 中添加：
defaults:
- scope:
path: ""
values:
robots: "noindex"
或在 HTML 中添加：
<meta name="robots" content="noindex">