Hugo使用方法

shawn

2023-10-15 513 words 3 minutes

Contents

折腾过很多种blog,都半途而废了,借助于AI,搭建hugo

使用 GitHub 配合 Hugo 部署个人博客是一个高效且免费的方案，主要利用 GitHub Pages 托管静态文件。以下是详细步骤：

一、准备工作

安装工具 ○ 安装 Hugo（建议安装扩展版 hugo_extended，支持更多主题功能） ○ 安装 Git ○ 注册 GitHub 账号

二、创建 Hugo 博客项目

初始化博客打开终端，执行以下命令创建 Hugo 项目（将 my-blog 替换为你的博客名称）：

hugo new site my-blog
cd my-blog

添加主题选择一个 Hugo 主题（推荐从 Hugo Themes 挑选），以经典主题 LoveIt 为例：

git init  # 初始化 Git 仓库
git submodule add https://github.com/dillonzq/LoveIt.git themes/LoveIt #（添加主题为子模块，方便后续更新）

配置主题

cp themes/LoveIt/exampleSite/config.toml .

编辑 config.toml，修改博客名称、作者、语言等基础信息。

创建第一篇文章bash

hugo new posts/hello-hugo.md

打开 content/posts/hello-hugo.md，用 Markdown 编写内容（注意删除头部 draft: true 才会发布）。 5. 本地预览启动 Hugo 本地服务器，实时查看效果：

hugo server -D  # -D 表示包含草稿文章

访问 http://localhost:1313 即可预览博客。

三、通过 GitHub Pages 部署

GitHub Pages 支持两种部署方式，推荐使用第二种（更灵活）：方式 1：直接部署 public 目录（简单但功能有限）

构建静态文件生成可部署的静态文件到 public 目录：

hugo  # 不带 -D，只生成非草稿内容

创建 GitHub 仓库在 GitHub 新建仓库，命名为 <你的用户名>.github.io（必须严格匹配，例如 octocat.github.io），这是 GitHub Pages 的特殊仓库名，用于托管个人主页。
推送 public 目录到仓库

cd public
git init
git add .
git commit -m "First deploy"
git branch -M main
git remote add origin https://github.com/<你的用户名>/<你的用户名>.github.io.git
git push -u origin main

几分钟后，访问 https://<你的用户名>.github.io 即可看到博客。方式 2：使用 GitHub Actions 自动部署（推荐）通过 GitHub Actions，可实现 “推送代码后自动构建并部署”，更适合持续更新。

创建两个仓库 ○ 仓库 A：命名为 my-blog-source（存储 Hugo 源码，私有 / 公开均可） ○ 仓库 B：命名为 <你的用户名>.github.io（存储最终静态文件，必须公开）
推送 Hugo 源码到仓库 Abash

四、在博客根目录（my-blog）执行

git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/<你的用户名>/my-blog-source.git
git push -u origin main

配置 GitHub Actions 在仓库 A 中创建工作流文件：

mkdir -p .github/workflows
touch .github/workflows/deploy.yml

编辑 deploy.yml，粘贴以下内容（替换 <你的用户名> 为实际 GitHub 用户名）：

name: Deploy Hugo Site to GitHub Pages
on:
  push:
    branches: [ main ]  # 源码仓库的主分支

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: true  # 拉取主题子模块
          fetch-depth: 0

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest' #可以指定版本 如 0.128.0
          extended: true  # 使用扩展版

      - name: Build
        run: hugo --minify  # 构建静态文件

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}  # 部署密钥
          external_repository: <你的用户名>/<你的用户名>.github.io  # 仓库 B
          publish_branch: main  # 仓库 B 的部署分支
          publish_dir: ./public  # 构建结果目录

配置部署密钥 ○ 本地生成 SSH 密钥（一路回车，不要设置密码） ○ 复制公钥（hugo-deploy-key.pub 内容）到仓库 B 的 Settings → Deploy keys，勾选 Allow write access。 ○ 复制私钥（hugo-deploy-key 内容）到仓库 A 的 Settings → Secrets → Actions，新建密钥 ACTIONS_DEPLOY_KEY，粘贴私钥。
完成部署推送代码到仓库 A 的 main 分支，GitHub Actions 会自动运行构建并部署到仓库 B。几分钟后，访问 https://<你的用户名>.github.io 即可看到博客。

五、后续维护

发布新文章：用 hugo new posts/新文章.md 创建并编辑，推送源码到仓库 A 后自动部署。
更新主题：执行 git submodule update –remote –merge 更新主题，再推送代码。
自定义域名：在仓库 B 的 Settings → Pages → Custom domain 中配置自己的域名（需提前解析 DNS）。

通过这种方式，你可以专注于内容创作，GitHub 会自动处理构建和部署，非常适合个人博客的长期维护。

换电脑后，只需重新配置开发环境并同步 Hugo 博客的源代码，就能继续维护博客。以下是详细步骤：

六、在新电脑上安装必要工具

安装 Git 下载并安装 Git，确保终端中能运行 git –version 验证安装成功。
安装 Hugo 根据新电脑的系统（Windows/macOS/Linux），从 Hugo 官网下载对应版本（推荐 hugo_extended 扩展版），安装后通过 hugo version 验证。

七、同步博客源代码

如果之前已将 Hugo 源码（非 public 目录）推送到 GitHub 仓库（如前文的 my-blog-source），直接克隆仓库即可：

克隆代码到新电脑打开终端，进入你想存放博客的目录，执行：

git clone https://github.com/<你的用户名>/my-blog-source.git
cd my-blog-source  # 进入博客目录

拉取主题子模块由于主题是作为 Git 子模块存在的，克隆后需要单独拉取主题文件：

git submodule update --init --recursive

（这一步会下载主题到 themes 目录，确保本地能正常预览）七、验证本地环境

预览博客运行本地服务器，确认博客能正常显示：

hugo server -D

访问 http://localhost:1313，检查文章、主题样式是否正常。 2. 测试发布流程可以尝试创建一篇测试文章，推送代码到 GitHub，验证 GitHub Actions 是否能自动部署（如果用了自动部署方案）：

hugo new posts/test-on-new-pc.md  # 创建文章
# 编辑文章后，删除 draft: true
git add .
git commit -m "Test on new PC"
git push origin main

八、补充说明

如果之前没备份源码：若只推送了 public 目录到 GitHub（方式 1），则需要从旧电脑拷贝 Hugo 源码（整个博客目录，除 public 外）到新电脑，再按上述步骤初始化 Git 并推送（建议后续改用双仓库 + Actions 的方式管理）。
密钥 / 权限问题：如果推送代码时出现权限错误，可能是新电脑未配置 GitHub 账号： a. 终端中运行 git config –global user.name “你的用户名” 和 git config –global user.email “你的邮箱” b. 若用 SSH 地址克隆，需在新电脑生成 SSH 密钥并添加到 GitHub（ Settings → SSH and GPG keys ）。

通过以上步骤，新电脑就能完全复用之前的博客环境，后续写作、更新主题等操作和原来完全一致。核心是确保源码通过 Git 备份，换设备时只需克隆代码 + 安装依赖即可。