Hugo站点GitHub Pages图片不显示但远程仓库预览可见

问题核心原因 #

你之前误解了GitHub Pages的构建逻辑：GitHub Pages支持直接用Hugo构建站点，不需要遵循Jekyll的docs/assets目录规则。仓库预览能显示图片是因为GitHub的Markdown预览直接读取仓库原始文件路径，但GitHub Pages展示的是Hugo构建后的静态站点，两者路径结构完全不同。

另外，当前的路径引用/docs/assets/dm1.jpg在Hugo构建后的站点中根本不存在——Hugo只会处理static目录下的资源，将其复制到构建后的站点根目录，docs目录如果没配置为发布目录，不会被纳入构建流程。

解决方案 #

方案1：用Hugo原生资源管理（推荐） #

1. 统一资源目录：把docs/assets下的所有图片移到static/assets/目录，保持static/main.jpg不动。
2. 修正图片引用路径：
   • 首页_index.md：<img src="main.jpg" alt="me"> 可以保留（因为static/main.jpg会被放到站点根目录）
   • 文章photogallery.md：把引用改为 <img src="/assets/dm1.jpg" alt="dartmouth 1" width="225">
3. 检查baseURL配置：在hugo.toml中确保baseURL设置正确：
   • 如果是用户/组织主页（比如https://carsonc.github.io/），设为baseURL = "https://carsonc.github.io/"
   • 如果是项目站点（比如https://carsonc.github.io/my-site/），必须包含仓库名：baseURL = "https://carsonc.github.io/my-site/"

方案2：配置GitHub Pages用Hugo Action构建 #

1. 进入仓库的「Settings」→「Pages」，把「Build and deployment」的「Source」改为「GitHub Actions」。
2. 选择Hugo官方提供的Action模板（比如「Hugo」），提交后GitHub会自动用Hugo构建你的站点，完全不需要迁就Jekyll的规则。
3. 之后按Hugo原生方式管理资源即可，无需调整目录结构。

方案3：用docs目录作为发布目录（可选） #

如果一定要用docs目录存放构建后的文件：

1. 在hugo.toml中添加配置：publishDir = "docs"
2. 所有图片放回static或static/assets目录，Hugo构建时会自动复制到docs目录下对应的位置。
3. 文章中引用路径改为/assets/dm1.jpg（对应static/assets/dm1.jpg），或者/dm1.jpg（对应static/dm1.jpg）。
4. 在GitHub Pages设置中选择「Deploy from a branch」，分支选main，目录选/docs。

额外检查项 #

• 确认文件名和引用路径的大小写完全一致（GitHub Pages区分大小写）。
• 不要用canonifyURLs = true，这会导致URL被强制转义，反而容易出问题。
• PDF链接的问题和图片完全一致，按上述路径规则修正即可。

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