software

使用 GitHub Actions 设置 GitHub Pages

发布: (2026年1月1日 GMT+8 06:11)
12 分钟阅读
原文: Dev.to

Source: Dev.to

高级步骤

  1. 创建 GitHub 仓库 – 在 GitHub 上创建一个新仓库。
  2. 创建 Hello World 内容 – 添加基本的 HTML 内容以供服务。
  3. 启用 GitHub Pages – 在仓库设置中配置 Pages。
  4. 设置 GitHub Actions – 使用工作流自动化部署。
  5. 验证部署 – 确认您的站点已上线。

先决条件

  • GitHub 账户
  • 本地已安装 Git
  • HTML 基础知识
  • 文本编辑器或 IDE

用例：简单的 Hello World 网站

我们将创建一个基本的静态网站，显示“Hello World”，并且可以通过添加额外内容进行扩展。这种方法适用于任何静态 HTML 网站、文档或简单的 Web 应用程序。

步骤式实现

第 1 步：创建 GitHub 仓库

  1. 前往 GitHub，点击右上角的 “+” 图标。
  2. 选择 “New repository.”

配置仓库：

设置值
Repository namegithub-pages-demo（或你喜欢的名称）
Description“A simple hello world site on GitHub Pages”（在 GitHub Pages 上的简易 Hello World 站点）
VisibilityPublic（公开，免费 GitHub Pages 所必需）
Initialize with README✅（勾选）

点击 “Create repository.”

关键点

  • 仓库名称会成为站点 URL 的一部分：https://<username>.github.io/
  • 公开仓库可免费使用 GitHub Pages 托管。
  • 私有仓库需要 GitHub Pro（或更高）才能使用 Pages。

第 2 步：在本地克隆仓库

git clone https://github.com/your-username/github-pages-demo.git
cd github-pages-demo

将 your-username 替换为你的实际 GitHub 用户名。

第 3 步：创建 Hello World 内容

在仓库根目录创建一个基本的 index.html 文件：

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Hello World - GitHub Pages</title>
  <style>
    body {
      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
      display: flex;
      justify-content: center;
      align-items: center;
      min-height: 100vh;
      margin: 0;
      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
      color: white;
    }
    .container {
      text-align: center;
      padding: 2rem;
    }
    h1 {
      font-size: 3rem;
      margin-bottom: 1rem;
    }
    p {
      font-size: 1.2rem;
      opacity: 0.9;
    }
  </style>
</head>
<body>
  <div class="container">
    <h1>Hello World!</h1>
    <p>Welcome to my GitHub Pages site</p>
  </div>
</body>
</html>

此文件的作用

  • 创建一个带有 “Hello World” 信息的简易 HTML 页面。
  • 使用基础样式实现干净的外观。
  • 响应式设计，可在移动设备上正常显示。

可选方案： 添加任何你需要的静态 HTML、CSS、JavaScript 或其他资源。

第 4 步：创建 GitHub Actions 工作流

  1. 创建工作流目录：

    mkdir -p .github/workflows

  2. 添加工作流文件 .github/workflows/pages.yml：

name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main
  workflow_dispatch:

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

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

jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Pages
        uses: actions/configure-pages@v4

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: '.'

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

工作流说明

  • 触发条件 – 当向 main 分支推送或手动触发时运行。
  • 权限 – 部署 Pages 所需的权限。
  • 并发控制 – 防止多个部署相互冲突。
  • 步骤
    1. 检出仓库代码。
    2. 配置 Pages 设置。
    3. 将整个仓库文件作为制品上传。
    4. 将制品部署到 GitHub Pages。

关键点

  • 当你推送到 main 时，工作流会自动部署。
  • 使用官方的 GitHub Actions for Pages（actions/deploy-pages@v4）。
  • 对于纯 HTML 页面无需构建步骤（如果使用框架，请自行添加构建步骤）。
  • path: '.' 会上传整个仓库根目录。

第 5 步：启用 GitHub Pages

重要提示： 在推送代码之前，请先启用 GitHub Pages。

Source: …

步骤 5.1：导航至设置

  1. 前往 GitHub 上的仓库。
  2. 在顶部导航栏中点击 “Settings（设置）”。
  3. 在左侧边栏中选择 “Pages（页面）”。

步骤 5.2：配置来源

在 “Build and deployment（构建和部署）” 下找到 “Source（来源）”。

  • 选择 “GitHub Actions”。
  • 选择后会自动保存。

这一步的作用

  • 为仓库启用 GitHub Pages。
  • 将 Pages 配置为使用 GitHub Actions 工作流进行部署。
  • 创建工作流所需的 github-pages 环境。

验证部署

  1. 将更改（包括 index.html 和工作流文件）提交并推送到 main 分支：

    git add .
git commit -m "Add site content and Pages workflow"
git push origin main

  2. 前往 Actions 选项卡查看工作流运行情况。

  3. 工作流完成后，进入 Settings → Pages 找到线上站点的 URL（例如 https://<username>.github.io/github-pages-demo）。

  4. 在浏览器中打开该 URL —— 你应该能看到 “Hello World!” 页面。

回顾

  • 创建了一个公共仓库。
  • 添加了一个简单的静态站点（index.html）。
  • 设置了 GitHub Actions 工作流，以自动部署站点。
  • 启用了 GitHub Pages，并将 GitHub Actions 设为源。
  • 验证站点已上线。

现在，您拥有了一个完全自动化的 GitHub Pages 站点，它会在每次推送到 main 时更新。欢迎通过添加更多页面、资源或使用静态站点生成器来扩展站点——只需相应地调整工作流即可。

第6步：提交并推送

git add index.html .github/workflows/pages.yml
git commit -m "feat: add hello world page and GitHub Pages workflow"
git push origin main

注意： 我们在本教程中直接推送到 main 分支。 在生产环境中，最佳实践是：

  1. 创建一个分支（例如 git checkout -b feature/add-pages-setup）
  2. 创建拉取请求进行审查
  3. 审批后合并

关键点

  • main（或 master）分支通常用于 GitHub Pages。
  • 仓库根目录或特定分支/文件夹中的所有文件都可以被提供服务。
  • GitHub Pages 只提供 静态 文件（HTML、CSS、JavaScript、图片等）。
  • 工作流将在推送时自动触发。

第 7 步：等待部署并访问站点

7.1 等待部署

  • GitHub Actions 检测到工作流文件并自动运行。
  • GitHub 构建并部署你的站点（可能需要几分钟）。
  • 绿色对勾表示部署已完成。
  • 在 Actions 选项卡中监控进度。

7.2 访问站点

你的站点将可通过以下地址访问：

https://your-username.github.io/github-pages-demo

将 your-username 和 github-pages-demo 替换为你的实际值。

7.3 在仓库 About 部分添加网站（可选）

  1. 在仓库页面，点击 About 部分旁的 齿轮图标 (⚙️)。
  2. 在 编辑仓库详情 弹窗中，找到 Website 字段。
  3. 输入你的 GitHub Pages URL（例如 https://your-username.github.io/github-pages-demo）。
  4. 勾选 “使用你的 GitHub Pages 网站” —— 这会自动填充 URL。
  5. 点击 保存更改。

此操作的作用

  • 在仓库的 About 部分显示站点 URL。
  • 为访问者提供直接链接。
  • 提高你的 GitHub Pages 站点的可发现性。

注意： 以后对 main 分支的推送将自动触发工作流并部署更新。

完整示例

仓库结构

github-pages-demo/
├── .github/
│   └── workflows/
│       └── pages.yml
├── index.html
└── README.md
  • index.html – 如步骤 3 所示。
  • pages.yml – 如步骤 4 所示。

仓库结构概览

文件 / 文件夹用途
.github/workflows/pages.ymlGitHub Actions 部署工作流
index.html主页面内容
README.md仓库文档

重要说明

GitHub Pages 限制

  • 仅限静态内容 – 不支持服务器端处理（PHP、Python 等）。
  • 文件大小限制 – 1 GB 仓库大小，单文件 100 MB。
  • 带宽 – 免费账户每月 100 GB。
  • 构建时间 – 每小时 10 次构建限制。

自定义域名支持

  • 添加一个包含域名的 CNAME 文件。
  • 配置 DNS 记录指向 GitHub。
  • 详见官方 GitHub Pages 文档。

有关使用 AWS Route 53 的操作步骤，请参见 Setting Up Custom Domain for GitHub Pages with Route53。

分支和文件夹选项

源选项描述
从分支部署直接从分支提供文件。
GitHub Actions使用工作流进行构建和部署（推荐）。
文件夹选项描述
/ (根)从仓库根目录提供文件。
/docs从 docs 文件夹提供文件。
自定义在设置中指定的任意文件夹。

安全注意事项

  • 公开仓库 – 内容对所有人可见。
  • 私有仓库 – 需要 GitHub Pro 计划才能使用 Pages。
  • 机密信息 – 切勿提交 API 密钥或其他敏感数据。
  • HTTPS – 所有 Pages 站点自动启用。

故障排除

网站无法加载

症状： 404 错误或网站未加载。

解决步骤

  1. 检查部署状态 – 前往 Repository → Actions 选项卡。
  2. 验证工作流已运行 – 确保其成功完成。
  3. 检查 Pages 设置 – 确认已选择 “GitHub Actions” 作为源。
  4. 等待几分钟 – 初始部署可能需要 5‑10 分钟。
  5. 清除浏览器缓存 – 尝试隐身模式或使用其他浏览器。

有用的命令

# Verify workflow file exists
ls -la .github/workflows/pages.yml

# View its contents
cat .github/workflows/pages.yml

工作流失败

症状： GitHub Actions 工作流错误。

解决检查清单

  • 查看 Actions 选项卡日志中的错误信息。
  • 确保已启用 Pages 权限 (pages: write, id-token: write)。
  • 验证制品路径与内容位置匹配（根目录使用 '.'，或指定正确的文件夹）。
  • 确认工作流在正确的分支上触发。
  • 验证 YAML 语法（如有需要，可使用在线 linter）。

常见错误

  • 缺少权限：添加 pages: write 和 id-token: write。
  • 制品路径错误：调整为 '.' 或相应的文件夹。
  • 分支名称不匹配：确保 on: 触发器与您的分支相符。

自定义域名问题

症状： 自定义域名无法使用。

解决步骤

  1. 检查 CNAME 文件 – 文件中只能包含域名（无多余空格）。
  2. 验证 DNS 记录 – A/CNAME 记录应指向 GitHub 的服务器。
  3. 等待传播 – DNS 更改可能需要最长 48 小时。
  4. 确认 GitHub 设置 – 必须在 Pages 设置中添加该域名。

验证

  • 访问站点 URL。
  • 确保 “Hello World!” 内容正确显示。
  • 检查 Actions 选项卡，确认运行成功。
Back to Blog

相关文章

阅读更多 »

RGB LED 支线任务 💡

markdown !Jennifer Davishttps://media2.dev.to/dynamic/image/width=50,height=50,fit=cover,gravity=auto,format=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%...

Mendex：我为何构建

介绍 大家好。今天我想分享一下我是谁、我在构建什么以及为什么。 早期职业生涯与倦怠 我在 17 年前开始我的 developer 生涯……