Hugo 静态建站笔记

作为这个网站的第一篇文章，我先来介绍下该网站使用的技术吧。该网站使用的是 Hugo + PaperMod + Nginx + Ubuntu，这样的组合。我的考虑是纯静态网站对服务器的性能要求不高，管理起来也非常方便，只要安装管理 Nginx 就可以了；本地写好的博客直接同步到服务器的 Nginx 网页目录即可。

Hugo + PaperMod

Hugo 我用的是官方打包好的二进制文件，下载下来后配置下环境变量就可以直接使用了。版本是 extended 版本，如：hugo_extended_0.155.3_windows-amd64。

安装 PaperMod 主题

主题的安装与更新推荐使用 git submodule（便于后续升级）：

# 1. 创建新站点（若尚未创建）
hugo new site myblog
cd myblog

# 2. 初始化 Git 仓库（必须）
git init

# 3. 添加 PaperMod 为子模块
git submodule add https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

# 4. 复制示例配置（可选但强烈建议）
copy themes/PaperMod/exampleSite/config.yml config.yml
# 或改用 TOML 格式（本文以 TOML 为主）：
# copy themes/PaperMod/exampleSite/config.toml config.toml

# 5. 启动本地预览
hugo server -D

升级 PaperMod 主题

使用 git submodule 升级非常简单：

# 进入站点根目录
cd myblog

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

# 提交更新记录（可选）
git add themes/PaperMod
git commit -m "chore: update PaperMod theme"

配置

baseURL: "https://xiaotupo.com"
languageCode: "zh-CN"
title: "小土坡 - 分享知识的地方..."
theme: "PaperMod"
disableThemeToggle: true # 显示主题修好按钮

# 设置新建文章的 Front Matter 格式为 YAML
frontmatter:
  posts:
    format: "yaml"

taxonomies:
  tag: "tags"
  category: "categories"

# PaperMod 主题配置
params:
  author: "小土坡"
  email: "xiaotupo@163.com" #
  defaultTheme: "auto" # 配置默认主题色，可选：light/dark/auto
  description: "小土坡是一个分享知识的网站，这里提供了一些关于电子硬件、电路仿真与实验、嵌入式以及物联网、3D打印等主流科技技术相关的内容。"
  enableSearch: true
  showReadingTime: true
  hideBreadcrumbs: true # 隐藏面包屑导航
  ShowShareButtons: true # 显示分享按钮
  TocOpen: true # 默认打开 Toc
  ShowPostNavLinks: true # 显示上一篇/下一篇链接
  ShowCodeCopyButtons: true # 显示代码复制按钮

  homeInfoParams:
    Title: "Hi there 👋"
    Content: "欢迎来到我的博客，我会分享一些有意思的内容给大家！"

  # 社交图标配置
  socialIcons:
    - name: "github"
      url: "https://github.com/xiaotupo-com"
    - name: "bilibili"
      url: "https://space.bilibili.com/334715750"
    - name: "email"
      url: "mailto:xiaotupo@163.com"
    - name: "rss"
      url: "/index.xml"

  profileMode:
    enabled: false
    title: "小土坡 - 分享知识的地方！"
    subtitle: "掌握知识掌握力量👋"
    imageUrl: "/images/avatar.png"
    imageTitle: "小土坡 - 分享知识的地方！"
    imageWidth: 120
    imageHeight: 120

  assets:
    # disableHLJS = true
    # disableFingerprinting = true
    favicon: "/images/favicon.ico"
    favicon96x96: "/images/favicon-96x96.png"
    apple_touch_icon: "/images/apple-touch-icon.png"
    safari_pinned_tab: "/images/safari-pinned-tab.svg"

  fuseOpts:
    isCaseSensitive: false
    shouldSort: true
    location: 0
    distance: 1000
    threshold: 0.4
    minMatchCharLength: 0
    # limit: 10 # refer: https://www.fusejs.io/api/methods.html#search
    keys: ["title", "permalink", "summary", "content"]

menu:
  main:
    - name: "Home"
      url: "/"
      weight: 1
    - name: "Archive"
      url: "/archives/"
      weight: 2
    - name: "Search"
      url: "/search/"
      weight: 3
    - name: "Tags"
      url: "/tags/"
      weight: 4
    - name: "Category"
      url: "/categories/"
      weight: 5
    - name: "Links"
      url: "/links"
      weight: 6
    - name: "About"
      url: "/about"
      weight: 7

# Search Page
outputs:
  home:
    - HTML
    - RSS
    - JSON # necessary for search

安装 Nginx 并配置 SSH 证书

下面列出了安装 Nginx 用到的一些命令：

# 1. 安装 nginx
sudo apt update
sudo apt install -y nginx

# 2. 启动并设置开机自启
sudo systemctl enable --now nginx

# 3. 验证是否成功
curl http://localhost

配置 Nginx 站点

创建配置文件：

sudo nano /etc/nginx/sites-available/xiaotupo.com

粘贴一下内容：

server {
    listen 80;
    server_name xiaotupo.com www.xiaotupo.com;  # ← 改成你的域名，或写服务器公网IP

    root /home/username/xiaotupo.com;
    index index.html index.htm;

    location / {
        try_files $uri $uri/ =404;
    }

    # 可选：隐藏 .git 等敏感目录
    location ~ /\. {
        deny all;
    }
}

启用站点：

sudo ln -s /etc/nginx/sites-available/xiaotupo.com /etc/nginx/sites-enabled/

测试配置&重载:

sudo nginx -t
sudo systemctl reload nginx

启用 HTTPS（Let’s Encrypt）

在阿里云轻量服务器（Ubuntu）上为 Nginx 配置 HTTPS（即安装 SSL/TLS 证书），最推荐的方式是使用 Let’s Encrypt 免费证书 + Certbot 自动化工具。整个过程免费、自动化、且被广泛信任。

安装 Certbot 并申请证书（全自动）

第一步：安装 Certbot 和 Nginx 插件

sudo apt update
sudo apt install -y certbot python3-certbot-nginx

第 2 步：运行 Certbot（自动配置 Nginx + 申请证书）

sudo certbot --nginx -d xiaotupo.com -d www.xiaotupo.com

替换 xiaotupo.com 为你的实际域名（可多个 -d）

配置站点目录权限

我设置的站点目录为我的用户目录下的 xiaotupo.com，如：/home/usarname/xiaotupo.com，不过这个目录默认 Nginx 是无权访问的，必须配置权限才能访问，否则当你访问时会显示 404。

# 1. 修复 home 目录权限
chmod 755 /home/username

# 2. 确保网站目录可读
chmod -R 755 /home/username/xiaotupo.com

# 3. 重载 Nginx
sudo nginx -t && sudo systemctl reload nginx

经过这样配置之后就可以正常访问了，当然我们还要执行一下命令把 hugo 的 public 目录中的站点内容上传到我们的 /home/username/xiaotupo.com，上传命令如下：

PS D:\xiaotupo.com> scp -r .\public\* usarname@xiaotupo.com:/home/username/xiaotupo.com

总结

经过这样的配置网站也算可以正常访问了，以后遇到问题再说。

如果您有什么问题可以通过本站提供的邮箱链接联系我。