零基础构建个人博客：Hugo搭建和GitHub Pages部署完全指南

前言：在互联网上拥有自己的一块地

个人建站的热潮还是在零几年，那时候互联网就像一片无限大的荒原，也有一批站长在那个时间发家致富。可以确定的是，现在已经不是当时那个遍地都是机会的时代，但互联网依然是那片几乎无限大的土地，大到任何人都可以在中间几乎零成本的圈出自己的一块地。本文将手把手教你，如何在数字世界中划出并耕耘你的“一亩三分地”。

准备工作

如你所见这个页面就是基于Hugo（雨果）部署在Github Pages的一个静态站点。接下来的教程将以此为蓝本。在开始之前，你需要准备：

一定的英语和计算机基础：后续操作多为英文界面，且需使用命令行。有基础会更顺畅，但零基础用户也可借助翻译工具和详细指引尝试。
Windows 10 或 Windows 11 操作系统：Linux系统命令行操作更为便捷，且相关资源丰富。但考虑到多数中文用户使用Windows，本教程将以Windows环境为主。
可顺畅访问GitHub的网络环境：GitHub是全球最大的开源社区，将使用其提供的GitHub Pages功能免费部署静态网站（有一定使用限制）。由于Github在国内存在DNS污染，因此可能存在访问不稳定的情况，访问Github对网络提供商，地点等等有一定要求，请先测试能否正常访问 github.com。若无法访问，需自行寻找解决方案。访问通畅后，请使用邮箱注册一个GitHub账户。

详细步骤：从零到一搭建你的博客

第一部分：本地环境搭建与Hugo安装

打开 Microsoft Store：在Windows 10/11系统中，找到并打开内置的“Microsoft Store”。如果曾被卸载，可查找相关脚本恢复。
安装/更新 App Installer：在Microsoft Store中搜索并安装/更新 “App Installer”。这是微软官方的包管理器（winget），安装后可通过命令行高效安装软件。
以管理员模式运行 PowerShell：
- 按下 Win 键（键盘左下角Ctrl和Alt之间的徽标键） + R 打开“运行”对话框。
- 输入 powershell。
- 同时按下 Ctrl + Shift + Enter 以管理员身份运行。若有授权弹窗，请选择“是”。
- 看到蓝色窗口，即表示成功进入PowerShell命令行环境。
验证 winget 包管理器：在PowerShell中输入以下命令并按回车执行（后续命令行操作均为此方式，不再赘述）：
```
winget
```
如果看到一长串帮助信息列表，说明winget已正常工作。
（可选）更换 winget 源以提升国内访问速度： winget默认源在国内访问可能较慢或者完全无法访问。可更换为国内镜像源，如中科大源：
```
winget source add ustc https://mirrors.ustc.edu.cn/winget-source
```
- 查看当前已配置的源：winget source list
- 移除某个源（例如移除名为msstore的源）：winget source remove msstore
- 恢复默认源设置：winget source reset --force
安装 Hugo 和 Git：
- 首先，搜索Hugo，确认可以从源中找到：
```
winget search hugo
```
  如果搜索不到，请检查源配置及网络连接。
- 搜索结果中通常有Hugo的多个版本（标准版、扩展版等）。部分主题需要扩展版（Extended）功能，建议一步到位安装扩展版：
```
winget install Hugo.Hugo.Extended
```
- 接着，安装Git，后续部署会用到：
```
winget install Git.Git
```
验证 Hugo 安装并切换 PowerShell 环境：
- 关闭当前的管理员PowerShell窗口。
- 重新打开一个新的、无管理员权限的PowerShell窗口。这点很重要，因为管理员与普通用户的默认路径不同。上一步换源等操作由于要求管理员权限，因此相关操作默认在系统目录，而创建站点应在用户目录下进行。
- 在新PowerShell窗口中输入：
```
hugo version
```
  如果能看到Hugo的版本信息，例如 hugo v0.xx.x-...，则表示安装成功。接着输入：
```
hugo
```
  此时应看到类似如下错误提示，这是正常的，表示当前目录不是一个Hugo站点：
```
Error: Unable to locate config file or config directory. Perhaps you need to create a new site.
Run `hugo help new` for details.
```

第二部分：创建并配置你的Hugo站点

确定建站位置并创建站点：你的个人网站需要一个文件夹来存放所有相关文件。新打开的PowerShell默认路径通常是用户文件夹（如 C:\Users\你的用户名）。常用命令行操作：
- 进入目录：cd 目录名
- 返回上一级：cd ..
- 创建新目录：mkdir 目录名
例如，在用户目录下创建一个名为 myblogs 的文件夹，并在其中创建名为 FirstSite 的站点：
```
mkdir myblogs     # 在用户目录下创建myblogs文件夹
cd myblogs        # 进入myblogs文件夹
hugo new site FirstSite # 创建名为FirstSite的新站点
cd FirstSite      # 进入FirstSite站点根目录
```
完成此步后，myblogs\FirstSite 目录即为你的站点根目录。之后所有针对此站点的操作，都需要先通过 cd 命令进入此根目录进行。
安装并配置主题：新创建的Hugo站点没有默认主题。你可以在 Hugo官方主题站寻找喜欢的主题。
- 首先，在站点根目录（即 FirstSite 目录）下初始化一个Git仓库：
```
git init
```
- 选择一个主题，例如官方教程默认的Ananke主题。在其GitHub页面找到项目地址，使用以下命令将主题作为子模块（submodule）克隆到本地站点的 themes 文件夹下：
```
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
```
  注意：不同主题支持特性各异，具体使用方法需查阅其文档。本站使用的主题为PaperMod，后续会另文分享其详细配置。
- 配置站点使用该主题。打开站点根目录下的 hugo.toml 文件（如果没有，旧版Hugo可能是config.toml，但hugo new site默认创建hugo.toml）。不建议使用 echo "theme = 'ananke'" >> hugo.toml 命令，因PowerShell编码问题可能导致字符错误。建议直接用文本编辑器（如VS Code、记事本）打开 hugo.toml 进行编辑。 修改或添加以下基本配置：
```
baseURL = '[https://yourusername.github.io/](https://yourusername.github.io/)' # 预先填入你未来的GitHub Pages地址
languageCode = 'zh-cn' # 或 'en-us' 等
title = '我的第一个博客' # 你的网站标题
theme = 'ananke'     # 对应 themes 文件夹下的主题名

# 以下是Ananke主题的一些推荐配置，可参考其文档添加
# SectionPagesMenu = "main"
# Paginate = 3 # 主页每页显示文章数
# googleAnalytics = "" # 谷歌分析ID
# enableRobotsTXT = true

# [sitemap]
#   changefreq = "monthly"
#   priority = 0.5
#   filename = "sitemap.xml"

# [params]
#   text_color = ""
#   author = "你的名字"
#   favicon = ""
#   site_logo = ""
#   description = "我的个人博客描述..."
#   # choose a background color from sincerity, LCF, or darkblue
#   background_color_class = "bg-sincerty"
#   recent_posts_number = 3
```
  请将 baseURL、title 和 params 中的内容替换为你自己的信息。
本地预览你的网站：在站点根目录下运行：
```
hugo server
```
Hugo会自动编译网站并启动一个本地服务器。当看到类似如下输出时：
```
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop
```
说明编译成功。在浏览器中访问 http://localhost:1313/ 即可看到你的网站。在PowerShell中按 Ctrl+C 可停止本地服务器。

第三部分：部署到GitHub Pages

理解部署原理：上一步已成功在本地创建并预览了静态网站。要让公网用户访问，通常认为需要服务器、域名、备案等。但对于纯静态网站，有多种免费方案，如Vercel、GitHub Pages。它们虽有带宽流量限制，但对访问量不高的个人站点绰绰有余。本文选择GitHub Pages。
配置Git全局信息及SSH密钥：
- 如果之前未安装Git，请返回步骤6安装。
- 配置Git的全局用户名和邮箱（请替换为你在GitHub注册的用户名和邮箱）：
```
git config --global user.name "你的GitHub用户名"
git config --global user.email "你的GitHub邮箱"
```
- 生成SSH密钥对，用于本地与GitHub的安全通信：
```
ssh-keygen -t rsa -C "你的GitHub邮箱"
```
  按几次回车使用默认设置（默认存储位置、无密码）。 注意！ SSH私钥（默认为 id_rsa）和公钥（id_rsa.pub）是你的身份凭证，请妥善保管，勿随意泄露私钥。
- 登录GitHub网站，点击右上角头像 -> Settings -> 左侧导航栏 SSH and GPG keys -> 点击 New SSH key。
- Title处为密钥填写一个名称（如 MyLaptopKey）。
- 用记事本打开公钥文件（默认路径为 C:\Users\你的用户名\.ssh\id_rsa.pub），复制其全部内容，粘贴到GitHub的 Key 文本框中，点击 Add SSH key。
在GitHub上创建仓库并配置部署令牌：需要创建两个仓库：一个用于存放Hugo站点的源代码（私有），另一个用于托管生成的静态网站文件（公开）。
1. 创建公开的Pages仓库：
  - 点击GitHub左上角猫头鹰图标返回首页，选择 Repositories -> New。
  - 仓库名称必须严格为：你的GitHub用户名.github.io。
  - 选择 Public (公开)。
  - 建议不勾选 “Add a README file”。
  - 创建完成后，进入该仓库的 Settings -> Pages 选项卡，在 Build and deployment下的 Branch 部分，选择 main 分支（如果你的主分支是 main），文件夹选 / (root)，然后点击 Save。
2. 创建私有的源文件仓库：
  - 再次点击 New 创建仓库。
  - 仓库名称可随意（如 my-hugo-blog-source）。
  - 选择 Private (私有)，以保护你的原始博文和配置。
  - 同样建议不勾选 “Add a README file”。
3. 生成并配置部署令牌 (Personal Access Token - PAT)：此令牌将允许你的私有仓库通过GitHub Actions自动部署到公开的Pages仓库。
  - 点击GitHub右上角头像 -> Settings。
  - 拖到页面最底部，左侧选择 Developer settings。
  - 在 Personal access tokens 下选择 Fine-grained tokens (推荐) 或 Tokens (classic)。这里以 Fine-grained tokens 为例：
  - 点击 Generate new token。
    - Token name: 给令牌起个名字，如 HUGO_DEPLOY_ACTION。
    - Expiration: 选择有效期（如 “No expiration”，或自定义）。
    - Repository access: 选择 Only select repositories。在下拉列表中，仅选择你刚创建的公开仓库 (即 你的GitHub用户名.github.io)。
    - 在下方 Permissions 部分，找到 Repository permissions -> Contents，将其权限设置为 Read and write。
    - 点击 Generate token。立即复制生成的令牌字符串并妥善保存，关闭页面后将无法再次查看。
  - 回到你的私有源文件仓库 (my-hugo-blog-source) 的 Settings -> Secrets and variables -> Actions。
  - 点击 New repository secret。
    - Name: 输入 ACTIONS_DEPLOY_KEY (此名称将用于后续的GitHub Actions配置文件中)。
    - Secret: 粘贴上一步复制的个人访问令牌。
    - 点击 Add secret。
4. 创建GitHub Actions Workflow文件：在你的本地Hugo站点根目录 (FirstSite 文件夹) 中，创建以下目录和文件结构： .github/workflows/hugo-deploy.yaml 即先创建 .github 文件夹，再在其内创建 workflows 文件夹，最后在 workflows 文件夹内创建 hugo-deploy.yaml 文件。将以下内容复制到 hugo-deploy.yaml 文件中：
```
name: Deploy Hugo site to Pages

on:
  push:
    branches:
      - main  # Set a branch to deploy from (e.g., main, master)
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-latest # Using ubuntu-22.04 is also fine
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: true  # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v3 # Using v3 for stability
        with:
          hugo-version: 'latest' # Or a specific version e.g., '0.111.3'
          extended: true

      - name: Build
        run: hugo --minify # Minify static assets

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        # Only run on direct pushes to the main branch
        if: github.ref == 'refs/heads/main' && github.event_name == 'push'
        with:
          # This token is created in your private repository's secrets
          personal_token: ${{ secrets.ACTIONS_DEPLOY_KEY }}
          # Target repository (your public GitHub Pages repo)
          external_repository: YourGitHubUsername/YourGitHubUsername.github.io
          publish_branch: main # Deploy to the main branch of the target repo
          publish_dir: ./public # Hugo's default output directory
          # cname: your.customdomain.com # Uncomment if you have a custom domain
          keep_files: false # Recommended to clean up old files
          commit_message: ${{ github.event.head_commit.message }} # Use original commit message
```
  请务必修改以下部分：
  - on.push.branches: 确保 - main 对应你私有仓库中存放Hugo源码的主分支名。
  - external_repository: 将 YourGitHubUsername/YourGitHubUsername.github.io 替换为你的GitHub用户名和对应的公开Pages仓库名。
  - personal_token: secrets.ACTIONS_DEPLOY_KEY 中的 ACTIONS_DEPLOY_KEY 必须与你在私有仓库中设置的Secret名称完全一致。
  - cname: 如果你没有自定义域名，请将此行删除或注释掉 (在行首加 #)。不要在此处填写 用户名.github.io。
将本地站点推送到GitHub私有仓库并触发部署：
- 回到PowerShell，确保当前路径是你的Hugo站点根目录 (FirstSite)。
- 将本地仓库关联到GitHub上的私有远程仓库（请替换URL）：
```
git remote add origin git@github.com:YourGitHubUsername/my-hugo-blog-source.git 
# 或者使用HTTPS:
# git remote add origin [https://github.com/YourGitHubUsername/my-hugo-blog-source.git](https://github.com/YourGitHubUsername/my-hugo-blog-source.git)
git branch -M main #确保本地主分支为main
```
- 将所有文件添加到Git暂存区，提交更改，并推送到远程私有仓库：
```
git add .
git commit -m "Initial commit: Setup Hugo site and deployment workflow"
git push -u origin main
```
- 推送成功后，进入你GitHub上的私有仓库页面，点击 Actions 选项卡，应能看到名为 “Deploy Hugo site to Pages” 的工作流正在运行或已完成。
- 等待几分钟（首次部署可能稍长），工作流成功完成后，你的公开仓库 (你的GitHub用户名.github.io) 中会包含由Hugo生成的静态网站文件。
- 此时，在浏览器中访问 https://你的GitHub用户名.github.io 即可看到你的博客了！
更新与发布新内容：网站搭建完成后，更新内容流程如下：
- 在你的本地Hugo站点根目录 (FirstSite) 下，content 文件夹是存放你博文的地方。通常，文章会放在 content/posts/ 或 content/blog/ 等子目录中，具体取决于主题的组织方式。
- 创建新文章（例如在 posts 目录下创建 my-first-post.md）：
```
hugo new posts/my-first-post.md
```
  这会在 content/posts/ 目录下生成一个Markdown文件模板。
- 推荐使用VS Code等编辑器打开并编辑此 .md 文件。VS Code可通过winget安装：
```
winget install Microsoft.VisualStudioCode
```
- 编辑完成后，在本地预览检查：hugo server。
- 确认无误后，将更改推送到GitHub私有仓库以触发自动部署：
```
git add .
git commit -m "feat: Add new blog post about XYZ" # 替换为有意义的提交信息
git push
```
  GitHub Actions会自动重新构建并部署你的网站。

结语与展望

恭喜你！至此，你已完成了个人博客的搭建与部署。本文详述了我个人建站的完整步骤，至于DNS配置、购买并绑定自定义域名、更高级的页面定制与SEO优化等，都是可以继续探索的方向。后续会逐步完善和更新相关内容。

前言：在互联网上拥有自己的一块地#

准备工作#

详细步骤：从零到一搭建你的博客#

第一部分：本地环境搭建与Hugo安装#

第二部分：创建并配置你的Hugo站点#

第三部分：部署到GitHub Pages#

结语与展望#