Hugo Modules 主题迁移实践

张小鱼2026-02-05约 5 分钟

警告

本文最后更新于 2026-02-05，文中内容可能已过时。

默认已部署，如尚未部署详见《Hugo 博客自动化部署指南》。

Git Submodule 将主题代码嵌入仓库，更新需手动操作，而 Hugo Modules 采用独立模块管理，主题版本可控、更新便捷、项目结构更清晰。¹

本文介绍从 Git Submodule 迁移至 Hugo Modules，包括使用临时分支隔离实验，以及配置的维护。

准备工作

在开始之前，准备以下工具：

Git：用于代码版本管理和拉取远程仓库。
Go：Hugo Modules 依赖 Go 环境。
‌VS Code（可选）：用于可视化操作和调试，并安装 Git Graph 插件。

工具的安装与配置详见《Win11 开发环境安装与配置》。

创建分支

运行以下命令，创建用于实验的分支（hugo-mod-migration）：

Bash
1
2
3
git status
git checkout -b hugo-mod-migration
git branch

VS Code 可视化操作：

打开 源代码管理 面板，确认没有未提交的更改；点击 ··· >分支>创建分支，输入 hugo-mod-migration 并确认，确保当前分支为 hugo-mod-migration，如未切换可手动切换或重启终端。

执行迁移

运行以下命令，移除现有的主题 Submodule 及相关配置（themes/FixIt/ 会被删除）：

Bash
1
2
3
git submodule deinit -f themes/FixIt
git rm -rf themes/FixIt
rm -rf .git/modules/themes/FixIt

修改站点配置，删除或注释掉原主题配置：

TOMLhugo.toml
1
theme = "FixIt"

运行以下命令，初始化 Hugo Modules，并生成 go.mod 文件：

Bash
1
hugo mod init github.com/你的用户名/你的仓库名

修改站点配置，在末尾添加 Hugo Modules 配置：

TOMLhugo.toml
1
2
3
4
[module]
[[module.imports]]
path = "github.com/hugo-fixit/FixIt"
# version = "v0.4.2"   # 可指定主题版本

运行以下命令，获取主题模块：

Bash
1
hugo mod get

运行以下命令，推送至远程仓库，以便创建安全存档点方便回退：

Bash
1
2
3
git add -A
git commit -m "启用 Modules"
git push

VS Code 可视化操作：

打开 源代码管理（Ctrl+Shift+G）面板，输入提交说明，点击 提交>同步更改。

本地验证

运行以下任一命令，启动本地服务器，检查网站样式、功能和内容是否正常：

Bash
1
2
3
4
5
6
7
8
# 日常写作：快速预览文章（快速渲染模式）
hugo server -D

# 深度调试：修改主题或样式，确保更改完整生效
hugo server -D --disableFastRender

# 部署检查：模拟线上环境，测试评论、CDN 等功能
hugo server -D -e production --disableFastRender

确认无误后，运行以下命令，将实验分支 hugo-mod-migration 合并到 main 分支并推送：

Bash
1
2
3
git checkout main
git merge hugo-mod-migration
git push origin main

VS Code 可视化操作：

打开 Git Graph，右键点击 main 分支，点击 Checkout Branch；在 hugo-mod-migration 分支上右键点击 Merge into current branch；在 源代码管理 面板输入提交说明，提交更改，并点击 同步更改。

故障回退

如果本地预览有问题，可运行以下命令，回退到迁移前的状态：

Bash
1
2
3
4
5
6
7
8
# 确认当前分支
git branch --show-current

# 查看提交历史，找到迁移前的 commit hash
git log --oneline

# 将 <commit-hash> 替换为实际值后执行
git reset --hard <commit-hash>

VS Code 可视化操作：

打开 源代码管理 面板，点击 Git Graph 图标，找到迁移前的提交（如 main 分支的最新提交），右键该提交点击 Reset current branch to this commit…>Hard 并确认，分支将恢复到迁移前的状态。

回退后，可重新执行执行迁移阶段的操作。

后续更新

至此，迁移完成。此后，站点配置和主题的个性化配置都写在根目录的 hugo.toml 中，只写要覆盖的键，其余自动继承主题默认值，无需再复制主题文件。

此外，在 FixIt 主题仓库中点击 Watch>Custom>Releases 订阅更新通知。当有更新时，可选择脚本更新或命令更新。如需更稳妥，也可在临时分支（如 update-fixit）中测试无误后合并到主分支。

创建以下文件（保存为 ANSI 编码）：

Batchfileupdate-fixit.bat
 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
@echo off
setlocal enabledelayedexpansion

REM ===== 在这里修改 FixIt 主题版本 =====
set FIXIT_VERSION=v0.4.3
REM ===================================

echo 当前 FixIt 版本: %FIXIT_VERSION%
echo 注意: 以下操作将清除所有模块缓存，并删除 _vendor 目录（如果存在）。
set /p confirm="是否继续清理并重装？ (y/n): "
if /i not "%confirm%"=="y" (
    echo 操作取消。
    exit /b
)

echo [1/5] 清理 hugo 模块缓存...
hugo mod clean

echo [2/5] 清理 go 模块全局缓存...
go clean -modcache

echo [3/5] 删除 _vendor 目录...
if exist _vendor (
    rmdir /s /q _vendor
    echo 已删除 _vendor。
) else (
    echo _vendor 不存在，跳过。
)

echo [4/5] 重新下载 FixIt %FIXIT_VERSION%...
hugo mod get github.com/hugo-fixit/FixIt@%FIXIT_VERSION%

echo [5/5] 清理 hugo 构建缓存...
hugo --gc

echo === 重置完成 ===
echo 现在可以运行 'hugo server' 检查代码块渲染是否正常。
echo 如果之后需要查看主题源码，可以执行 'hugo mod vendor' 重新生成 _vendor 目录。
pause

设置版本：修改变量 FIXIT_VERSION 指定目标版本，无需在 hugo.toml 中指定主题版本。
用户确认：提示将清除缓存并删除 _vendor，需输入 y 确认。
清理缓存：执行 hugo mod clean 和 go clean -modcache。
删除目录：如果存在 _vendor 则删除。
下载主题：执行 hugo mod get 下载指定版本。
清理构建缓存：执行 hugo --gc。
完成提示：可运行 hugo server 测试，如需源码可执行 hugo mod vendor。

修改 hugo.toml 中的主题版本号（如 version = "v0.4.3"），然后运行以下命令：

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
# 修改 hugo.toml 中的版本号（如 version = "v0.4.3"）

# 清理缓存（确保全新下载）
rm -rf _vendor        # 删除 vendor 目录（如有）
hugo mod clean        # 清理 Hugo 模块缓存
go clean -modcache    # 清理 Go 全局模块缓存
hugo --gc             # 清理构建缓存（可选但推荐）

# 根据配置文件的版本更新主题
hugo mod get          # 拉取 hugo.toml 中指定的版本
hugo mod get -u       # 一键升级所有模块到最新兼容版本

# 将模块源码导出到 _vendor 目录，方便查阅（可选）
hugo mod vendor

# 本地预览与调试（三选一）
hugo server -D                      # 日常写作：快速预览文章和内容（默认快速渲染模式）
hugo server -D --disableFastRender  # 深度调试：修改主题/模板/全局样式时，确保所有更改完整生效
hugo server -D -e production --disableFastRender  # 部署检查：模拟线上环境，测试评论、CDN 等生产功能是否正常