Hugo静态博客搭建到服务器

CBBA 收录于 搭建
 约 500 字 预计阅读 3 分钟 

准备工作

服务器版本：Ubuntu20.04

Hugo官方文档中提到，尽管在某些情况下不是必需的，但在使用Hugo时常常需要使用到 Git、Go和Dart Sass。

安装Git

标准安装方式：

1
2

sudo apt update
sudo apt install git

安装后验证是否成功安装：

1

git --version

安装Snap

这里需要安装snapd，命令如下：

1
2

sudo apt update
sudo apt install snapd

安装后可以通过查看版本号的操作来判断是否成功安装，命令如下：

1

snap version

我这里输出：

1
2
3
4
5

snap    2.67.1+20.04
snapd   2.67.1+20.04
series  16
ubuntu  20.04
kernel  5.4.0-212-generic

安装时安装snap存在的问题

最开始时我是直接安装的sanp，但是安装后使用snap version查看版本号时会报错，提示我需要安装snapd，以下是网上找到的解答：

  • snap 是一个命令行工具（客户端），用于与 snapd 守护进程交互。
  • snapd 是实际的 Snap 服务（守护进程），负责管理 Snap 包的安装和运行。
  • 在较新的 Ubuntu/Debian 版本中，snap 命令本身是 snapd 的一部分，但 apt 仓库中的 snap 包可能只是一个过渡性空包（metapackage），实际依赖 snapd。

安装Go

上面已经安装过snap了，通过snap来安装go更简单，安装命令如下：

1

sudo snap install go --classic

安装后验证是否成功安装：

1

/snap/bin/go version

我这里输出：

1

go version go1.24.2 linux/amd64

安装Hugo

方法一：通过snap安装Hugo（废弃）

使用以下命令安装Hugo的extended版本：

1

sudo snap install hugo

我这里安装后使用hugo version输出的版本为：

1

hugo v0.147.6-0a5fd8ebb8e2ca798515e8c564c14e32db3b4127+extended linux/amd64 BuildDate=2025-05-27T11:17:16Z VendorInfo=snap:0.147.6

不过我这里使用snap安装后有一个小问题，就是不识别hugo这个命令，输入hugo version后会报错：

1

bash: /usr/bin/hugo: No such file or directory

原因是Snap 安装的 Hugo 可执行文件没有被正确链接到系统路径中，Snap 将软件安装在 /snap/bin/ 目录下，系统默认的 /usr/bin/ 就不识别这个命令，经过实测，临时使用完整路径去调用hugo是没问题的，会正常输出版本号，完整命令如下：

1

/snap/bin/hugo version

但是这只是临时的解决方案，想正常使用hugo还是需要处理一下的，不如apt直接安装就能用来的方便，所以我选择卸载掉这个，重新用apt安装。

方法二：通过apt安装Hugo（废弃）

需要注意的是，默认指令安装的Hugo版本比较旧

我这里使用默认的指令sudo apt install hugo，安装后的版本为：

1

Hugo Static Site Generator v0.68.3/extended linux/amd64 BuildDate: 2020-03-25T06:15:45Z

卸载Hugo

我这里用snap安装后出了点问题，卸载指令如下。

通过apt安装的Hugo卸载指令（官方仓库版本） 

1
2

sudo apt remove --purge hugo
sudo apt autoremove  # 清理依赖

通过 Snap 安装的 Hugo卸载指令 

1

sudo snap remove hugo

方法三：从 Release 页面手动安装

我想下载最新版本，所以直接到GitHub里找到最新版本的包，我这里最新的版本是0.147.8，安装命令如下：

1
2
3
4
5
6
7
8

# 根据官网最新版本选择下载链接（示例：hugo_extended_0.147.8_linux-amd64.deb）
wget https://github.com/gohugoio/hugo/releases/download/v0.147.8/hugo_extended_0.147.8_linux-amd64.deb

# 安装
sudo dpkg -i hugo_extended_0.147.8_linux-amd64.deb

# 检查
hugo version

安装后使用hugo version来验证，我这里还是报bash: /usr/bin/hugo: No such file or directory，看来想偷懒是偷不成了，还是要排查一下问题

问题排查

  1. 首先使用 which hugo命令排查是否安装成功，我这里输出/usr/local/bin/hugo说明安装成功。

  2. 然后直接调用完整路径测试是否能正常运行：

    1

    /usr/local/bin/hugo version

    正常输出hugo版本hugo v0.147.8-10da2bd765d227761641f94d713d094e88b920ae+extended linux/amd64 BuildDate=2025-06-07T12:59:52Z VendorInfo=gohugoio

    那么就可以确定文件是没有问题的了，然后继续排查环境变量是否有问题

  3. 检查当前 $PATH 是否包含 /usr/local/bin，命令如下：

    1

    echo $PATH

    我这里输出：/home/xh/.vscode-server/cli/servers/Stable-258e40fedc6cb8edf399a463ce3a9d32e7e1f6f3/server/bin/remote-cli:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin，其中是包含 /usr/local/bin的，所以也不是环境变量的问题，那么继续排查是不是Shell缓存有问题

  4. 考虑到可能 Shell 缓存了旧路径，所以使用hash -r清除Shell命令缓存，然后再次尝试hugo version，这次正常输出版本号了

新建Hugo站点

创建博客目录

我这里将博客数据都存储到~/myblog目录了

1
2
3

cd ~
mkdir myblog
cd myblog

初始化 Hugo 站点

1

hugo new site blog

此时会在 ~/myblog/blog 下自动创建一系列文件夹和配置文件，常见目录结构包括：

1
2
3
4
5

├── archetypes
├── content
├── layouts
├── static
└── config.toml (或 config.yaml / config.json)

初始化 Git 仓库（可选） 如果你想用 Git 管理整个 Hugo 站点，可以在 blog 目录下执行：

1
2
3
4

cd blog
git init
git add .
git commit -m "Initial commit"

我这里是准备备份一份数据，使用git比较方便

配置主题

Hugo 官方主题库： themes.gohugo.io

我这里使用stack主题，该主题文档链接：开始使用 | Hugo 主题 Stack

修改主题后记得修改配置文件，或者按主题教程中说的将他提供的配置文件复制过来也行，我这里自己修改的 config.toml文件：

1
2
3
4

baseURL = "http://060010.xyz/"
languageCode = "zh-cn"
title = "My New Hugo Site"
theme = "hugo-theme-stack"

注意theme这个值要对应主题文件夹的名字

创建文章

新建文章

在 blog 目录下：

1

hugo new posts/hello-world.md

默认会在 content/posts 目录生成 hello-world.md 文件，可打开编辑

注意：将 draft 设置为 false 可以在发布时被包含。

本地预览

1

hugo server -D

  • -D 选项表示包含 draft 草稿文章。

  • 启动后会显示一个本地访问地址，如 http://localhost:1313/。

  • 如果你希望外网通过 ECS 的 IP 地址访问预览，可以使用 --bind 0.0.0.0 --baseURL http://<服务器IP>:1313/ 启动，让其监听所有网卡。 例如：

    1

    hugo server -D --bind 0.0.0.0 --baseURL http://<服务器IP>:1313/

生成静态文件

确认内容没问题后，生成静态文件即可：

1

hugo

执行成功后，会在 blog/public 目录下生成所有静态页面文件。你可以把 public 目录下的文件发布到任何静态 Web 服务器（Nginx、Apache 等）上即可对外访问。

关于运行hugo server渲染正确而本地打开public文件渲染错误的问题

生成的public文件渲染错误，但是运行hugo server的渲染却没问题

  • 怀疑是hugo.yaml配置文件有问题，目前有两个思路：
    • 抄新发现的这个教程的配置文件
    • 删配置文件上的内容，直到没问题

经测试，上面的两个思路都没有解决问题，最后在这里发现了相同的问题：Files in public folder not rendering correctly. But running locally by “hugo serve” is fine. · Issue #125 · matcornic/hugo-theme-learn

PixPin_2025-07-09_21-51-18

实测将以下两行添加到hugo.toml文件中就解决问题了，至于baseURL = "//example.org"这行怎么填都没问题（仅限本地测试，配置到服务器中还是要填正确的）

1
2
3
4

# 是否使用相对路径
relativeURLs = true
# 是否使用丑陋的URL
uglyURLs = true

relativeURLs = true 的作用：

  • 默认情况下，Hugo 生成的资源路径（CSS/JS/图片等）是 绝对路径，基于 baseURL（如 /css/style.css）。

  • 当你直接双击打开本地的 index.html 文件时，浏览器会尝试从 file:// 协议加载这些绝对路径，导致路径解析失败（因为本地没有域名根目录）。

  • 改用relativeURLs = true后，强制 Hugo 生成 相对路径（如 css/style.css 而非 /css/style.css），所以静态文件在本地打开就是渲染正确的了。

uglyURLs = true 的作用

  • Hugo 默认生成“美观”的 URL（如 /about/ 对应 /about/index.html）。
  • 某些本地文件系统或旧版服务器对 index.html 的支持不完善，可能导致路径解析错误，改用uglyURLs = true 后直接生成“丑陋”路径，本地打开静态文件时，链接跳转更可靠。

通过1panel配置访问

  1. 先创建一个静态网站，然后进入到该网站对应的路径中，例如我这里网站是cbba-top，对应的路径是/opt/1panel/www/sites/cbba-top/index

  2. 在index文件夹中创建hugo站点hugo new site blog-FixIt-dev，然后按需调整主题、文章、配置文件等，最后生成静态文件

  3. 生成静态文件后，通过1panel配置网站默认访问的路径。

    • 进入网站页面，找到已经创建好的网站，点击配置

      PixPin_2025-07-10_11-14-07

    • 「网站目录」>「运行目录」>「保存并重载」，运行目录选hugo生成的public文件夹

      PixPin_2025-07-10_11-16-17

然后就可以正常访问hugo博客了

更新于 2025-07-10 
阅读原始文档
LINE Myspace
博客
返回 | 主页
0%