我把网站迁移到了 GitHub Pages

特别鸣谢： Soloopooo
本文大部分内容链接均指向简体中文页面

我为什么用 GitHub Pages

很简单，我原本用的是 Linode ，而 Linode 的服务器价格大约为 5 USD / 月（上个月收了我 36.69 CNY）。这个价格甚至是最低配置，而 GitHub Pages 完全免费。

并且，使用 GitHub Pages 可以再也不用在 Terminal 里和 SSH 搏斗，也不用操心 SSL 证书一系列乱七八糟的事情，全部交付给 GitHub Pages 上就好了！至少目前为止对我来说也是个很好的选择。

如何利用 Hugo 搭建 GitHub Pages 网站

基础教程

可以看 这个网站 来快速入门 Hugo。

参考 这个网站 来将本地做好的网站项目上传到 GitHub 并用 Pages 生成网站。

双仓库方案

我非常推荐使用双仓库方案来保管你的项目。

1. 创建仓库

创建两个仓库，一个为源码仓库（可以任意命名），另一个为发布仓库（必须命名为 [你的 GitHub 用户名].github.io）。源码仓库储存的是你的 Hugo 项目除了 public/ 文件夹以外的所有内容，而发布仓库通过 GitHub Actions 被创建。

2. 测试网站

通过 hugo server 命令建立本地网站，然后在浏览器中访问 localhost:1313，看看你的网站能否正常运行。如果不能，请返回检查，例如你的 md 文件是否将 draft 状态改为 false。

3. 初次提交

将你的网站项目提交到源码仓库中，这一步需要通过 .gitignore 文件来避开提交 public/ 目录。

具体来讲，创建一个 .gitignore 文件，内容为（本段代码由 豆包 生成）：

# --------------------------  
# Hugo 核心排除项  
# --------------------------  
# 构建产物  
public/  
# 资源缓存  
resources/  
# Hugo 环境变量配置（若有本地自定义环境变量）  
.env  
.env.local  
# Hugo 调试日志（若开启了日志输出）  
hugo.log  
  
# --------------------------  
# 系统/编辑器临时文件  
# --------------------------  
# macOS  
.DS_Store  
# Windows  
Thumbs.db  
desktop.ini  
# Linux  
*~  
.#*  
# VS Code 编辑器（若使用）  
.vscode/  
.idea/  # JetBrains 编辑器（WebStorm/Goland 等）  
*.swp   # Vim 交换文件  
  
# --------------------------  
# 可选排除项（根据需求）  
# --------------------------  
# .gitmodules  # 若团队协作，建议注释掉（不排除）  
# node_modules/  # 若主题依赖 npm 包（少数 Hugo 主题需要）  

然后在终端中（Windows 建议使用 Powershell ，而不要用 cmd 或者 Windows Powershell）输入以下命令来初次提交源码：

git add .  
git commit -m "Initial commit"  
git remote add origin https://github.com/[你的源码仓库].git  
git branch -M main  
git push -u origin main  

Windows 用户应该会在此时遇到 warning: in the working copy of '.gitmodules', LF will be replaced by CRLF the next time Git touches it 提示，无视他就好了，意思是 LF 换行符将会被替换 CRLF，对我们并没有太大影响。

如果遇到 Author identidy unknown 的报错，说明你的本地并没有配置用户名和邮箱，执行以下命令（更换为你自己的 GitHub 账号信息）即可：

git config --global user.email "you@example.com"
git config --global user.name "your name"

4. 配置GitHub Actions

在 GitHub 的设置中找到 Developer settings - Personal access tokens - Tokens (classic) - Generate new token (classic)。名称任意，权限选择 repo（全选）、workflow，有效期选择 No expiration（无限期，避免修改麻烦，但也可以设置期限，看你想法了）。生成后记得复制并保存令牌，因为它只会显示一次。

进入源码仓库，在设置中找到 Secrets and variables - Actions - New repository secret。名称任意（推荐设置：DEPLOY_TOKEN），注意会在后面的 deploy.yml 中用到，值为保存的令牌。

在本地hugo项目中创建 .github/workflows/deploy.yml 文件，内容如下（依旧豆包生成），注意有两处替换：

name: Deploy Hugo to GitHub Pages

# 触发条件：推送到 main 分支时执行
on:
  push:
    branches: ["main"]
  workflow_dispatch: # 允许手动触发

# 权限配置
permissions:
  contents: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      # 步骤1：检出源码仓库（包含子模块）
      - name: Checkout source code
        uses: actions/checkout@v4
        with:
          submodules: true  # 拉取主题子模块（Ananke）
          fetch-depth: 0    # 确保 Hugo 能获取完整提交记录

      # 步骤2：安装 Hugo（建议指定版本）
      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: '0.152.2'  # 此处为发布本 blog 时的最新版
          extended: true           # 根据主题选择，Ananke 主题需要 extended 版本

      # 步骤3：构建静态文件（生成到 public/ 目录）
      - name: Build Hugo site
        run: hugo --minify  # --minify 压缩静态文件，可选

      # 步骤4：推送到部署仓库（username.github.io）
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          # 部署仓库的地址（替换为你的用户名）
          deploy_repo: [你的用户名]/[你的用户名].github.io
          # 使用 PAT 授权推送（替换为你的 Secrets，填入名字而不是令牌值）
          personal_token: ${{ secrets.DEPLOY_TOKEN }}
          # 要推送的目录（Hugo 构建的静态文件）
          publish_dir: ./public
          # 部署仓库的分支（GitHub Pages 默认从 main 或 gh-pages 分支部署）
          publish_branch: main
          # 提交信息
          commit_message: ${{ github.event.head_commit.message }}

最后一步是推送 deploy.yml 到源码仓库

git add .github/workflows/deploy.yml
git commit -m "Add GitHub Actions for auto deploy"
git push origin main

5. 配置 GitHub Pages

找到发布仓库设置的 Pages，在 Build and deployment 区域，Source 选择 Deploy from a branch，Branch 选择 main（需要与 deploy.yml 配置的 publish_branch 一致），目录选择 / (root)。保存后等待几分钟后，访问你的网站，检查是否部署完成。

执行完全部步骤后，应该就可以了，只要你没有动不改动的配置。

自定义域名

1. 配置解析

如果你购买了自己的域名，那么可以将上面创建的网站自定义为你自己的域名。在域名注册商后台或者第三方 DNS 服务商（例如 Cloudflare）配置域名 DNS 解析：

@ 代表根域名，记录值 ip 为 GitHub Pages 官方固定 ip 无需修改，TTL 可以根据需求自己选择，注意 CHAME 记录的记录值需要在末尾加 . 。如果域名注册商支持 ALIAS 记录（如阿里云），也可将 @ 设为 ALIAS 记录，值填 [你的 GitHub 用户名].github.io. 来替代 4 条 A 记录。

注意，如果使用 Cloudflare 等第三方 DNS 服务商，记得关闭他们的代理服务，让流量直接通过 GitHub。

2. 配置仓库

在本地文件根目录创建 CNAME 文件（名字就叫 CNAME，不含后缀名，全大写），内容为

你的自定义域名

然后输入以下命令提交并推送：

git add CNAME
git commit -m "Add a CNAME"
git push origin main

将本地网站项目的 hugo.toml 或者 config.toml 的 baseURL 改为你的自定义域名，然后输入以下命令提交并推送修改：

git add hugo.toml
git commit -m "Update baseURL to custom domain trave11er.org"
git push origin main

4. 验证配置

在终端中执行 ping [你的自定义域名]，如果返回前文提到的 GitHub Pages 官方 ip，则说明解析生效。

在发布仓库设置的 Pages 页面，如果显示 “Your site is live at https://[你的自定义域名]"，则说明配置成功。

访问你的自定义域名，能够看到你的博客，则说明万事俱备，只欠你的文章！

还有一些话

希望可以通过我的教程学到一些东西，然后建立起自己的博客网站，并开始写文章！