在构建之前重新恢复文件在本地系统的修改时间，避免被commit时间覆盖导致显示错误

GitHub Actions 自动部署 Hugo 博客说明文档

本文档详细说明了 .github/workflows/main.yml 文件的配置和工作原理。这个工作流程用于自动构建和部署 Hugo 博客到 GitHub Pages。

触发条件

on:
  push:
    branches:
      - main # 更新触发的分支

工作流会在 main 分支收到推送时自动触发。

运行环境

jobs:
  build-deploy:
    runs-on: ubuntu-20.04

使用 Ubuntu 20.04 作为构建环境，这是为了确保构建环境的稳定性。

构建步骤

1. 设置时区

- name: Set timezone
  run: |
    sudo timedatectl set-timezone Asia/Shanghai

将系统时区设置为中国时区（UTC+8），确保生成的时间戳正确。

2. 检出代码

- name: Check out repository code
  uses: actions/checkout@v4
  with:
    submodules: recursive # 获取 Hugo 主题
    fetch-depth: 0 # 获取完整的 Git 历史

submodules: recursive: 递归克隆所有子模块，确保主题文件完整
fetch-depth: 0: 获取完整的 Git 历史，这对于获取文件的修改时间很重要

3. 恢复文件时间戳

- name: Restore file timestamps
  run: |
    git ls-files -z | while read -d '' file; do
      timestamp=$(git log -1 --format="%at" -- "$file")
      touch -d @$timestamp "$file"
    done

这个步骤很关键，它解决了 Hugo 获取文件修改时间的问题：

git ls-files -z: 列出所有被 Git 追踪的文件（使用 null 字符分隔）
git log -1 --format="%at": 获取每个文件最后一次提交的 Unix 时间戳
touch -d @timestamp: 将文件的修改时间设置为该时间戳

4. 设置 Hugo 环境

- name: Setup hugo
  uses: peaceiris/actions-hugo@v3.0.0
  with:
    hugo-version: "0.127.0"
    extended: true

安装指定版本的 Hugo Extended 版本。Extended 版本支持 SCSS/SASS 处理。

5. 缓存资源

- name: Cache resources
  uses: actions/cache@v3
  with:
    path: resources
    key: ${{ runner.os }}-hugocache-${{ hashFiles('content/**/*') }}
    restore-keys: ${{ runner.os }}-hugocache-

缓存 Hugo 的资源文件以加快构建速度：

缓存路径为 resources 目录
缓存键基于操作系统和内容文件的哈希值
当内容变化时会自动创建新的缓存

6. 构建站点

- name: Build Hugo static files
  run: hugo --gc --minify

使用 Hugo 构建静态文件：

--gc: 构建后运行垃圾收集
--minify: 最小化 HTML、CSS、JS 等文件

7. 部署到 GitHub Pages

- name: Deploy to Github Pages
  uses: peaceiris/actions-gh-pages@v3
  with:
    personal_token: ${{ secrets.PERSONAL_TOKEN }}
    external_repository: 1143520/1143520.github.io
    publish_dir: ./public
    publish_branch: main
    commit_message: ${{ github.event.head_commit.message }}

将构建好的文件部署到 GitHub Pages：

personal_token: 使用个人访问令牌进行认证
external_repository: 指定部署的目标仓库
publish_dir: 指定要发布的目录（Hugo 的输出目录）
publish_branch: 指定发布到哪个分支
commit_message: 使用触发构建的提交信息作为部署提交信息

注意事项

需要在 GitHub 仓库的 Secrets 中设置 PERSONAL_TOKEN
确保目标仓库存在且有正确的访问权限
时区设置确保了生成的时间戳正确
文件时间戳的恢复确保了 Hugo 可以获取正确的文件修改时间

故障排除

如果部署失败，请检查：

Personal Token 是否有效且具有正确的权限
外部仓库是否存在且配置正确
Hugo 版本是否兼容
主题子模块是否正确克隆

源码

name: Auto Deploy hugo
on:
  push:
    branches:
      - main # 更新触发的分支
jobs:
  build-deploy:
    #  runs-on: ubuntu-latest
    runs-on: ubuntu-20.04
    steps:
      - name: Set timezone
        run: |
          sudo timedatectl set-timezone Asia/Shanghai          
      
      - name: Check out repository code
        uses: actions/checkout@v4
        with:
          submodules: recursive # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod

      - name: Restore file timestamps
        run: |
          git ls-files -z | while read -d '' file; do
            timestamp=$(git log -1 --format="%at" -- "$file")
            touch -d @$timestamp "$file"
          done
                    
      - name: Setup hugo
        uses: peaceiris/actions-hugo@v3.0.0
        with:
          #  hugo-version: "latest" # 可以修改为你使用的 Hugo 版本
          hugo-version: "0.127.0"
          extended: true # 设置是否需要 extended 版本

      - name: Cache resources # 缓存 resource 文件加快生成速度
        uses: actions/cache@v3
        with:
          path: resources
          # 检查照片文件变化
          key: ${{ runner.os }}-hugocache-${{ hashFiles('content/**/*') }}
          restore-keys: ${{ runner.os }}-hugocache-

      - name: Build Hugo static files # 部署静态资源
        run: hugo --gc --minify

      - name: Deploy to Github Pages # 部署到Github Pages页面
        uses: peaceiris/actions-gh-pages@v3
        with:
          personal_token: ${{ secrets.PERSONAL_TOKEN }}
          external_repository: 1143520/1143520.github.io
          publish_dir: ./public # hugo 生成到 public 作为跟目录
          publish_branch: main # Github Pages 所在分支
          commit_message: ${{ github.event.head_commit.message }}