从0到1搭建个人技术博客：用Hugo+GitHub Pages实现免费自动化部署

准备工作与环境配置

系统环境与工具安装

本教程基于Windows 10/11系统，macOS和Linux用户操作类似。首先安装以下三个必备工具：

• Git：版本控制工具，用于管理代码和部署到GitHub
• Hugo：静态网站生成器，用于构建博客
• Visual Studio Code：代码编辑器（可选，但推荐）

安装Git：访问 https://git-scm.com/download/win 下载最新版本。安装时所有选项保持默认即可。

安装Hugo：访问 https://github.com/gohugoio/hugo/releases 下载Windows版本的hugo_extended_0.xxx.0_windows-amd64.zip（xxx代表最新版本号）。解压后将hugo.exe文件复制到C:\Windows\System32目录。

验证安装：打开命令提示符（Win+R输入cmd），分别执行以下命令：

``` git --version hugo version ```

如果显示版本号，说明安装成功。

GitHub账号准备

访问 https://github.com 注册账号。注册后需要创建两个仓库：

1. 主仓库：用户名.github.io（例如zhangsan.github.io）
2. 源码仓库：blog-source（名称可自定）

创建主仓库步骤：登录GitHub → 点击右上角"+" → New repository → Repository name输入"用户名.github.io" → 选择Public → 勾选"Add a README file" → Create repository。

创建源码仓库步骤：同上，但Repository name输入"blog-source"。

本地博客项目初始化

创建Hugo站点

打开命令提示符，进入你希望存放博客项目的目录，例如：

``` cd D:\Projects ```

执行以下命令创建新的Hugo站点：

``` hugo new site myblog cd myblog ```

此时会生成以下目录结构：

• archetypes/：内容模板
• content/：博客文章
• layouts/：布局文件
• static/：静态资源（图片、CSS等）
• themes/：主题文件夹
• config.toml：配置文件

安装并配置主题

我们使用PaperMod主题，这是一个简洁高效的Hugo主题。在myblog目录下执行：

``` git init git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod ```

编辑config.toml配置文件，用记事本或VS Code打开，清空原有内容，粘贴以下完整配置：

``` baseURL = "https://你的用户名.github.io/" languageCode = "zh-cn" title = "我的技术博客" theme = "PaperMod" [params] homeInfoMode = "PostList" socialIcons = [ { name = "github", url = "https://github.com/你的用户名" }, { name = "rss", url = "https://你的用户名.github.io/index.xml" } ] [menu] [[menu.main]] identifier = "posts" name = "文章" url = "/posts/" weight = 1 [[menu.main]] identifier = "tags" name = "标签" url = "/tags/" weight = 2 [[menu.main]] identifier = "search" name = "搜索" url = "/search/" weight = 3 [outputs] home = ["HTML", "RSS"] ```

将"你的用户名"替换为你的GitHub用户名，保存文件。

创建第一篇博客文章

执行命令创建文章：

``` hugo new posts/我的第一篇博客.md ```

用文本编辑器打开content/posts/我的第一篇博客.md，修改内容为：

``` title: "我的第一篇博客" date: 2024-01-15T10:00:00+08:00 draft: false tags: ["Hugo", "教程"] 欢迎来到我的博客 这是我的第一篇博客文章，使用Hugo和GitHub Pages搭建。 技术栈 - Hugo静态网站生成器 - GitHub Pages免费托管 - PaperMod主题 后续计划 1. 添加更多技术文章 2. 配置评论系统 3. 优化SEO设置 ```

注意：draft必须设为false，否则文章不会发布。

本地测试与预览

启动本地服务器

在myblog目录下执行：

``` hugo server -D ```

-D参数表示包含草稿文章。看到"Web Server is available at http://localhost:1313/"后，在浏览器打开该地址。

如果页面显示异常，检查config.toml配置是否正确，特别是theme参数是否为"PaperMod"。

常见问题解决

• 页面404：确保config.toml中baseURL正确
• 样式丢失：检查themes/PaperMod文件夹是否存在
• 文章不显示：确认文章frontmatter中draft: false

本地测试正常后，按Ctrl+C停止服务器。

部署到GitHub Pages

生成静态文件

在myblog目录执行：

``` hugo ```

此命令会在项目根目录生成public文件夹，包含所有静态HTML文件。

配置GitHub Pages

首先配置本地Git：

``` git config --global user.name "你的GitHub用户名" git config --global user.email "你的GitHub邮箱" ```

进入public目录，将其初始化为Git仓库并推送到主仓库：

``` cd public git init git add . git commit -m "首次部署" git branch -M main git remote add origin https://github.com/你的用户名/你的用户名.github.io.git git push -u origin main ```

等待1-2分钟后，访问https://你的用户名.github.io，应该能看到你的博客。

自动化部署脚本

回到myblog目录，创建deploy.sh脚本文件（Windows用户创建deploy.bat）：

Linux/macOS用户创建deploy.sh：

``` !/bin/bash echo -e "\033[0;32m生成静态文件...\033[0m" hugo echo -e "\033[0;32m进入public文件夹\033[0m" cd public echo -e "\033[0;32m添加变更\033[0m" git add . echo -e "\033[0;32m提交变更\033[0m" msg="rebuilding site $(date)" if [ -n "$" ]; then msg="$" fi git commit -m "$msg" echo -e "\033[0;32m推送到GitHub\033[0m" git push origin main echo -e "\033[0;32m返回项目根目录\033[0m" cd .. ```

Windows用户创建deploy.bat：

``` @echo off echo 生成静态文件... hugo echo 进入public文件夹 cd public echo 添加变更 git add . echo 提交变更 set msg=rebuilding site %date% %time% if not "%1"=="" set msg=%1 git commit -m "%msg%" echo 推送到GitHub git push origin main echo 返回项目根目录 cd .. ```

以后每次更新博客后，只需执行./deploy.sh（Linux/macOS）或deploy.bat（Windows）。

源码备份与版本管理

推送源码到GitHub

在myblog目录（不是public目录）执行：

``` git add . git commit -m "初始提交" git remote add origin https://github.com/你的用户名/blog-source.git git branch -M main git push -u origin main ```

这样你的源码就备份到了blog-source仓库。

工作流总结

1. 在myblog目录写新文章：hugo new posts/文章标题.md
2. 编辑文章内容，设置draft: false
3. 本地测试：hugo server -D
4. 生成并部署：执行deploy脚本
5. 源码备份：git add . && git commit -m "更新" && git push

高级配置与优化

自定义域名（可选）

如果你有自己的域名：

1. 在域名注册商处添加CNAME记录：
• 类型：CNAME
• 主机记录：@或www
• 记录值：你的用户名.github.io
2. 在myblog/static目录创建CNAME文件，内容为你的域名（如blog.example.com）
3. 重新部署：hugo && cd public && git add . && git commit -m "添加域名" && git push
4. GitHub仓库设置：Settings → Pages → Custom domain → 输入你的域名 → Save

添加Google Analytics

在config.toml中添加：

``` [params] analytics = { google = "G-XXXXXXXXXX" } ```

将G-XXXXXXXXXX替换为你的Google Analytics测量ID。

配置搜索功能

PaperMod主题内置搜索，需要在config.toml中启用：

``` [outputs] home = ["HTML", "RSS", "JSON"] [params] assets = { disableHLJS = true } ```

创建搜索页面：hugo new search.md，编辑内容：

``` title: "搜索" layout: "search" summary: "search" placeholder: "输入关键词搜索..." ```

文章封面图片

在文章frontmatter中添加：

``` title: "文章标题" cover: image: "images/cover.jpg" alt: "封面描述" ```

将图片放在static/images/目录下。

维护与更新

更新主题

在myblog目录执行：

``` git submodule update --remote --merge ```

如果更新后出现样式问题，检查主题文档或回退版本。

添加新功能

所有自定义修改应放在以下位置：

• 自定义CSS：assets/css/extended/custom.css
• 自定义布局：layouts/partials/
• 自定义短代码：layouts/shortcodes/

避免直接修改themes/PaperMod中的文件，否则更新主题时会丢失修改。

备份策略

定期备份以下内容：

1. 整个myblog文件夹（源码）
2. 数据库文件（如果将来添加评论系统）
3. 自定义配置和图片资源

可以使用GitHub Actions设置自动备份到其他仓库。