目录

年初时写过一篇很混乱的hugo搭建笔记:在Windows上搭建Hugo博客之Github部署填坑记 。这篇的思路大致是将本地 hugo 命令生成的public文件夹丢到github的名称为<github_username>.github.io的repository上,写了新博文后public内的内容需要更新并重新部署到github pages上。由于用了自定义域名,还有一些细节问题需要注意(后经友邻提醒,CSS无法正常加载可能有其他原因,应该不需要借助_config.yml使网页正常显示;也不需要每次删除public内部分内容,直接覆盖并调整后续操作即可;CNAME等需要保留的文件放进static文件夹中即可),虽然每次发布的过程也称不上麻烦,但还是会觉得有些繁琐,并因为Github Action运转失败(也不想借助VPS与github之外的第三方的应用来进行部署),我也一直只能借助电脑进行添加、删除、修改博文的操作,而无法在其他机器上快速编辑。

最近不少友邻在尝试新建博客并尝试自动部署,看着看着也想久违地挑战下之前一直失败的自动部署,总算是成功了!部署过程中参考了不少教程和笔记,也踩了一些坑,希望这篇笔记可以帮到对静态博客感兴趣的朋友~

♡ 正式开始前你需要知道

  • 操作系统为Windows 10,Mac的操作过程应该是相似的,将涉及到系统操作时的步骤替换为Mac的即可
  • 用这篇笔记的方法实现自动部署,最终效果为可以通过在其他机器上登录github远程修改博文与各种设定,修改后github action会自动运行,将改动推送到博客页面上;在本地发布新博文,依旧需要至少三步git操作(git addgit commitgit push),因为远程可以进行操作,每次push前最好添加一步 git pull避免版本混乱
  • 搭建前需要本机安装 githugo ,还需要你有一个 github 的帐号,相关步骤这里不再阐释;如果你有自定义域名的需求,你还需要去购买域名或者申请免费域名

✦ 快速在本地生成一个博客!

Sites 和 Bin

你的hugo目录下此时应该有两个文件夹:Sites和bin 。bin文件夹平时不用去管,如需更换hugo版本可用新版本的hugo直接将原文件覆盖,在这里查看并下载各版本的hugo:Hugo Releases ,个别主题需要你使用extended版本:

If you process SCSS or SASS to CSS in your Hugo project, you need the Hugo extended version, or else you may see this error message:

error: failed to transform resource: TOCSS: failed to transform "scss/main.scss" (text/x-scss): this feature is not available in your current Hugo version

Hugo Frequently Asked Questions

使用hugo命令,需要将hugo添加到环境变量: 搭建Hugo时需要注意的坑

进入Site文件夹,鼠标右键点击Git Bash或打开Git Bash后cd到这个目录,创建你的hugo博客所在目录(替换为你的博客名称):

hugo new site <example>
emample
├── archetypes
│   └── default.md
├── config.toml
├── content
├── data
├── layouts
├── static
└── themes

简单说下每个目录和文件是做什么的。archetypes文件夹用于存放模板,hugo new posts/new-post.md会使用default.md中的模板生成新博文;config.toml是存放博客基础设置的文件,一般会被安装后的主题中的同名文件替代;content用来存放page与post,所有新博文都要存放在content中;data用于存放数据模板;layouts用来存放布局模板文件,如果你想要调整你安装的主题中的页面布局,可以在layouts中放入同名文件,hugo将优先读取根目录中的layouts文件;static用来存放静态资源,比如自定义css、图片图标等;themes用来放你想要使用的主题。

进入新生成的博客文件夹并初始化一个空的 git 本地仓库,之后博客文件夹里会出现一个隐藏的.git文件夹。

cd <example>
git init

第一次使用Git和SSH?

如果之前进行过git全局配置,且本机上存有SSH key,可以忽略这步。SSH key一般存储在系统盘 C:\Users<用户名>.ssh 目录中,git全局设置存在 C:\Users<用户名>.gitconfig 文件中。

先来生成SSH密钥!

ssh-keygen -t rsa -C "[email protected]"
# -C 的意思是注释,后面的邮箱可以填写任意邮箱,与github账号邮箱不一致也是可以的

之后会跳出一堆提示,在系统提示输入passphrase时直接回车不添加。生成的密钥对会储存在C:\Users<用户名>.ssh中,公钥存放在id_rsa.pub里,私钥存放在id_rsa里,请妥善保管密钥对,公钥稍后我们需要使用,私钥非极特殊情况请勿上传到本机外的地方!

接下来在博客根目录进行git的配置!

git config user.name "examplename"
git config user.email "[email protected]"

建议将引号内的内容替换为准备部署博客的github账号用户名和密码,当然,用其他的名称和邮箱替代也可,只是这样每次本地提交commit时github上会无法查看提交者信息。

之后点进.git目录查看config文件,可以发现里面多了name和email信息。

网络上很多教程的这两行命令后有添加 --global,这个的意思是全局配置,如果git账户没有进行本地配置,将默认使用全局配置,使用 --global后name与email信息将存在系统目录的C:\Users<用户名>.gitconfig 文件中。

来安装主题吧!

这里挑选你心仪的主题,看看demo的效果是否满意,如果没有demo也不要紧,下载到本地后也能够在部署前查看。

有三种安装主题的方法。最简单粗暴的一种是在主题的github页面直接下载主题打包文件,解压到themes中就好了;另外两种可以参考hello-friend这个主题的说明,在themes目录下git clone或者git submodule add,后者能较方便的升级主题(根目录上传到GitHub后,themes文件夹会显示为一个无法打开的带白箭头的文件夹图标,之后action要想跑起来一定要记得加上submodule的配置)。一般根据主题的说明文档进行安装就好了~

下载好的主题目录下会有一个exampleSite的示例文件夹,把里面的东西复制下来,覆盖根目录中的文件和文件夹,打开新的config.toml文件,修改theme = “example-theme” 为你安装的主题名,主题名要与themes中的主题文件夹名称一致。这样一个主题就安装好了。

在sites目录下git bash,hugo server来看下主题的效果!(hugo server -D的话草稿也会显示,注意是大写D)跳出一大堆提示后,在任意浏览器打开 http://localhost:1313/ 就能实时查看博客效果与调整。如果的博客设置有误,页面会无法查看,请先排除错误后再进行尝试。不需要查看后Ctrl+C退出即可。


✦ 自动部署准备

两种部署方案

一般来说利用Github Action进行自动部署有两个方案。一个是建一个repository并使用两个分支(main和gh-pages),这样做的不太好的是,该repository只能设置为公开,main中的博客根目录内容谁都可以看(包括草稿状态的已上传博文),除非付费将页面公开(听说gitlab可以免费单独公开私有项目的页面);另一个是建两个repositories,一个存放根目录文件,设置为私密,另一个用来存放public中的内容,设置为公开。

两个方法我都有尝试,主要说说建立两个repositories的部署方案。

上传公钥

我们既可以将公钥直接上传到该github用户的setting里,也可以上传到单独这个repository的setting里。前面的方法的效果是,如果你还想用这个账号建博客或者做一些其他项目,不需要二次上传公钥。

点击github页面右上角头像右侧下拉按钮,进入Settings,找到左侧页面 SSH and GPG keys ,点击New SSH key ,取一个便于识别的名称,下方填入之前生成的id_rsa.pub中的内容(以"ssh-rsa"开头,以邮箱结尾)。

之后我们在本地测试看看,在git bash里输入:

ssh -T [email protected]

成功的话会提示:

Hi <github-username>! You've successfully authenticated, but GitHub does not provide shell access.

生成Token

右上角Settings里找到Developer settings,再点Personal access tokens,Generate new token生成新的token,有效期可选永久生效(永久生效的话,这个Token就不要用于其他用途,只用于部署这一个hugo博客),否则要记得定时更换或称新生成Token。

Select scopes里勾选repo全部内容与workflow。最后点击绿色按钮生成。

生成后,Token上会浮现一串字符,将它复制下来备份。页面刷新后这个Token将不再显示,所以在导入Token前不要把它弄丢!

建立存放博客根目录的仓库并储存到本地

接下来建根目录用的私密仓库。右上角新建repository,Repository name随意填,设置为private,创建。

接下来将仓库remote到本地。复制SSH链接,进入git bash,确保目前的位置是在博客根目录下。

git remote add origin [email protected]:<github-username>/<repository-name>.git

如果你这个目录之前存有远程仓库,你需要先把之前的orrigin删掉,再创建新的。

git remote查看当前目录下所有远程仓库,如果无结果说明这里之前没有远程仓库;如果有一个已经不再使用origin,git remote rm origin将它删除掉 。

git通过命令更换远程仓库地址—–和更换地址后对项目进行操作显示无权限问题

将博客根目录上传至github新建的仓库

确保git bash中位置为博客根目录,git默认的分支应该是(master),因为现在github的默认分支从master换成了main(详见GitHub将替换掉master等术语),我们先切换分支到main:

git checkout -b main

之后输入这三个命令(今后要经常和这三个指令打招呼了)

git add . # 添加目录下全部内容
git commit -m "new blog" # 提交说明,出问题了可以回退到之前的commit
git push -u origin main # 将本地内容推送到远程

没有报错的话,现在已经可以在github刚刚创建的仓库中看到推送上去的内容了~

检查检查有没有缺少什么东西。空文件夹不会被push上去,不用去管;如果有其他文件夹没有上传上去,看看你根目录下有没有.gitignore这个文件,里面存放上传时会被忽略掉的目录与文件(比如我正在用的Tranquilpeak主题就会忽略掉主题文件夹,应该是用于本地魔改主题测试放置远程受影响用的),把这个文件删掉或者把里面的内容清除,再重复上面的指令,这次应该就成功了。

为根目录仓库生成Secrets

进入刚刚建好的repository,点进它的Settings中,找到Secrets,点击New repository secret,名称为PERSONAL_TOKEN,内容为之前备份下来的Token。

建立存放public目录的仓库

建立仓库

回到github再建一个repository。注意这次repository的名称须为 .github.io 这个格式。这个仓库要设置为公开状态。

题外话:repository名称问题

Github关于github pages 类型的说明

个人建博客不考虑organization的情况。除去网络上大多数教程强调的使用 .github.io 作为repository名称的方法,其实还可以建一个任意名称的仓库,在不使用自定义域名的前提下,这样建起来的hugo博客网址为 .github.io/ 。

比方说你github的用户名为suicablue,repo名为my-blog,那最后你的博客域名就是 suicablue.github.io/blog 。少数派的这篇教程就是这样建起来的:使用 Hugo 从 0 到 1 搭建个人博客

确定要使用自定义域名的话,就完全不需要管repository的名称问题了。但想要用github免费提供的 .github.io 这个域名的话,就需要注意一下名称问题了。


✦ 自动部署!

确认以下步骤是否已经完成:

建好两个仓库,一个私有的已经存放博客根目录内容的仓库,一个公开的空白仓库;github账号已经上传了无passphrase的公钥并确保公钥可以使用,生成了Token并将其添加到私有仓库的Secrets中

Github Action

进入博客根目录仓库,点上方的Actions,set up a workflow yourself,之后你会发现github会在根目录下新建/.github/workflows/xxx.yml文件,下方是这个文件的编辑区域。把下面的配置复制进去,yml文件的名称与配置第一行的name随意填,特别注意我添加注释的地方。

name: hugo-blog

on:
  push:
    branches:
      - main  # 博客根目录的默认分支,这里是main,有时也是master
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-20.04
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - uses: actions/[email protected]
#         with:               # 如果你安装主题时用的是git submodule add
#           submodules: true  # 那么这三行不必注释掉,这一行填写 true
#           fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

      - name: Setup Hugo
        uses: peaceiris/[email protected]
        with:
          hugo-version: '0.88.1'  # 填写你的hugo版本,可用hugo version查看
          extended: true          # 如果你使用的不是extended版本的hugo,将true改为false

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/[email protected]
        if: ${{ github.ref == 'refs/heads/main' }}  # 注意填写main或者master
        with:
          personal_token: ${{ secrets.PERSONAL_TOKEN }} # 如果secret取了其他名称,将PERSONAL_TOKEN替换掉
          external_repository: <username>/<username>.github.io # 填写远程仓库,不一定是这个格式,按照自己的情况写 
          publish_dir: ./public
          cname: blog.example.com        # 填写你的自定义域名。如果没有用自定义域名,注释掉这行

格式参考GitHub Pages action,可以根据自己需要,按照说明文档上的建议对上面的配置进一步调整。

提交commit,保存!之后会发现action在尝试运行,等待不到一分钟结果就会出来,变成绿色就说明成功啦!

这时跑去公开仓库瞅瞅看,应该已经可以看到自动建了一个名为gh-pages的分支,里面出现了许多东西,此时打开你的博客域名应该已经可以看到博客内容啦!

如果github action没成功跑起来也不要慌,点进deploy详细看下报错,一般都可以根据报错内容发现原因,对应去调整后再跑几遍即可。

自定义域名注意事项

  • 博客根目录下的config文件中base url更换为自定义域名
  • 为自定义域名添加了CNAME记录(顶级域名也可添加四条A记录),详见github官方说明:Managing a custom domain for your GitHub Pages site
  • 部署成功后,进入公开仓库settings,pages页面添加自定义域名,等待DNS检验成功
  • 如果使用了CDN(比如cloudflare),github上的强制https按钮可能不能点;cloudflare免费提供https证书,如果无法正常显示https,可以建立强制https规则
  • 不适用CDN的情况下,github已支持为自定义域名办法let’s encrypt证书,稍等一会儿即可生效

✧ 部署完成后续管理

按照上述流程完成部署后,今后每次在本地执行操作前,都要记得用git pull先同步本地与远程操作。

上面我们在远程博客根目录新建了workflow,在本地开始写新的博文前,先在本地的博客根目录进行同步:

git pull

之后本地会出现.github文件夹。记得每次在github远程编辑并commit后,本地都要pull;而本地无论是写博文还是调整主题(主题可在根目录同名文件夹内进行调整,不建议直接对themes下的设定进行改动),都建议先用 hugo server本地查看效果,确定能够正常显示博客与调整后的内容后再push到远程。

到这里,hugo博客的搭建与部署过程就结束啦!(撒花)


✧ 一些可能有用的 tips

  1. 执行hugo server过程中错误退出git,导致之后执行时1313端口被占用

    windows+r 输入cmd 打开窗口:

    netstat -aon|findstr "1313"  筛选使用1313端口的进程
    taskkill /f /PID xxxxx  杀死占用的进程
    

    来源:端口号被占用?怎么办

  2. 空文档无法提交的解决方法

    在你想要提交的空文档下新建一个.gitkeep文件,里面填入以下内容:

    # Ignore everything in this directory
    *
    # Except this file !.gitkeep
    

    来源:git提交空文件夹

  3. 我不在意博客根目录公开,我不想要建两个仓库

    这种情况大致的操作过程和上面是一样的,只是如果你需要使用.github.io这个免费域名时同样要注意仓库名称问题,并将workflow文件里的这行删掉:

    external_repository: <username>/<username>.github.io
    

    之后你的仓库中会有main和gh-pages两个分支,main分支存放博客根目录文件,gh-pages存放页面文件。

  4. github pages如何才能使用呢?

    • 发布路径在默认分支main的根目录

    • 发布路径在gh-pages分支

    • 发布路径在默认分支main的docs目录

    来源:Hugo配合GitHub搭建博客(Windows 10)

    这边笔记的思路就是发布路径在gh-pages分支,使用其他思路也可成功完成部署,但需要调整workflow设置。需要用docs替换默认的public目录的话,博客根目录下config中添加这一行:

    publishDir = "docs"
    
  5. 为Hugo添加favicon

    一般情况下,在static目录下直接添加favicon.ico就可以添加上favicon了,但也不排除部分主题设置不同的情况。要让多平台支持favicon的显示,可以参考这篇博文:Add Favicon to Hugo-Based Website

✧ 参考链接

Hugo Frequently Asked Questions

git通过命令更换远程仓库地址—–和更换地址后对项目进行操作显示无权限问题

About GitHub Pages

使用 Hugo 从 0 到 1 搭建个人博客

Managing a custom domain for your GitHub Pages site

端口号被占用?怎么办

git提交空文件夹

Hugo配合GitHub搭建博客(Windows 10)

Add Favicon to Hugo-Based Website

折腾Hugo | GitHub Pages | Github Actions自动构建发布免费个人网站

Hugo使用Github Action自动部署博客到Github Pages

使用 Github Action 实现全自动部署

阮一峰:GitHub Actions 入门教程

搭建Hugo时需要注意的坑

Alola World | 暨简明麻瓜快速念咒 Hugo 搭建笔记