使用Hugo搭建个人静态网站

XiongNeng 收录于 DevOps

2026-04-27 2026-05-24 约 3100 字预计阅读 7 分钟

Hugo是一个静态网站生成器，基于Go语言，使用Markdown写作。构建速度极快，速度之王 (10000页约2.95秒)。本地写作能实时预览，体验流畅。单个二进制文件，无需node_modules，升级只需替换新文件，适用于大型内容站，追求极致性能与长期免维护。

官网地址：https://gohugo.io/

安装

首先安装Go语言：https://go.dev/doc/install

再安装Git：https://git-scm.com/

然后打开Powershell，输入

1
2
3
# 先安装 Scoop 包管理器
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
irm get.scoop.sh | iex

如果已经是管理员用户了，就输入

`1`	`iex "& {$(irm get.scoop.sh)} -RunAsAdmin"`

然后安装 Hugo Extended 版（支持 Sass/SCSS 编译）

1
2
scoop install hugo-extended
scoop install sass

后续Hugo版本更新：

1
2
3
4
#更新 Scoop 和软件仓库
scoop update
#升级 hugo-extended 软件包
scoop update hugo-extended

创建站点并添加主题

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# 创建新站点
hugo new site xiongneng-me
cd xiongneng-me

# 初始化 Git 仓库
git init

# 以 FixIt 为例，添加为主题子模块
git submodule add --depth=1 https://github.com/hugo-fixit/FixIt.git themes/FixIt

# 更新子模块
git submodule update --remote --merge

最简配置文件

站点根目录下的 hugo.toml（或 config.yaml）是核心配置文件。以下是一个最小可运行配置：

 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
baseURL = 'https://xiongneng.me'
languageCode = 'zh-CN'
title = '飞污熊'
theme = 'FixIt'

[ params ]
[ params.profileMode ]
enabled = true
title = "全栈开发 | Python/Java/Web/AI"
subtitle = "专注于全栈开发和AI应用"
imageUrl = "images/avatar.png"
# 主页按钮（引导访客到项目页或博客）
[[params.profileMode.buttons]]
name = "项目作品"
url = "/projects"
[[params.profileMode.buttons]]
name = "技术博客"
url = "/posts"

# 社交链接
[ [ params.socialIcons ] ]
name = "github"
url = "https://github.com/yidao620c"
[[params.socialIcons]]
name = "email"
url = "mailto:yidao620@gmail.com"

创建第一篇内容

1
2
3
4
5
# 创建文章
hugo new posts/hello-world.md

# 用编辑器打开 content/posts/hello-world.md
# 将 draft: true 改为 draft: false（否则不会发布）

启动开发服务器

`1`	`hugo server`

浏览器访问 http://localhost:1313。Hugo 支持热重载——你改动 Markdown 或配置后，浏览器会自动刷新，无需手动重启。

文章规范

每篇文章顶部的 Front Matter 不只是给人类看的，它会影响搜索引擎收录效果：

1
2
3
4
5
6
7
8
---
title: "Hugo 建站完整指南"
date: 2026-04-28
draft: false
tags: ["Hugo", "建站", "静态网站"]
categories: ["教程"]
description: "从零搭建 Hugo 静态博客，并部署到阿里云的完整教程"
---

其中 description 字段会直接渲染为页面的 <meta name="description">，对 SEO 至关重要。

创建独立页面（作品集、服务页等）

除了博客文章，你还可以创建独立页面来展示项目案例和未来工作室的服务：

1
2
hugo new projects/_index.md
hugo new services/_index.md

每个 _index.md 会作为一个独立路由（如 /projects/），你可以在对应的 Markdown 中自由排版。

生产构建

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# 生成静态文件到 public/ 目录
hugo --minify

# 文件结构示例：
# public/
# ├── index.html
# ├── posts/
# │   └── hello-world/
# │       └── index.html
# └── ...

--minify 参数会压缩 HTML/CSS/JS，减小文件体积 30%-50%。public/ 目录里的所有文件就是你要部署到服务器上的内容。

GitHub Actions 自动部署

手动 scp 上传虽然可行，但每次写文章都要手动构建+上传，效率不高。利用 GitHub Actions 可以实现「推送代码即自动部署」。

工作流设计思路：在 GitHub Actions 中安装 Hugo → 拉取源码 → 执行构建 → 通过 scp 将 public/ 上传到云服务器的Nginx目录。

生成 SSH 密钥对

使用以下命令生成一个专门用于部署的密钥对，建议保存在 ~/.ssh/ 下：

`1`	`ssh-keygen -m PEM -t rsa -b 4096 -C "github-action-deploy" -f ~/.ssh/github-action-deploy`

这会产生两个文件：私钥 (github-action-deploy) 和公钥 (github-action-deploy.pub)。注意：请不要设置密码短语，留空即可。

创建deploy用户

1
2
3
# 创建用户（如果尚未存在）
sudo adduser deploy --disabled-password
sudo mkdir -p /home/deploy/.ssh

配置Nginx目录权限：

1
2
sudo chown -R deploy:www-data /var/www/html
sudo chmod -R 755 /var/www/html

赋予 sudo 权限：在服务器上运行 sudo visudo，在文件末尾添加以下内容，允许 deploy 用户无密码执行 systemctl reload nginx命令：

1
deploy ALL=(ALL) NOPASSWD: /usr/bin/systemctl reload nginx

配置服务器授权

将刚刚生成的公钥内容添加到deploy用户的授权文件中，并设置正确的权限：

1
2
3
4
5
cat ~/.ssh/github-action-deploy.pub  | sudo tee -a /home/deploy/.ssh/authorized_keys
# 修正权限
sudo chown -R deploy:deploy /home/deploy/.ssh
sudo chmod 700 /home/deploy/.ssh
sudo chmod 600 /home/deploy/.ssh/authorized_keys

配置 GitHub Secrets（在 GitHub 网页端操作）

进入GitHub仓库页面，依次点击 Settings ➔ Secrets and variables ➔ Actions，然后点击 New repository secret，创建四个 Secrets：

SERVER_IP: 你的阿里云服务器公网 IP 地址。
SERVER_USER: 登录服务器的用户名（刚刚创建的用户 deploy）。
SSH_PRIVATE_KEY: 私钥文件的内容~/.ssh/github-action-deploy，包括 -----BEGIN RSA PRIVATE KEY----- 和 -----END RSA PRIVATE KEY-----。
TARGET_DIR: 你的 Nginx HTML 目录在服务器上的绝对路径。比如，如果你已经配置好 Nginx，并且目录为 /var/www/html/main

创建核心文件：GitHub Actions 配置文件

在你的本地 Hugo 项目根目录下，创建文件 .github/workflows/deploy.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
58
59
60
61
62
63
64
65
66
67
68
name: Deploy Hugo Site to Aliyun ECS

on:
  push:
    branches:
      - main        # 监听 main 分支的推送，请替换为你的主分支名，如 master

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    steps:
      # 步骤一：拉取你的 Hugo 源代码
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: true   # 如果你的主题是 Git 子模块，需要这个
          fetch-depth: 1     # 只需要最新的代码

      # ---------- 安装 sass ----------
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '24'

      # 通过 npm 安装 sass-embedded，解决 CSS 编译问题
      - name: Install sass-embedded via npm
        run: |
          npm install -g sass-embedded
          NPM_BIN_DIR=$(npm prefix -g)/bin
          echo "NPM bin directory: $NPM_BIN_DIR"
          ls -la "$NPM_BIN_DIR"
          # 可执行文件是 'sass'，而非 'sass-embedded'
          sudo ln -sf "$NPM_BIN_DIR/sass" /usr/local/bin/sass
          sudo ln -sf "$NPM_BIN_DIR/sass" /usr/local/bin/dart-sass-embedded
          # 验证
          /usr/local/bin/dart-sass-embedded --version
      # ------------------------------

      # 步骤二：安装 Hugo
      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
          extended: true      # 如果需要 Sass/SCSS 支持

      # 步骤三：构建静态网站
      - name: Build
        run: hugo build --gc --minify --environment production --cleanDestinationDir -F -E

      # 步骤四：部署到阿里云服务器
      - name: Deploy to Aliyun ECS
        uses: easingthemes/ssh-deploy@main
        env:
          SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
          ARGS: "-azr --delete"     # rsync 参数：归档、压缩、递归、删除目标多余文件[reference:9]
          SOURCE: "public/"         # Hugo 将构建好的文件放在 public 目录
          REMOTE_HOST: ${{ secrets.SERVER_IP }}
          REMOTE_USER: ${{ secrets.SERVER_USER }}
          TARGET: ${{ secrets.TARGET_DIR }}
          # 以下两个脚本实现 Nginx 平滑重载
          SCRIPT_AFTER: |
            if sudo -n systemctl reload nginx 2>/dev/null; then
                echo "Nginx reloaded successfully (sudo mode)."
            else
                echo "Warning: Failed to reload nginx."
            fi
          SCRIPT_AFTER_REQUIRED: false

测试与运行

将 deploy.yml 和你的 Hugo 源码一起提交并推送到 GitHub。你可以通过 git push 命令或在 GitHub 网页端操作。推送后，前往你 GitHub 仓库的 Actions 标签页，就能看到工作流正在运行。如果一切顺利，第一个绿色的勾就出现了！

日常维护命令手册

场景	命令
新建文章	hugo new posts/文章标题.md
本地预览（含草稿）	hugo server -D
生产构建	hugo –minify
清理 public 目录后重建	rm -rf public/ && hugo –minify
更新主题子模块	git submodule update –remote –merge
检查 Hugo 版本	hugo version

好看主题推荐

主题列表：https://themes.gohugo.io/

FixIt：一个简洁、优雅且高效的个人网站主题。适合技术博客、个人站点。–推荐
PaperMod：以极快的速度和简洁的设计著称，功能丰富且维护积极。适合技术博客、个人站点。–推荐
doks：美观高性能技术文档网站。–推荐
docsy：一款非常简单的技术文档网站。
hextra：现代响应式，开箱即用的静态网站。
hugo-saasify-theme：使用TailwindCSS构建的SaaS服务网站

霞鹜文楷

其实我平时不怎么在意网页字体什么的，直到无意间看到了霞鹜文楷，真漂亮啊，而且免费开源可商用，于是就用上了。

字体来源：

屏幕阅读版比原版更适用屏幕显示，区别其实不是很大，但是看着更顺眼一些。

安装方法

FixIt 主题安装霞鹜文楷字体。在 FixIt 主题的说明文档中其实也描述了，直接加一个全局覆盖 css 就可以。以下字体样式均在 assets/scss/custom.scss 中定义。自定义全局字体为霞鹜文楷屏幕阅读版，同时还有代码字体:

1
2
@import url('https://cdn.jsdelivr.net/npm/lxgw-wenkai-screen-web/style.css?display=swap');
@import url('https://cdn.jsdelivr.net/npm/@fontsource/fira-mono@5.2.7/index.min.css');

在 assets/scss/override.scss 中定义字体覆盖变量：

1
2
3
4
@forward "variables" with (
  $global-font-family: ('LXGW WenKai Screen', 'PingFang SC', 'Microsoft YaHei', serif),
  $code-font-family: ('Fira Mono', 'JetBrains Mono', monospace),
);

参考

Hugo 官方文档：gohugo.io/documentation
Hugo 主题市场：themes.gohugo.io（300+ 免费主题）
GitHub Pages 免费托管：gohugo.io/host-on-github-pages