Github Pages加载Hugo主题时CSS、图片丢失及跳转失效问题求助

1 baseURL 配置校验 #

• 打开站点根目录的配置文件（config.toml/config.yaml/config.json），确认baseURL参数值和你实际的Github Pages访问地址完全一致，末尾必须带斜杠。如果你的仓库名不是<用户名>.github.io，格式应为https://<用户名>.github.io/<仓库名>/，遗漏仓库名前缀或者斜杠会导致所有资源路径拼接错误。

2 Github Actions 工作流校验 #

• 检查checkout步骤是否开启了子模块拉取：你使用submodule引入主题，工作流的拉取代码步骤必须配置submodules: true，否则主题文件不会被完整拉取，构建产物会缺失样式文件，参考配置：

- name: Checkout
  uses: actions/checkout@v4
  with:
    submodules: true
    fetch-depth: 0

• 检查Hugo安装步骤是否启用了extended版本：该Bootstrap主题依赖Hugo extended版本处理SCSS资源，未开启会导致样式构建失败，参考配置：

- name: Setup Hugo
  uses: peaceiris/actions-hugo@v2
  with:
    hugo-version: 'latest'
    extended: true

• 检查Hugo构建命令是否指定了正确的参数，建议添加--gc --minify参数，若baseURL未在配置文件中声明，可在构建命令中通过--baseURL "你的站点地址"指定。

3 gh-pages 分支内容校验 #

• 进入仓库的gh-pages分支，确认根目录存在css、js、images等静态资源文件夹，打开任意生成的HTML文件，检查头部引入的CSS路径是否和gh-pages分支内的实际文件路径匹配，路径不匹配100%是baseURL配置错误导致。

4 缓存清理 #

• 进入仓库Actions页面，找到对应工作流，手动触发一次重新运行。
• 本地访问站点时使用Ctrl+Shift+R强制刷新，清除浏览器缓存的旧资源。

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