Hugo站点自定义index.html无法默认显示问题求助

问题详情 #

• 本地环境下，Hugo默认加载系统自带的index.html页面，仅当手动编辑layouts/index.html（哪怕仅添加一个空格）后，页面才会触发刷新并正确展示自定义首页
• 部署到Netlify后出现完全相同的问题，怀疑和缓存有关，但无法确定
• 自定义首页路径：layouts/index.html
• Netlify配置文件netlify.toml内容：

[build]
command = "hugo --gc --minify --cleanDestinationDir"
publish = "public"  # Your final built site goes here

[build.environment]
HUGO_VERSION = "0.145.0"  # Match your local Hugo version

# Optional: Cache Hugo modules/themes for faster builds
[[plugins]]
package = "netlify-plugin-hugo-cache-resources"

可行解决方案 #

本地环境修复 #

1. 停止Hugo开发服务，手动删除本地项目中的public目录和.hugo_cache目录
2. 重启服务时禁用缓存：执行命令hugo server --noCache，强制Hugo读取最新的布局文件

布局优先级排查 #

检查当前使用的Hugo主题是否自带layouts/index.html——Hugo会优先加载主题内的布局文件，而非项目根目录的同名文件。解决方式二选一：

• 删除主题目录下的layouts/index.html
• 在项目根目录创建layouts/_default/index.html，该路径的布局优先级高于主题内的首页布局

Netlify部署端修复 #

1. 禁用Hugo资源缓存插件：注释掉netlify.toml中的插件配置：

# [[plugins]]
# package = "netlify-plugin-hugo-cache-resources"

2. 手动触发清除缓存部署：进入Netlify站点的Deploys页面，点击「Trigger deploy」→「Clear cache and deploy site」
3. 优化构建命令，确保构建前彻底清理旧文件：
   修改netlify.toml中的build命令：

command = "rm -rf public .hugo_cache && hugo --gc --minify --cleanDestinationDir"

配置文件检查 #

查看项目根目录的config.toml（或config.yaml），确认没有首页相关的配置项覆盖自定义布局的优先级，比如是否指定了特定的首页模板路径

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