Hugo部署至GitHub Pages时图片URL路径错误求助

核心原因 #

本地运行hugo server时，站点根路径是http://localhost:1313/，绝对路径/cards/card1/card1.png能直接匹配到资源；但GitHub Pages部署后，你的站点实际根路径是https://<你的用户名>.github.io/hugo_akinator/，绝对路径缺少仓库名前缀hugo_akinator，导致资源找不到。

解决方案 #

1. 正确配置hugo.toml的baseURL #

在项目根目录的hugo.toml中，将baseURL设置为包含仓库名的完整站点地址：

baseURL = "https://<你的GitHub用户名>.github.io/hugo_akinator/"

注意末尾必须保留斜杠。Hugo构建时会自动给所有绝对路径加上这个前缀，本地运行hugo server时会自动适配本地根路径，不影响开发体验。

2. 使用相对路径或Hugo资源引用 #

• 相对路径：在cards/index.md中，将图片路径改为相对当前文件的路径：

  ![card1](./card1/card1.png)
  

• Hugo内置引用：用relref短代码让Hugo自动生成正确路径：

  ![card1]({{< relref "cards/card1/card1.png" >}})
  

3. 验证部署构建参数 #

如果用GitHub Actions部署，确保构建命令中传递了正确的baseURL：

hugo --baseURL "https://<你的GitHub用户名>.github.io/hugo_akinator/"

同时确认GitHub Pages的源分支设置为gh-pages，且该分支包含Hugo构建后的public目录内容。

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