title: “从零到一：我的个人博客自动化部署问题日志” tags: [“建站”, “Hugo”, “GitHub”, “踩坑记录”, “教程”, “问题日志”]

本文是一份详尽的技术问题日志，旨在精准记录我在24小时内，从零基础开始，通过 Hugo 和 GitHub Actions 搭建一个全自动个人博客所遇到的所有障碍、诊断过程及最终解决方案。

初始目标

使用 Hugo 静态网站生成器和 GitHub Pages 服务，构建一个可以通过 git push 自动更新内容的个人博客。

问题日志

阶段一：本地环境搭建

问题 #1：'git' 不是内部或外部命令...

  • 触发操作： 在 Windows 11 的 CMD/PowerShell 中首次运行 git init。
  • 诊断： 这是典型的环境变量缺失。系统未安装 Git，或已安装但其可执行文件路径未被添加到系统的 PATH 环境变量中。
  • 解决方案：
    1. 从 git-scm.com 下载并安装 Git for Windows。
    2. 在安装向导的 Adjusting your PATH environment 步骤，必须选择 Git from the command line and also from 3rd-party software 选项，以确保 Git 命令在全局可用。

问题 #2：fatal: ... Connection was reset (下载主题时)

  • 触发操作： 运行 git submodule add https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod。
  • 诊断： 这是一个纯粹的网络连接问题。git 通过 HTTPS 协议克隆仓库的过程中，连接被服务器或中间网络设备重置。多次重试均在下载中途失败。
  • 解决方案（绕行）：
    1. 放弃使用 git submodule 命令。
    2. 直接在浏览器中访问主题的 GitHub 仓库页面。
    3. 点击 Code -> Download ZIP，手动下载主题的完整压缩包。
    4. 解压后，将 hugo-PaperMod-master 文件夹重命名为 PaperMod。
    5. 将重命名后的 PaperMod 文件夹手动移动到本地项目的 themes 目录中。此方法完全绕过了不稳定的命令行网络连接。

阶段二：首次推送到 GitHub

问题 #3：Author identity unknown

  • 触发操作： 运行 git commit -m "..."。
  • 诊断： Git 要求每一次提交（commit）都必须关联一个作者身份（用户名和邮箱）。本地 Git 配置中缺少此信息。
  • 解决方案：
    • 执行以下两条命令，配置全局的用户信息。此操作只需在新机器上执行一次。
    git config --global user.name "Dandroi"
git config --global user.email "you@example.com" # 替换为自己的GitHub邮箱

问题 #4：! [rejected] main -> main (fetch first)

  • 触发操作： 运行 git push origin main。
  • 诊断： 远程仓库（GitHub）包含了本地仓库所没有的提交记录。这是因为我为了解决部署问题，直接在 GitHub 网站上编辑了 hugo.yml 文件，导致远程版本领先于本地版本。Git 出于安全考虑，拒绝了可能覆盖远程更改的推送。
  • 解决方案：
    1. 遵循 Git 的提示，执行 git pull origin main，将远程的更改拉取到本地并与本地修改进行合并。
    2. 在执行 pull 后，系统自动进入 Vim 编辑器界面，要求输入合并备注。通过输入 :wq 并按回车，保存默认备注并退出。
    3. 完成合并后，再次执行 git push origin main，推送成功。

阶段三：自动化部署 (GitHub Actions)

问题 #5：Error: Get Pages site failed... Not Found

  • 触发操作： GitHub Actions 首次运行。
  • 诊断： 初始的 hugo.yml 工作流配置不正确。它尝试在源码仓库 (my-blog) 自身上启用和部署 Pages，但我们的计划是将静态文件部署到一个独立的目标仓库 (dandroi.top)。
  • 解决方案：
    • 更换 hugo.yml 的内容，使用 peaceiris/actions-gh-pages 这个第三方 Action，并明确配置 external_repository 参数，指定部署的目标仓库。

问题 #6：Error: ... GITHUB_TOKEN does not support to push to an external repository

  • 触发操作： 使用了新的 hugo.yml 后，GitHub Actions 再次运行。
  • 诊断： 这是一个权限问题。工作流默认使用的 GITHUB_TOKEN 仅有权限操作其所在的仓库 (my-blog)。它没有权限向另一个外部仓库 (dandroi.top) 推送内容。
  • 解决方案：
    1. 生成个人访问令牌 (PAT): 在 GitHub Settings -> Developer settings -> Personal access tokens 中，生成一个具有 repo 范围权限的经典个人访问令牌。生成后必须立刻复制并保存该令牌。
    2. 在源码仓库中添加 Secret: 在 my-blog 仓库的 Settings -> Secrets and variables -> Actions 中，创建一个名为 ACTIONS_DEPLOY_KEY 的新 Repository secret，其值为上一步生成的 PAT。
    3. 更新工作流文件: 修改 hugo.yml，将部署步骤中的 github_token: ${{ secrets.GITHUB_TOKEN }} 替换为 personal_token: ${{ secrets.ACTIONS_DEPLOY_KEY }}。

阶段四：最终的“拦路虎”——本地环境兼容性

问题 #7：git@github.com: Permission denied (publickey)，伴随 Could not create directory...

  • 触发操作： 在本地命令行中，尝试通过 git push 或 git pull 与配置了 SSH 协议的远程仓库进行交互。
  • 诊断： 这是本次建站过程中最底层、最顽固的问题。其根源在于我的 Windows 用户名包含中文字符（“王玉航”）。
    1. 我所使用的命令行版 Git for Windows 内置的 SSH 客户端，在处理非 ASCII 字符的用户路径时存在兼容性缺陷。
    2. 当 SSH 首次连接，需要将服务器指纹写入 C:\Users\王玉航\.ssh\known_hosts 文件时，因无法正确解析中文路径而失败。
    3. 即使手动创建了 .ssh 文件夹和 known_hosts 文件，后续的读写操作依然失败，导致公钥认证无法完成。
    4. 结论： 这是一个无法在当前命令行环境下轻易解决的底层工具兼容性问题。重命名系统用户文件夹风险极高，不可取。
  • 最终解决方案（决定性）：
    1. 彻底放弃在命令行中执行 push 和 pull 操作。
    2. 下载并安装 GitHub Desktop 官方图形化客户端。
    3. 使用 GitHub Desktop “添加本地仓库”功能，接管我的 my-blog 项目。
    4. 此后，所有提交和推送操作均通过 GitHub Desktop 的图形界面完成。该软件在后台使用了更健壮的方式处理认证和文件路径，完美绕开了命令行工具的缺陷。

最终工作流

经过以上所有问题的解决与绕行，我最终确立了稳定、高效的博客发布流程：

  1. 本地写作： 使用任何文本编辑器创作 Markdown 文章。
  2. 本地预览 (可选)： 运行 hugo server 在本地浏览器中实时查看效果。
  3. 提交更改： 打开 GitHub Desktop，为本次修改填写备注，点击 Commit to main。
  4. 一键发布： 点击 GitHub Desktop 顶部的 Push origin 按钮。

GitHub Actions 会在后台自动完成所有构建和部署工作。几分钟后，更新就会出现在我的线上博客。

总结

这次经历远超“搭建一个博客”本身。它是一次完整的、高强度的工程问题排查实践。我学会了如何阅读和理解错误日志，如何通过隔离变量来诊断问题，以及最重要的——当工具或环境成为障碍时，如何果断地寻找并切换到更合适的解决方案。