重装系统电脑没有备份，只能拉取远程代码然后本地运行调试了。

第一个坑：Hugo配置系统变量

拉起代码之后，本地运行命令：

hugo server -D

报错： 无法将“hugo”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。

原因：没有配置hugo环境

下载Hugo安装包，地址：https://github.com/gohugoio/hugo/releases

我使用extended(扩展版)是因为使用了PaperMod简约主题需要extended版来处理SCSS/SASS样式。

安装zip包解压缩，配置环境变量只想hugo.exe就OK了。

第二个坑：本地访问Page Not Found

运行本地项目后，访问http://localhost:1313/报错：Page Not Found。

原因：项目下themes/PaperMod是个空文件夹，相当于没有主题，也就没有加载出页面内容。

导致问题的原因：themes/PaperMod是通过git submodule的形式嵌套的，它也是一个单独的git仓库(是子项目)。

# 重装之后拉取代码使用的git clone xxxxxx只是拉取了主仓库
# 需要再进入到子项目目录进行拉取
cd themes/PaperMod
git pull origin master

git submodule各种问题

拉取submodule的时候各种报错：

  1. 错误地配置了代理：

    unable to access ‘https://github.com/qiuxiaolong1/qingkong-blog.git/': OpenSSL SSL_connect: SSL_ERROR_SYSCALL in connection to 127.0.0.1:7897

    解决方案：

    # 查看git的代理配置，先删除
# 取消全局代理配置
git config --global --unset http.proxy
git config --global --unset https.proxy

# (可选) 如果你只想针对当前仓库清理
git config --unset http.proxy
git config --unset https.proxy

  2. 不稳定网络环境下的负载传输失败：

    error: RPC failed; curl 92 HTTP/2 stream 0 was not closed cleanly: CANCEL (err 8)

    fatal: clone of ‘https://github.com/adityatelange/hugo-PaperMod' into submodule path ‘F:/code/qingkong-blog/themes/PaperMod’ failed

    Failed to clone ’themes/PaperMod’. Retry scheduled

    Cloning into ‘F:/code/qingkong-blog/themes/PaperMod’…

    直接忽略，纯粹网络延迟导致的。。。

  3. Git索引(index)与物理目录状态严重脱节：

    fatal: not a git repository: F:/code/qingkong-blog/themes/PaperMod/../../.git/modules/themes/PaperMod

    Failed to clone ’themes/PaperMod’. Retry scheduled

    BUG: submodule considered for cloning, doesn’t need cloning any more?

    fatal: could not get a repository handle for submodule ’themes/PaperMod’

    解决方案：

    • 彻底删除子模块元数据

      # 1. 强制移除子模块物理目录
rm -rf themes/PaperMod

# 2. 清理 Git 内部缓存（这是报错根源）
git rm -r --cached themes/PaperMod 2>/dev/null

# 3. 彻底删除 Git 管理目录中的子模块残留（非常关键）
# 在 Windows 环境下手动执行或运行：
rm -rf .git/modules/themes/PaperMod

    • 修正 .gitmodules 配置

      [submodule "themes/PaperMod"]
    path = themes/PaperMod
    url = https://github.com/adityatelange/hugo-PaperMod

    • 分步恢复

      # 1. 重新同步配置
git submodule sync

# 2. 强制手动克隆子模块到指定路径，仅获取最近一次提交（规避 EOF 报错）
git clone --depth 1 https://github.com/adityatelange/hugo-PaperMod themes/PaperMod

# 3. 重新建立主仓库与子模块的绑定关系
git submodule add --force https://github.com/adityatelange/hugo-PaperMod themes/PaperMod

    • 验证，更新成功没有报错信息

      git submodule update --init --recursive

    终极方案：Https直接切换为SSH

    HTTPS 协议（https://...）持续报 10054 错误，说明网络环境对 GitHub 的 HTTPS 加密流量监控极其严格。这种情况需要特别注意：

    1. 不要频繁重试：10054 错误如果连续出现，说明配置有误，盲目重试会导致 GitHub 触发临时 IP 封禁。
    2. 检查 MTU：如果你在云服务器或特定路由下，请尝试减小网卡的 MTU 值，但这属于底层网络调优，优先执行上述 Git 配置。
    3. 关于推送：你之前遇到的 src refspec master does not match any 报错，请务必先完成 git add . 和 git commit 后再尝试推送。

    协议切换组合拳：

    生成 SSH Key：ssh-keygen -t ed25519 -C "your_email@example.com"。

    将公钥添加到 GitHub 设置。

    修改远程仓库地址：

    git remote set-url origin git@github.com:qiuxiaolong1/qingkong-blog.git

    修改 .gitmodules 中的子模块地址为 SSH 格式： url = git@github.com:adityatelange/hugo-PaperMod.git

    同步并更新：

    git submodule sync
git submodule update --init --recursive