Featured image of post Hugo + Stack 搭建个人博客：GitHub Pages 部署和 Token 踩坑记录

Hugo + Stack 搭建个人博客：GitHub Pages 部署和 Token 踩坑记录

记录了我如何使用 Hugo 和 GitHub Pages 搭建个人博客。重点分享 macOS 与 Windows 的环境差异，以及解决首次 `git push` 时遇到的 GitHub 令牌（Token）认证问题。

本文记录第一次用 Hugo + Stack 搭建个人博客的过程，重点是 macOS 环境、GitHub Pages 自动部署和 GitHub Token 认证问题。

你好，世界！欢迎来到我的小站。

正如标题所说，这是我的第一篇博客。作为一个喜欢记录和分享的人，我一直梦想着拥有一个属于自己的、可以自由书写的空间。在探索了各种方案后，我最终选择了 Hugo + GitHub Pages 这套组合，因为它足够快速、免费、强大，而且折腾起来非常有成就感。

这篇文章，就是为了记录我从一个想法到网站上线的全过程，并特别点出一些教程里可能没详细说明、但我亲身遇到的“坑”。

搭建过程我主要参考了以下优秀教程，强烈推荐大家先看一遍：

整体思路

  1. 在本地电脑上安装 Hugo。
  2. 创建网站、配置主题、撰写文章。
  3. 将网站源码推送到 GitHub，触发自动化部署。
  4. 最终，通过 username.github.io 访问你的博客。

第一步：环境准备 (macOS)

首先，我们需要一些基础工具。在 macOS 上，推荐使用 Homebrew 这个包管理器来安装，非常方便。

  1. 安装 Homebrew (如果已经安装，请跳过)

    1

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

  2. 安装 Hugo 和 Git

    1
2

    brew install hugo
brew install git

    安装完成后，可以通过 hugo version 和 git --version 来检查。

核心搭建步骤：跟随教程 & 注意差异

从创建 Hugo 网站、安装 Stack 主题，到配置 hugo.toml 文件、设置 GitHub Actions 自动化部署，上面链接的教程已经讲得非常详细清晰了，我就不再赘述。

在这里，我只想补充一点 macOS 用户 需要注意的小差异：

macOS 用户请注意： 在视频教程中，你可能会看到讲师使用的是 hugo.exe 命令。这是因为他可能是在 Windows 上直接下载的二进制文件。 在 macOS 上，通过 Homebrew 安装后，直接使用 hugo 命令即可，例如 hugo server -D。不需要 .exe 后缀。

关键一步：首次 git push 与 GitHub 令牌（Token）

当你本地的所有工作都完成后，最后一步是 git push，将你的网站源码推送到 GitHub 仓库。这是新手最容易卡住的地方。

现在 GitHub 不再支持使用账户密码直接进行 git 操作，我们必须使用 个人访问令牌（Personal Access Token, PAT）。

1. 为什么需要令牌？

简单来说，令牌是比密码更安全的一种认证方式。

2. 第一次 Push 的正确姿势

当你第一次执行 git push 时，系统会弹出一个窗口或在命令行提示你输入用户名和密码：

  • Username: 输入你的 GitHub 用户名。
  • Password: 千万不要输入你的 GitHub 登录密码！ 在这里应该粘贴你提前生成好的个人访问令牌。

如何生成令牌？ 前往 GitHub -> 点击右上角头像 -> Settings -> Developer settings -> Personal access tokens -> Tokens (classic) -> Generate new token。 权限 (Scopes) 至少要勾选 repo。 生成后，立刻复制并保存好这个令牌，因为这个页面关掉后你将再也看不到它了。

3. 救命！我的令牌过期了/错了，该如何更新？

这是一个非常常见的问题。如果你之前设置过错误的令牌，或者令牌过期了，git push 会一直失败，提示认证错误。这是因为 macOS 的“钥匙串”已经帮你记住了那个旧的、无效的令牌。

我们需要手动删除它，让 Git 重新问你要新的。

在最新版的 macOS 中，操作非常简单：

  1. 打开“系统设置” (System Settings)。
  2. 在左侧菜单找到并进入 “密码” (Passwords) 区域 (需要 Touch ID 或密码解锁)。
  3. 在密码列表上方的搜索框中，输入 github.com。
  4. 找到相关的条目，点击右侧的“信息”图标 (i)，然后选择 “删除密码”。

删除后，回到你的终端，再次执行 git push。此时，系统就会重新提示你输入用户名和密码了，这时再粘贴你的新令牌，问题就解决了！

总结

搭建博客的过程，就是跟随教程、解决问题的过程。希望我补充的这两点关于 macOS 的命令差异和 GitHub 令牌的经验，能帮你绕过新手常见的“坑”。

现在，轮到你来书写自己的故事了。

相关阅读