Wordpress2Hugo

把个人站点从wordpress 迁移到了hugo。本文主要记录hugo使用过程中的一些配置信息

修改even favicon 的图标

可以将之前做好的512x512图片传到这个工具网站favivon，自动生成多个尺度的icon 照片, 然后下载下来，解压到主题的目录 themes/even/static/.

使用HugoBox

Setting Website icon

Save your icon as a square 512x512 pixel image named icon.png and place the image in your root assets/media/ folder, creating the folders if they don’t already exist.

Windows 本地环境搭建（2026-09 更新）

以下步骤在 Windows + PowerShell（Warp 终端同样适用）下验证通过。

为什么必须是 Hugo 0.126.3 extended

和线上保持一致：netlify.toml 里固定了 HUGO_VERSION = "0.126.3"，本地用同一版本，预览结果才和上线一致；
必须是 extended 版：主题模块 blox-tailwind 要求 Min 0.126.0 extended，主题里的图片裁剪（.Fit、.Fill）也只有 extended 版支持。普通版会报 this feature is not available in your current Hugo version；
不能用太新的版本：Hugo 0.145 之后陆续移除了当前主题还在用的写法，例如 front matter 里的 _build、配置里的 markup.goldmark.renderHooks.link.enableDefault。用 0.166 构建会直接报 ERROR deprecated ... subsequently removed，整站无法生成。要升级 Hugo，需要先升级 Hugo Blox 主题，并同步修改 Netlify 的版本。

为什么还需要 Go 和国内代理

站点通过 go.mod 引用 Hugo Blox 主题模块，Hugo 首次构建时会调用 go mod download 下载主题，所以本机需要 Go。默认的 proxy.golang.org 在国内很慢，容易卡住十几分钟，换成 goproxy.cn 后十几秒就能下载完成。

安装步骤

下载 Hugo 0.126.3 extended，解压到固定目录（这里用 C:\Users\xwell\tools\hugo_extended）：

$dir = "C:\Users\xwell\tools\hugo_extended"
New-Item -ItemType Directory -Force $dir | Out-Null
Invoke-WebRequest -UseBasicParsing "https://github.com/gohugoio/hugo/releases/download/v0.126.3/hugo_extended_0.126.3_windows-amd64.zip" -OutFile "$dir\hugo.zip"
Expand-Archive -Force "$dir\hugo.zip" $dir
& "$dir\hugo.exe" version   # 输出应包含 v0.126.3 和 +extended

GitHub 下载较慢时需要耐心等待。也可以用 winget install Hugo.Hugo.Extended --version 0.126.3 安装，但会和已装的其他版本冲突。

用 conda 新建一个独立环境安装 Go，不影响 base 环境：
```
$env:CONDA_PKGS_DIRS = "C:\cpk"
conda create -n hugo --override-channels -c conda-forge go -y
```
- --override-channels -c conda-forge：只用 conda-forge 频道，避免默认的 Anaconda 频道要求先接受服务条款；
- CONDA_PKGS_DIRS 设成短路径：部分包内文件路径很长，放在默认缓存目录解压时会超过 Windows 的路径长度限制；
- 不要装进 base：conda 会顺带把 base 里的 Python、openssl 换成 conda-forge 的版本。

设置 Go 模块的国内代理（只需运行一次，会永久保存）：

$env:GOROOT = "C:\Users\xwell\miniconda3\envs\hugo\go"
$env:PATH = "C:\Users\xwell\miniconda3\envs\hugo\bin;$env:PATH"
go env -w GOPROXY=https://goproxy.cn,direct

写入用户环境变量，之后新开的终端（包括 Warp）都会自动生效：

$goBin = "C:\Users\xwell\miniconda3\envs\hugo\bin"; $hugoDir = "C:\Users\xwell\tools\hugo_extended"
# 复制一份 hugo126.exe，以后即使装了其他版本的 hugo，也能明确调用 0.126.3
Copy-Item "$hugoDir\hugo.exe" "$hugoDir\hugo126.exe" -Force
[Environment]::SetEnvironmentVariable("GOROOT", "C:\Users\xwell\miniconda3\envs\hugo\go", "User")
[Environment]::SetEnvironmentVariable("GOPROXY", "https://goproxy.cn,direct", "User")
# Hugo 不读 GOPROXY，而是用自己的 module.proxy（默认 direct，直连 GitHub），要单独设置
[Environment]::SetEnvironmentVariable("HUGO_MODULE_PROXY", "https://goproxy.cn,direct", "User")
# 把 Go 和 Hugo 目录追加到用户 PATH 末尾
$key = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey("Environment", $true)
$raw = $key.GetValue("Path", "", [Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames)
$parts = @($raw -split ";" | Where-Object { $_ -ne "" })
foreach ($d in @($goBin, $hugoDir)) { if ($parts -notcontains $d) { $parts += $d } }
$key.SetValue("Path", ($parts -join ";"), [Microsoft.Win32.RegistryValueKind]::ExpandString); $key.Close()

conda 里的 Go 必须设置 GOROOT，否则会报 'go' binary is trimmed and GOROOT is not set；
没设 HUGO_MODULE_PROXY 时，hugo server 会报 git ls-remote ... unable to access 'https://github.com/HugoBlox/hugo-blox-builder/': Recv failure: Connection was reset。只设 GOPROXY 不够，因为 Hugo 会用自己的代理配置覆盖它。不写进 config/_default/module.yaml，是为了不影响 Netlify 上的构建；
没有用 PowerShell 的 $PROFILE，因为 Windows PowerShell 默认执行策略会拒绝加载配置脚本，用户环境变量不受这个限制；
写入后要完全退出并重新打开 Warp，新的环境变量才会生效。

日常使用

重开终端后，进入项目目录运行：

cd C:\Users\xwell\projects\blog_hugo_blox
hugo126 server -D

然后在浏览器打开 http://localhost:1313/ 预览，修改文章后页面会自动刷新。

目前系统里只保留了 0.126.3（winget 装的 0.166 已用 winget uninstall --id Hugo.Hugo.Extended 卸载，并从用户 PATH 里删除了残留条目），所以 hugo 和 hugo126 都能用；以后如果再装新版，就用 hugo126；
只想检查能否构建、不启动服务时，可以运行 hugo126 --gc。

Hugo 常用命令

创建新的文章 hugo new posts/new_blog.md

生成网页预览，可使用Chrome 无痕模式查看 http://localhost:1313/

# 使用hugo box  & netlify, 预览后，直接推送即可
hugo && \
npm_config_yes=true npx pagefind --site "public" --output-subdir ../static/pagefind && \
hugo server -D

# 单独使用hugo 配置
hugo server

使用 hugo 生成静态网页，然后将public 文件夹内容推到网站地址
```
hugo

cp -r public/* SITE_PATH
```

hugo box 配置

To hide the automatic last modified date, change HUGO_ENABLEGITINFO to "false" in netlify.toml