如何本地更新Hugo站点并同步GitHub Pages线上站点

• 前期部署时仅将Hugo构建生成的public静态资源目录关联了Git仓库，未将Hugo站点全量源文件纳入版本管理，因此GitHub仓库仅能看到public目录内容
• 本地修改Markdown文件后未重新执行构建命令生成最新静态资源，或推送时分支/目录匹配错误，导致GitHub Pages拉取的仍是旧版构建产物，无法同步更新内容
• 首次构建时未指定主题参数，或站点配置文件中主题字段未正确填写，导致线上仅展示主题默认示例内容

所有命令均在Hugo站点根目录执行，即本地存放站点文件的文件夹中，能看到config.yaml/config.toml、content、themes文件夹的层级，不要进入public子目录操作。

1. 清理错误的Git配置
   先删除之前误放在public目录下的Git关联文件：
   • Mac/Linux系统执行：rm -rf public/.git
   • Windows PowerShell执行：Remove-Item -Recurse -Force public/.git
2. 重新关联全量站点文件到Git仓库
   逐行执行以下命令：

   git init
   git add .
   git commit -m "init: 提交全量Hugo站点源文件"
   

   关联你的GitHub远程仓库，将命令中<你的GitHub仓库地址>替换为你自己存放Pages站点的仓库地址：
   • 首次关联执行：git remote add origin <你的GitHub仓库地址>
   • 之前已经关联过仓库的执行：git remote set-url origin <你的GitHub仓库地址>
3. 配置GitHub Pages部署分支
   打开对应GitHub仓库的设置页，找到Pages配置项，将部署源设置为gh-pages分支的根目录，保存即可。

每次本地修改完Markdown内容、调整主题配置、新增文章后，严格按以下步骤操作即可同步到线上：

1. 执行构建命令，将修改的内容渲染为静态文件存入public目录，强制指定主题避免默认内容问题：
   hugo -t hugo-whisper
   如果已经在站点配置文件中明确设置theme = "hugo-whisper"，可以直接执行hugo省略主题参数
2. 提交本地源文件的修改：

   git add .
   git commit -m "update: 同步最新站点内容"
   

3. 将全量源文件推送到仓库的默认分支（main/master）：
   git push origin main
   如果你的默认分支是master，把命令里的main换成master即可
4. 将构建好的public目录内容推送到gh-pages部署分支：
   git subtree push --prefix public origin gh-pages
5. 等待1-3分钟，GitHub Pages完成部署后刷新线上地址即可看到最新内容，部署进度可以在仓库的Actions页面查看，显示绿色对勾即为部署完成。

新手避坑提示

• public目录是每次执行hugo命令自动生成的构建产物，不需要手动修改里面的文件，也不要单独在这个目录下做Git操作
• 必须先执行hugo构建命令再推送，否则gh-pages分支拿到的还是旧版本的静态文件，线上不会更新
• 部署存在1-3分钟的缓存延迟，不要刚推完就反复刷新页面，等Actions状态更新完成再访问

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