近日，不少使用Hugo静态网站生成器的开发者反映，在本地通过hugo server运行测试时，页面中的图片均能正常加载显示，但一旦将站点部署到GitHub Pages上，图片链接就变成了“404”或空白占位符。这一现象在Hugo社区及Stack Overflow等技术论坛中屡见不鲜，影响了大量个人博客、项目文档站点的正常访问。本文将从技术原理出发，剖析问题根源，并给出行之有效的修复方案。

现象描述：本地与云端的两张“脸”

Hugo作为Go语言编写的超快静态站点生成器，凭借其灵活的模板系统和极短的构建时间，深受开发者喜爱。开发者通常会在本地使用hugo server -D（或hugo server）开启开发服务器，在浏览器中预览站点效果，一切完美：图片、样式、脚本均正常渲染。然而，当执行hugo命令构建静态文件，并将public目录推送到GitHub仓库，启用GitHub Pages服务后，却发现页面上的图片全部失效，而其他资源（如CSS、JS）可能正常，也可能同样丢失。

根因分析：路径、大小写与基URL的“暗礁”

经过大量案例排查，Hugo图片在GitHub Pages上不显示的核心原因可归结为以下三类：

1. 相对路径与绝对路径的混淆

Hugo默认会在本地开发模式下将站点根目录设置为http://localhost:1313，而在config.toml（或config.yaml）中通常配置了baseURL。许多开发者直接在Markdown或模板中使用诸如![alt](/images/photo.png)的绝对路径写法。在本地，该路径会被正确解析为http://localhost:1313/images/photo.png；但部署到GitHub Pages后，若baseURL配置为https://username.github.io/repo-name/（项目Pages），则根路径变为/repo-name/，导致图片请求被发往https://username.github.io/images/photo.png（缺少项目名），从而返回404。

解决方案：使用Hugo的relURL或absURL模板函数，或在Markdown中利用{{< figure src="/images/photo.png" >}}短代码，让Hugo在构建时自动根据baseURL修正路径。确保baseURL在配置文件中以斜杠结尾，如https://username.github.io/repo-name/。

2. 大小写敏感的文件系统差异

Windows和macOS的本地文件系统默认大小写不敏感，而Linux（GitHub Pages的服务器环境）是大小写敏感的。如果图片实际文件名是Photo.png，但在Markdown中写作photo.png，本地开发服务器会正常显示，Linux环境则会报错找不到文件。

解决方案：统一所有图片文件名及引用路径的大小写，坚持使用小写字母加连字符的命名规范（如my-photo.png），并在代码中严格保持一致。

3. Git忽略规则遗漏资源

部分开发者误将public/目录添加到了.gitignore文件中，但Hugo构建后的静态文件正是放置在public下。如果使用[GitHub Actions]或自定义CI/CD自动构建部署，通常需要将public目录作为部署源，忽略它会直接导致站点空白。此外，如果使用GitHub Pages的“docs/”文件夹模式，需确保构建命令输出到docs目录，而非默认的public。

解决方案：检查.gitignore，移除public（除非使用其他部署方式），或确保CI/CD流水线正确生成并上传静态文件。

延伸排查：资源管理与主题问题

除了上述常见原因，还需检查Hugo版本与主题的兼容性。某些主题使用“叶子包”（Leaf Bundles）或“分支包”（Branch Bundles）管理图片资源，需通过.Resources.GetMatch方法引用，而非简单的Markdown图片语法。另外，如果站点使用了图片懒加载（Lazy Loading）插件，需确保其JavaScript在GitHub Pages上能够正确执行（如无CSP限制）。

业界建议：建立标准化部署流程

针对这一普遍困扰，Hugo官方推荐开发者使用相对路径引用资源，并在config.toml中设置canonifyURLs = false（或true，视情况而定）。同时，建议使用GitHub Actions进行自动化构建与部署，将Hugo构建命令与部署步骤分离，通过--baseURL参数动态设置正确的根路径。例如：

- name: Build
  run: hugo --baseURL "https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/"

此外，利用Hugo的--themesDir选项确保主题资源被正确引用；定期运行hugo --gc垃圾回收，清理过期缓存。

结语

“本地正常，云端失效”是静态站点生成器部署中最常见的“幽灵现象”之一。对于Hugo用户而言，图片不显示通常源于路径配置、文件名大小写或构建环境差异。通过统一资源引用方式、规范命名习惯、自动化构建部署，这一问题完全可以避免。希望本文的解析能为广大开发者提供一条清晰的排错路径，让您的Hugo站点在GitHub Pages上完美呈现。