教程 on IMX-博客

Hugo Theme IMX 主题配置指南

Tue, 07 Jul 2026 10:00:00 +0800

IMX 是一个通过 Hugo Module 使用的中文博客主题。它不需要放进 themes/ 目录，也不需要在配置里写 theme = "..."，站点通过 Go Module 引入主题，然后由 Hugo 在构建时合并主题模板、资源和默认配置。

这篇文章集中说明 如何把 IMX 主题配置清楚。第一次搭建站点，可先读 Hugo 与 IMX 入门指南；准备上线时再读 GitHub Pages 部署指南。如果你已经有一个 Hugo 站点，照着本文检查一遍，基本可以把首页、文章列表、关于页、评论、搜索、图片和部署流程都理顺。

一、配置文件放在哪里

站点的主配置文件一般是根目录下的 hugo.toml：

your-site/
├── content/
├── static/
├── go.mod
├── go.sum
└── hugo.toml

IMX 主题推荐把主要配置都写在 hugo.toml 里。除非站点规模很大，否则没有必要一开始就拆成多个配置文件。

一个可以工作的最小配置如下：

baseURL = 'https://example.com/'
defaultContentLanguage = 'zh-cn'
locale = 'zh-CN'
title = '我的博客'

[params]
 description = '站点描述'
 subtitle = '首页副标题'
 author = '你的名字'
 mainSections = ['posts']

[outputs]
 home = ['HTML', 'RSS', 'JSON']

[module]
 [[module.imports]]
 path = 'github.com/c-x-x/hugo-theme-imx'

这几项先不要省：

baseURL：站点最终访问地址，影响 canonical、RSS、Open Graph 图片地址。
title：站点标题，会出现在导航、首页、关于页和网页标题里。
[params]：主题参数区，IMX 的头像、Logo、默认图片、评论、社交链接都在这里配置。
[outputs].home：必须保留 JSON，站内搜索依赖首页生成的 index.json。
[module.imports]：主题通过 Hugo Module 引入，不能用传统 theme = "xxx"。

二、安装与更新主题

如果站点还没有 go.mod，先执行：

Hugo 博客搭建与 IMX 主题完全使用指南

Tue, 07 Jul 2026 10:00:00 +0800

这篇指南带你从空目录走到一个能本地预览的 IMX 博客。完成后，你会知道站点文件放在哪里、怎样写文章，以及修改后该检查什么。已有 Hugo 站点的读者可以直接看 IMX 主题配置指南；准备上线时再看 GitHub Pages 部署指南。

开始前需要什么

安装 Git、Go 和 Hugo Extended。IMX 通过 Hugo Module 加载，主题示例站给出的最低要求是 Hugo Extended 0.112.0 与 Go 1.20；新项目建议让本地与 CI 使用经过验证的相同版本。

hugo version
go version
git --version

确认 hugo version 的输出包含 extended。建站和写作不需要安装 Node.js；主题仓库里的前端测试依赖只用于维护主题。

1. 创建站点并安装主题

以下以 my-blog 为目录名，your-name 为 GitHub 用户名。请替换这两个占位符。

hugo new site my-blog
cd my-blog
git init
hugo mod init github.com/your-name/my-blog

在根目录的 hugo.toml 写入最小配置：

baseURL = 'https://your-name.github.io/'
defaultContentLanguage = 'zh-cn'
locale = 'zh-CN'
title = '我的博客'

[params]
 description = '记录技术与生活'
 subtitle = '把值得记住的事写下来'
 author = '你的名字'
 mainSections = ['posts']

[outputs]
 home = ['HTML', 'RSS', 'JSON']

[module]
 [module.hugoVersion]
 extended = true
 min = '0.112.0'
 [[module.imports]]
 path = 'github.com/c-x-x/hugo-theme-imx'

安装一个明确的主题版本。例如，本站当前使用 v1.5.6：

Hugo 博客部署到 GitHub Pages 完全指南

Sat, 13 Jun 2026 00:00:00 +0000

本篇从一个已经能运行 hugo --minify 的博客开始。还没有站点，可以先完成 Hugo 与 IMX 入门指南；需要调整主题细节，参见 IMX 主题配置指南。

1. 确认仓库与站点地址

GitHub Pages 有两种常见地址，baseURL 必须与最终公开地址对应：

类型	仓库名	`baseURL`
用户站点	`your-name.github.io`	`https://your-name.github.io/`
项目站点	`my-blog`	`https://your-name.github.io/my-blog/`

本站是用户站点，但使用自定义域名，所以 hugo.toml 中写的是 baseURL = 'https://blog.cxx.pub/'。项目站点尤其要保留末尾的仓库路径；否则页面链接、图片或样式可能指向错误位置。

在发布前检查本地环境与构建：

hugo version
go version
hugo --minify

IMX 需要 Hugo Extended 和 Go。Hugo Module 的依赖应记录在 go.mod、go.sum，并连同 hugo.toml 一起提交。将 /public/、/resources/_gen/、/.hugo_build.lock 放入 .gitignore；Pages 工作流会构建 public/，不必把它提交进源码仓库。

2. 创建 GitHub 仓库

在 GitHub 新建仓库。若希望使用根地址 https://your-name.github.io/，仓库名必须是 your-name.github.io；若使用项目地址，可以取普通仓库名。已有本地 Git 仓库时，建议创建空仓库，避免首次推送出现不必要的历史合并。

然后在仓库 Settings → Pages → Build and deployment → Source 选择 GitHub Actions。本文的工作流会上传构建产物并部署，不使用“从分支发布”的方式。