实现推送后自动编译并部署到 gh-pages 分支
要实现推送后自动编译并部署到 gh-pages 分支，你有几种方法可以选择：
方法1：使用 GitHub Actions（推荐）
这是最现代、最灵活的方式：
- 创建 GitHub Actions 工作流文件：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
| name: Deploy to GitHub Pages
on:
push:
branches: ["main"] # 如果你的主分支是 main
pull_request:
branches: ["main"]
permissions:
contents: write
pages: write
id-token: write
jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
# 这里添加你的构建步骤
# 例如，如果是 Jekyll：
# - name: Setup Ruby
# uses: ruby/setup-ruby@v1
# - name: Build with Jekyll
# run: |
# bundle install
# bundle exec jekyll build
# 如果是静态文件，直接复制到输出目录
- name: Build
run: |
# 你的构建命令
# 例如：npm run build 或 hugo
echo "Building site..."
# 构建后的文件放在 dist/ 或 public/ 目录
- name: Deploy
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./dist # 改为你的输出目录
publish_branch: gh-pages
|
- 根据你的博客类型调整：
- Jekyll：GitHub Pages 会自动构建，但如果你想自定义：
1
2
3
4
5
6
| - name: Setup Jekyll
uses: ruby/setup-ruby@v1
- name: Build
run: |
bundle install
bundle exec jekyll build
|
Hugo：
1
2
3
4
| - name: Setup Hugo
uses: peaceiris/actions-hugo@v2
- name: Build
run: hugo --minify
|
Hexo：
1
2
3
4
5
6
| - name: Setup Node.js
uses: actions/setup-node@v3
- name: Install and Build
run: |
npm install
npm run build
|
方法2：使用 CI 工具的构建脚本
如果你已经在使用其他工具，可以在 package.json 中添加脚本：
1
2
3
4
5
6
7
8
| {
"scripts": {
"deploy": "npm run build && gh-pages -d dist"
},
"devDependencies": {
"gh-pages": "^5.0.0"
}
}
|
然后手动运行npm run deploy
方法3：手动设置分支
确保 gh-pages 分支存在
在主分支中添加构建脚本
使用 Git 子模块或 subtree 推送
配置建议
- 检查 Pages 设置：
- 验证部署：
常见问题解决
推荐使用 方法1（GitHub Actions），因为它最灵活且与 GitHub 生态集成最好。你需要根据自己的博客框架调整构建步骤。
基于旧的YAML文件修复
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
| name: auto-hugo # 名字自取
on:
push:
branches:
- main # 这里的意思是当 main分支发生push的时候，运行下面的jobs
jobs:
deploy: # 任务名自取
runs-on: ubuntu-latest # 在什么环境运行任务
steps:
- uses: actions/checkout@v3 # 引用actions/checkout这个action，与所在的github仓库同名
with:
submodules: true # Fetch Hugo themes (true OR recursive) 获取submodule主题
fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod
- name: Setup Hugo # 步骤名自取
uses: peaceiris/actions-hugo@v2 # hugo官方提供的action，用于在任务环境中获取hugo
with:
hugo-version: '0.91.2' #'latest'# 获取最新版本的hugo
extended: true
- name: Build
run: hugo --minify -b https://mkbooks.github.io/blog/ # 使用hugo构建静态网页
# - name: Deploy
# uses: peaceiris/actions-gh-pages@v3 # 一个自动发布github pages的action
# with:
# # github_token: ${{ secrets.GITHUB_TOKEN }} # 该项适用于发布到源码相同repo的情况，不能用于发布到其他repo
# # external_repository: mkbooks/blog 发布到哪个repo
# github_token: ${{ secrets.ACTIONS_DEPLOY_KEY }} # 发布到其他repo需要提供上面生成的personal access token
# publish_dir: ./public # 注意这里指的是要发布哪个文件夹的内容，而不是指发布到目的仓库的什么位置，因为hugo默认生成静态网页到public文件夹，所以这里发布public文件夹里的内容
# publish_branch: gh-pages # 发布到哪个branch
# commit_message: ${{ github.event.head_commit.message }}
# name: Debugging with SSH
# on: push
# jobs:
# build:
# runs-on: ubuntu-latest
# steps:
# - uses: actions/checkout@v1
# - name: Try Build
# run: ./not-exist-file.sh it bloke build
# - name: Start SSH via Ngrok
# if: ${{ failure() }}
# run: curl -sL https://gist.githubusercontent.com/retyui/7115bb6acf151351a143ec8f96a7c561/raw/7099b9db76729dc5761da72aa8525f632d8875c9/debug-github-actions.sh | bash
# env:
# # After sign up on the https://ngrok.com/
# # You can find this token here: https://dashboard.ngrok.com/get-started/setup
# NGROK_TOKEN: ${{ secrets.NGROK_TOKEN }}
# # This password you will use when authorizing via SSH
# USER_PASS: ${{ secrets.USER_PASS }}
# - name: Don't kill instace
# if: ${{ failure() }}
# run: sleep 8640h # Prevent to killing instance after failure
|
基于旧的YAML文件，修改了一个完整可用的版本，将Hugo构建的网站自动部署到gh-pages分支：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
| name: Build and Deploy Hugo Site
on:
push:
branches:
- main
jobs:
build-and-deploy:
runs-on: ubuntu-latest
permissions:
contents: write # 需要写入权限来推送gh-pages分支
steps:
- name: Checkout repository
uses: actions/checkout@v3
with:
submodules: true
fetch-depth: 0
- name: Setup Hugo
uses: peaceiris/actions-hugo@v2
with:
hugo-version: '0.91.2'
extended: true
- name: Build with Hugo
run: hugo --minify -b https://mkbooks.github.io/blog/
- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./public
publish_branch: gh-pages
# cname: mkbooks.github.io # 如果使用自定义域名，可以取消注释并修改
commit_message: ${{ github.event.head_commit.message }}
|
重要配置说明：
- 权限设置：
1
2
| permissions:
contents: write
|
这行很重要，它允许工作流有写入权限来创建/更新gh-pages分支。
- GITHUB_TOKEN：
部署后的设置：
部署完成后，需要在仓库设置中配置GitHub Pages：
进入仓库 Settings → Pages
Source选择：Deploy from a branch
Branch选择：gh-pages → /(root)
保存
备用方案（如果上述方案失败）：
如果遇到权限问题，可以使用个人访问令牌：
1
2
3
4
5
6
7
| - name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v3
with:
deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }} # 或者使用 personal_access_token
# 或者使用 personal_token: ${{ secrets.PERSONAL_TOKEN }}
publish_dir: ./public
publish_branch: gh-pages
|
- 调试版本（遇到问题时使用）：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
| name: Build and Deploy Hugo Site (Debug)
on:
push:
branches: [main]
jobs:
build-deploy-debug:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v3
with:
submodules: true
fetch-depth: 0
- name: Debug Info
run: |
echo "Repository: ${{ github.repository }}"
echo "Event name: ${{ github.event_name }}"
echo "Ref: ${{ github.ref }}"
ls -la
- name: Setup Hugo
uses: peaceiris/actions-hugo@v2
with:
hugo-version: '0.91.2'
extended: true
- name: Build Hugo
run: |
hugo version
hugo --minify -b https://mkbooks.github.io/blog/
echo "Build completed"
ls -la public/
- name: Deploy
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./public
publish_branch: gh-pages
keep_files: false # 清除gh-pages分支的旧文件
force_orphan: true # 创建单次提交的gh-pages分支
- name: Verify Deployment
run: |
echo "Deployment completed at $(date)"
echo "Visit https://mkbooks.github.io/blog/"
|
故障排除步骤：
- 检查工作流运行状态：
到仓库的 “Actions” 标签页查看运行状态
点击失败的作业查看详细错误信息
- 常见问题：
- 手动测试：
1
2
3
4
5
| # 本地测试构建
hugo --minify -b https://mkbooks.github.io/blog/
# 查看生成的文件
ls -la public/
|
将修改后的YAML文件保存到 .github/workflows/deploy.yml，然后推送到main分支就会自动触发构建和部署。