跳至内容
博客列表
jekyll 博客迁移为 Hugo

jekyll 博客迁移为 Hugo

April 26, 2026

jekyll 博客迁移为 Hugo

痛点：Hugo (对比 Jekyll)

在 DevOps 和静态网站生成（SSG）的圈子里，Jekyll 是前辈，但 Hugo 是目前的“性能之王”。以下是它在工程体验上的三大降维打击：

1. Zero Dependency

  • Jekyll 的痛点： 它是用 Ruby 写的。你为了跑起来，必须折腾 Ruby 环境、装 bundler、解决 Gemfile 版本冲突。换台电脑经常跑不起来，让人非常崩溃。

  • Hugo 的优势： 它是用 Go 语言编写的。Hugo 编译出来就是一个独立的二进制文件。不需要装 Go 环境，不需要装任何依赖，下载那个 .exe 或执行 brew install hugo，立刻就能跑，极其干净。

2. 最快的静态网站生成器

  • Jekyll 的痛点： 当你的博客文章超过 100 篇时，Jekyll 的本地编译速度会肉眼可见地变慢，每次保存可能要等好几秒浏览器才会刷新。

  • Hugo 的优势： 号称“世界上最快的静态网站生成器”。哪怕你有上万篇文章，它的构建时间也是以毫秒计算的。保存瞬间，渲染完成。

3. 极简的本地预览指令

在 Hugo 中，只需要在博客根目录下敲下这一行命令：

# -D 参数表示同时渲染草稿 (Drafts)
hugo server -D
  • 本地实时更新： http://localhost:1313/

Jekyll 到 Hugo 的企业级迁移 SOP：

阶段一：本地架构重组 (Directory Restructuring)

  • Hugo 的目录规范和 Jekyll 类似，但更加严谨。我们需要把你的资产“重定向”到 Hugo 认识的路径里。请在终端执行以下操作：

1. 清理历史包袱 (Drop Legacy Dependencies)

既然不用 Jekyll 了，Ruby 的依赖和本地编译的产物必须立刻销毁，防止环境污染。

# 删除 Ruby 依赖文件 和 旧的编译产物
rm -rf Gemfile Gemfile.lock _site/

2. 初始化 Hugo 骨架 (Init Hugo)

安装hugo

  • 安装Hogo通过github的hugo发行版选择win版本

  • 将压缩包全部解压缩到本地新创建的D:/Hugo文件夹下

  • 此电脑右击来新建Path的环境变量添加路径D:\Hugo

  • hugo --version验证安装成功


wang@DESKTOP-IE4JJEG MINGW64 /d/Git/blogs/blogs.github.io (main)
$ hugo --help
hugo is the main command, used to build your Hugo project.

Hugo is a Fast and Flexible Static Site Generator
built with love by spf13 and friends in Go.

Complete documentation is available at https://gohugo.io/.
  • 在当前网站目录下强制初始化 Hugo 结构（--force 是因为目录非空）。

	wang@DESKTOP-IE4JJEG MINGW64 /d/Git/blogs/blogs.github.io (main)
	$ hugo new site . --force
	Congratulations! Your new Hugo project was created in D:\Git\blogs\blog
	s.github.io.
	
	Just a few more steps...
	
	1. Change the current directory to D:\Git\blogs\blogs.github.io.
	2. Create or install a theme:
	   - Create a new theme with the command "hugo new theme <THEMENAME>"
	   - Or, install a theme from https://themes.gohugo.io/
	1. Edit hugo.toml, setting the "theme" property to the theme name.
	2. Create new content with the command "hugo new content <SECTIONNAME>\
	<FILENAME>.<FORMAT>".
	3. Start the embedded web server with the command "hugo server --buildD
	rafts".
	
	See documentation at https://gohugo.io/.

3. 核心资产映射 (Data Migration)

这是最关键的一步。把 Jekyll 的核心文件移动到 Hugo 的标准目录结构中：


	# 1. 迁移文章：Hugo 的文章必须放在 content 目录下
wang@DESKTOP-IE4JJEG MINGW64 /d/Git/blogs/blogs.github.io (main)
$ mkdir -p content/posts

wang@DESKTOP-IE4JJEG MINGW64 /d/Git/blogs/blogs.github.io (main)
$ ls ./_posts/
2026-02-24-Nginx-softlink-upgrade.md  2026-03-20-FTP-Win.md
2026-03-03-Alist-Mount.md             2026-03-20-docker-junior.md
2026-03-03-SSHD-remote-connect.md     2026-03-21-SSH-Pubkey.md
2026-03-04-Rocky9-resume.md           2026-03-31-DingDing-Upgrade.md
2026-03-05-rsync-errors.md            2026-03-31-DingDing.md
2026-03-08-Nginx-Website.md           2026-03-31-HeFeng-DingDing.md
2026-03-12-NFS.md                     2026-04-11-Yum-Advanced.md
2026-03-12-Nginx-Shopping-Website.md  2026-04-15-Docker-Nodejs.md
2026-03-12-Pages-cloudFlare.md        2026-04-16-Linux-Commands.md
2026-03-15-SSH-Remote.md              2026-04-18-Bash-Scripting.md
2026-03-17-add-swap.md                2026-04-18-Terraform-Docker.md
2026-03-19-Email-Number.md            2026-04-20-IAM.md
2026-03-19-IPs-ban.md                 2026-04-21-Docker-Demo.md
2026-03-19-Zip.md                     2026-04-25-Tailscale.md
2026-03-20-Comics-Python.md

wang@DESKTOP-IE4JJEG MINGW64 /d/Git/blogs/blogs.github.io (main)
$ mv ./_posts/* ./content/posts/

wang@DESKTOP-IE4JJEG MINGW64 /d/Git/blogs/blogs.github.io (main)
$ ls ./content/posts/
2026-02-24-Nginx-softlink-upgrade.md  2026-03-20-FTP-Win.md
2026-03-03-Alist-Mount.md             2026-03-20-docker-junior.md
2026-03-03-SSHD-remote-connect.md     2026-03-21-SSH-Pubkey.md
2026-03-04-Rocky9-resume.md           2026-03-31-DingDing-Upgrade.md
2026-03-05-rsync-errors.md            2026-03-31-DingDing.md
2026-03-08-Nginx-Website.md           2026-03-31-HeFeng-DingDing.md
2026-03-12-NFS.md                     2026-04-11-Yum-Advanced.md
2026-03-12-Nginx-Shopping-Website.md  2026-04-15-Docker-Nodejs.md
2026-03-12-Pages-cloudFlare.md        2026-04-16-Linux-Commands.md
2026-03-15-SSH-Remote.md              2026-04-18-Bash-Scripting.md
2026-03-17-add-swap.md                2026-04-18-Terraform-Docker.md
2026-03-19-Email-Number.md            2026-04-20-IAM.md
2026-03-19-IPs-ban.md                 2026-04-21-Docker-Demo.md
2026-03-19-Zip.md                     2026-04-25-Tailscale.md
2026-03-20-Comics-Python.md

	
	# 2. 迁移静态资源（图片、CSS等）：Hugo 的静态文件必须放在 static 目录下
	
wang@DESKTOP-IE4JJEG MINGW64 /d/Git/blogs/blogs.github.io (main)
$ ls !$
ls ./assets/
css/  image/

wang@DESKTOP-IE4JJEG MINGW64 /d/Git/blogs/blogs.github.io (main)
$ mv ./assets/ ./static/

wang@DESKTOP-IE4JJEG MINGW64 /d/Git/blogs/blogs.github.io (main)
$ ls ./static
assets/


	
	# 3. 🚨 高危注意：迁移 CNAME 文件
	# 很多人迁移后发现自定义域名掉了，就是因为没把 CNAME 移到 static 里。
	# Hugo 编译时，只有 static 目录下的文件会被原封不动地复制到根目录！
wang@DESKTOP-IE4JJEG MINGW64 /d/Git/blogs/blogs.github.io (main)
$ mv ./CNAME ./static/

wang@DESKTOP-IE4JJEG MINGW64 /d/Git/blogs/blogs.github.io (main)
$ ls ./static/
CNAME  assets/
4. 处理运维脚本文件夹

对于 ansible-playbooks/ 和 k8s-manifests/ 这类非博客内容：

  • Hugo 的优势： 只要它们不在 content/ 或 static/ 目录下，Hugo 编译时会完全无视它们。这意味着你可以继续把它们安全地留在根目录作为代码仓库管理，不会被打包泄露到外网。

阶段二：配置与主题 (Configuration)

Jekyll 使用 _config.yml，而 Hugo 现代版本默认使用 hugo.toml。
  1. 删除旧配置： rm _config.yml

wang@DESKTOP-IE4JJEG MINGW64 /d/Git/blogs/blogs.github.io (main)
$ rm _config.yml
  1. 选择主题： SRE 博客不需要花里胡哨，推荐极简、极速的 PaperMod 主题。

	git submodule add https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod
  1. 更新 hugo.toml： 打开根目录的 hugo.toml，写入基础配置：

    baseURL = 'https://你的自定义域名.com/'
    languageCode = 'zh-cn'
    title = '我的 SRE 知识库'
    theme = 'PaperMod'

阶段三：部署 CI/CD 流水线 (The GitOps Way)

  • 以前用 Jekyll，你可能依赖 GitHub Pages 原生的后台黑盒编译。现在，我们要把构建的控制权夺回来，使用 GitHub Actions。

  • 在根目录创建工作流文件：


	mkdir -p .github/workflows
	touch .github/workflows/hugo.yaml
  • 将以下 生产级 CI/CD 编排代码 填入 hugo.yaml。这段代码的作用是：只要你执行了 git push，GitHub 的云端服务器就会自动拉取最新的 Hugo 引擎，以毫秒级速度编译你的网站，并推送到 GitHub 边缘 CDN。

name: Deploy Hugo Site to GitHub Pages

on:
  # 监听 main 分支的 push 动作
  push:
    branches: ["main"] # 如果你的主分支叫 master，请修改这里
  workflow_dispatch:

# 设置权限，允许脚本推送静态文件到 GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

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

defaults:
  run:
    shell: bash

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          submodules: true # 必须开启，为了拉取你的主题
          fetch-depth: 0

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
          extended: true

      - name: Build with Hugo
        run: hugo --minify # 开启压缩，减少传输带宽

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./public # Hugo 默认的输出目录

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

Checklist

完成上述配置后，你需要做最后两件事：

  1. 在 GitHub 仓库设置中激活 Actions 部署： 去你仓库的 Settings -> Pages -> Source，将其从 Deploy from a branch 修改为 GitHub Actions。

  2. 提交并推送：


	git add .
	git commit -m "chore: migrate from Jekyll to Hugo and setup CI/CD"
	git push origin main
  • 修改categories：的内容为categories：[“tools”] 格式让hugo识别出来：

wang@DESKTOP-IE4JJEG MINGW64 /d/Git/blogs/blogs.github.io (main)
$ find content/posts/ -name "*.md" | xargs sed -i -E 's/^categories:[[:space:]]*([a-zA-Z0-9_-]+)[[:space:]]*$/categories: ["\1"]/g'

  • 直接在浏览器的地址栏里输入并访问后端分类页面： http://localhost:1313/categories/

  • 在 hugo.toml 文件追加前端显示功能：


# --- 全局导航栏配置 (Main Menu) ---
[menu]
  # 首页入口
  [[menu.main]]
    identifier = "home"
    name = "首页"
    url = "/"
    weight = 10

  # 分类入口 
  [[menu.main]]
    identifier = "categories"
    name = "分类"
    url = "/categories/"
    weight = 20

  # 标签入口 
  [[menu.main]]
    identifier = "tags"
    name = "标签"
    url = "/tags/"
    weight = 30


# 在具体文章内部补充

[params] # 开启文章元数据展示（日期、字数等） 
	
	hasCJKLanguage = true   # 开启 CJK 语言支持，保证中文字数计算的绝对精准
	ShowPostMeta = true     # 显示文章日期、字数等元数据
	ShowPostNavLinks = true # 显示上一篇/下一篇文章链接
	
	
	
	ShowPostMeta = true # 强制显示字数统计 (Word Count) 
	ShowWordCount = true # 强制显示预计阅读时间 (Reading Time) 
	ShowReadingTime = true
Tailscale 组网实践Regex