GitHub Actions GitHub Pages部署 #

GitHub Pages是GitHub提供的静态站点托管服务。本节介绍如何使用GitHub Actions自动部署到GitHub Pages。

GitHub Pages概述 #

什么是GitHub Pages？ #

GitHub Pages是免费的静态站点托管服务：

  • 支持自定义域名
  • 自动HTTPS
  • 与GitHub仓库集成
  • 免费使用

部署方式 #

方式 描述
Source 从分支部署
GitHub Actions 使用工作流部署

配置GitHub Pages #

启用GitHub Pages #

  1. 进入仓库设置
  2. 点击 “Pages”
  3. Source选择 “GitHub Actions”

权限配置 #

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

基本部署 #

使用官方Action #

yaml 
name: Deploy to GitHub Pages

on:
  push:
    branches: [main]

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      
      - run: npm ci
      - run: npm run build
      
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: dist

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

使用第三方Action #

yaml 
name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      
      - run: npm ci
      - run: npm run build
      
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

静态站点生成器 #

Next.js #

yaml 
name: Deploy Next.js

on:
  push:
    branches: [main]

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

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
      
      - name: Export
        run: npm run export
      
      - uses: actions/upload-pages-artifact@v3
        with:
          path: out

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

Vue.js #

yaml 
name: Deploy Vue.js

on:
  push:
    branches: [main]

jobs:
  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
      
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

React #

yaml 
name: Deploy React

on:
  push:
    branches: [main]

jobs:
  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
      
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build

Hugo #

yaml 
name: Deploy Hugo

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: true
      
      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
      
      - run: hugo --minify
      
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

Jekyll #

yaml 
name: Deploy Jekyll

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.2'
          bundler-cache: true
      
      - run: bundle exec jekyll build
      
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./_site

自定义域名 #

配置CNAME #

yaml 
- uses: peaceiris/actions-gh-pages@v3
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./dist
    cname: example.com

或在仓库设置中配置 #

  1. 进入仓库设置
  2. 点击 “Pages”
  3. Custom domain输入域名

部署配置 #

peaceiris/actions-gh-pages参数 #

yaml 
- uses: peaceiris/actions-gh-pages@v3
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./dist
    publish_branch: gh-pages
    destination_dir: subdir
    external_repository: owner/repo
    allow_empty_commit: false
    enable_jekyll: false
    disable_nojekyll: false
    cname: example.com
    force_orphan: true
    user_name: 'github-actions[bot]'
    user_email: 'github-actions[bot]@users.noreply.github.com'
    commit_message: ${{ github.event.head_commit.message }}

完整示例 #

带预览的部署 #

yaml 
name: Deploy

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

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

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

  deploy-preview:
    needs: build
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    environment:
      name: preview
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/deploy-pages@v4
        id: deployment
        with:
          preview: true

  deploy-production:
    needs: build
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/deploy-pages@v4
        id: deployment

最佳实践 #

1. 使用环境保护 #

yaml 
environment:
  name: github-pages
  url: ${{ steps.deployment.outputs.page_url }}

2. 缓存依赖 #

yaml 
- uses: actions/setup-node@v4
  with:
    cache: 'npm'

3. 使用并发控制 #

yaml 
concurrency:
  group: "pages"
  cancel-in-progress: true

4. 添加部署状态徽章 #

markdown 
![Deploy](https://github.com/owner/repo/actions/workflows/deploy.yml/badge.svg)

下一步学习 #

小结 #

  • GitHub Pages提供免费静态站点托管
  • 使用官方或第三方Action部署
  • 支持多种静态站点生成器
  • 可以配置自定义域名
  • 使用环境保护生产环境
  • 使用并发控制避免冲突
最后更新：2026-03-28