Hugo Academic主题加载报错：缺失blox-bootstrap/v5模块

以下是针对该问题的分步解决方案：

• 确认Hugo版本要求
  Hugo Blox Builder（原Hugo Academic）必须使用Hugo Extended扩展版，标准版Hugo不支持模块依赖管理。执行以下命令检查版本：

  hugo version
  

  输出中需包含extended字样，若没有则前往Hugo官网下载对应系统的扩展版替换。

• 清理模块缓存并重新拉取依赖
  本地模块缓存损坏可能导致依赖找不到，按系统执行以下操作：

  1. 删除本地模块缓存：
     • Windows：

       rd /s /q .hugo\modules
       go clean -modcache
       

     • Ubuntu：

       rm -rf .hugo/modules
       go clean -modcache
       

  2. 在站点根目录重新初始化并拉取模块：

     hugo mod init your-site-slug  # 若站点未初始化模块则执行此步
     hugo mod get -u github.com/HugoBlox/hugo-blox-builder/modules/blox-bootstrap/v5
     hugo mod tidy
     

     hugo mod tidy会自动整理go.mod文件，移除无效依赖并拉取缺失的必需模块。

• 检查主题配置是否正确
  确保站点配置文件（config.toml/config.yaml）使用模块方式指定主题，而非本地克隆的文件夹：

  • TOML格式：

    theme = ["github.com/HugoBlox/hugo-blox-builder"]
    

  • YAML格式：

    theme:
      - github.com/HugoBlox/hugo-blox-builder
    

  模块方式会自动拉取主题所需的子模块，避免手动克隆遗漏依赖。

• 排查网络访问问题
  若网络无法访问GitHub，可临时设置Go代理加速模块拉取：

  • Windows：

    set GOPROXY=https://goproxy.io
    

  • Ubuntu：

    export GOPROXY=https://goproxy.io
    

  设置完成后重新执行模块拉取命令。

内容的提问来源于stack exchange，提问作者ashoki