用Github Page 搭免费博客

参考：

Hugo官方: https://gohugo.io/hosting-and-deployment/hosting-on-github/

步骤

macOS安装hugo

1
2
3
4
5
# 安装hugo
brew install hugo

# 验证安装
hugo version

hugo 博客的搭建

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
# 创建新站点
hugo new site myblog
cd myblog

# 初始化git仓库
git init

# 添加主题（以hugo-theme-stack为例）
git submodule add https://github.com/CaiJimmy/hugo-theme-stack.git themes/hugo-theme-stack

# 复制主题示例配置
cp themes/hugo-theme-stack/exampleSite/config.yaml config.yaml

# 启动本地服务预览
hugo server -D

在github上新增blog仓库, 设置为隐私模式
- 登录GitHub，点击"New repository"
- Repository name: 如 myblog-source （可自定义）
- Public/Private: 选择 Private（私有）
- Initialize this repository with: 不勾选任何选项
- 点击"Create repository"
1 2 3 4
# 将本地项目推送到远程仓库 git remote add origin git@github.com:{your-username}/myblog-source.git git branch -M master git push -u origin master
创建 {username}.github.io 仓库，用于存放生成的静态网站
- 登录GitHub，点击"New repository"
- Repository name: 必须是 {your-username}.github.io （替换 {your-username} 为你的GitHub用户名）
- Public/Private: 选择 Public（GitHub Pages只支持公共仓库）
- Initialize this repository with: 不勾选任何选项
- 点击"Create repository"

github page 仓库添加 deploy ssh key

1
2
3
4
5
# 生成SSH密钥对（如果已有可跳过）
ssh-keygen -t rsa -b 4096 -C "your_email@example.com" -f ~/.ssh/github_pages_deploy_key

# 查看公钥内容
cat ~/.ssh/github_pages_deploy_key.pub

复制公钥内容（以ssh-rsa开头的部分）
在GitHub上进入 {username}.github.io 仓库
点击 Settings -> Deploy keys
点击 “Add deploy key”
Title: 填写描述（如 “Deploy Key”）
Key: 粘贴刚才复制的公钥内容
勾选 “Allow write access”
点击 “Add key”

在blog仓库的Settings -> Secrets and variables -> Actions中添加SSH密钥
- 复制私钥内容：
1
cat ~/.ssh/github_pages_deploy_key
- 在GitHub上进入 blog-source 仓库
- 点击 Settings -> Secrets and variables -> Actions
- 点击 “New repository secret”
- Name: 填写 DEPLOY_KEY
- Secret: 粘贴刚才复制的私钥内容（以—–BEGIN OPENSSH PRIVATE KEY—–开头的部分）
- 点击 “Add secret”

添加 github action, 上传到blog仓库的时候自动触发编译, 发布到 github page 仓库

在blog仓库根目录下创建 .github/workflows/gh-pages.yml 文件：

 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
name: Build and deploy

on:
  push:
    branches:
      - master
  workflow_dispatch:

permissions:
  contents: read

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    env:
      HUGO_VERSION: 0.158.0
    steps:
      - name: Checkout
        uses: actions/checkout@v6
        with:
          submodules: recursive
          fetch-depth: 0

      - name: Install Hugo CLI
        run: |
          wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb
          sudo dpkg -i ${{ runner.temp }}/hugo.deb

      - name: Install Node.js
        uses: actions/setup-node@v6
        with:
          node-version: 24

      - name: Setup Go
        uses: actions/setup-go@v6
        with:
          go-version: 1.26.1

      - name: Install Dart Sass
        run: |
          sudo snap install dart-sass

      - name: Install Node.js dependencies
        run: |
          [[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true

      - name: Build the site
        run: |
          hugo --minify

      - name: Deploy to external repository
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          branch: master
          folder: ./public
          repository-name: {your-username}/{your-username}.github.io
          ssh-key: ${{ secrets.DEPLOY_KEY }}

替换上述配置中的 {your-username} 为GitHub用户名，然后提交该文件到blog仓库。

Hugo 优化/设置

配置默认文章模板 (archetypes)

创建或修改 archetypes/default.md 文件，设置新文章的默认模板：

1
2
3
4
5
6
7
8
---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
categories: []
tags: []
slug: ""
---

自定义布局 (Layouts)

layouts/ 目录可以覆盖主题提供的默认模板

例如，创建 layouts/partials/footer/footer.html 自定义页脚

Sitemap优化

https://gohugo.io/templates/sitemap/

自定义 layouts/_default/sitemap.xml, 针对Google收录进行优化

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{{ printf "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\"?>" | safeHTML }}
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
  xmlns:xhtml="http://www.w3.org/1999/xhtml">
  {{ range .Data.Pages }}
    {{ if or (eq .RelPermalink "/") (and (strings.HasPrefix .RelPermalink "/post/") (ne .RelPermalink "/post/")) }}
      <url>
        {{ if site.Params.sitemapPrefix }}
        <loc>{{ site.Params.sitemapPrefix }}{{ .RelPermalink }}</loc>
        {{ else }}
        <loc>{{ .Permalink }}</loc>
        {{ end }}
        {{ if not .Lastmod.IsZero }}
          <lastmod>{{ safeHTML ( .Lastmod.Format "2006-01-02T15:04:05-07:00" ) }}</lastmod>
        {{ end }}
        {{ with .Sitemap.ChangeFreq }}
          <changefreq>{{ . }}</changefreq>
        {{ end }}
        {{ if ge .Sitemap.Priority 0.0 }}
          <priority>{{ .Sitemap.Priority }}</priority>
        {{ end }}
      </url>
    {{ end }}
  {{ end }}
</urlset>