手动部署没有CSS样式

本地生成正常，手动部署github没有CSS样式。可能是忘记改baseUrl，还在用localhost:1313。

把地址改成https://你的github仓库地址/。然后删除public里面生成的静态文件，执行hugo -D重新生成，然后再次部署。

自动部署只有index.xml，没有html生成

如果手动部署正常，但是自动部署有问题。

证明不是 Hugo 配置本身 的问题（本地能正常生成 HTML），而是 GitHub Actions 构建时没有拿到 HTML 的布局文件，于是 Hugo “找不到 layout → 跳过 HTML”，但 RSS 用的是内置模板还能生成，于是发布后只剩 index.xml。

配置里用的是 PaperMod。如果主题是 git submodule 放在 themes/PaperMod，Actions 默认不会把子模块拉下来；没有主题就没有 HTML 布局，Hugo 会在日志里报类似：

WARN  found no layout file for ... kind home | HTML

而 RSS 仍会生成。

修复： 在 checkout 加上 submodules: true（或 recursive），示例工作流：

name: deploy

# 代码提交到main分支时触发github action
on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
        - name: Checkout
          uses: actions/checkout@v4
          with:
              fetch-depth: 0
              submodules: true          # ★ 拉取主题子模块
              # submodules: recursive   # 若主题里还有子模块

        - name: Setup Hugo
          uses: peaceiris/actions-hugo@v3
          with:
              hugo-version: "latest"
              extended: true

        - name: Build Web
          run: hugo -D

        - name: Deploy Web
          uses: peaceiris/actions-gh-pages@v4
          with:
              PERSONAL_TOKEN: ${{ secrets.你的TOKEN }}
              EXTERNAL_REPOSITORY: 你的github名字/你的github部署网站的仓库名
              PUBLISH_BRANCH: main
              PUBLISH_DIR: ./public
              commit_message: auto deploy

其它小问题

Hugo在构建时要在 public/tags/index.xml 位置生成一个文件（通常是 tags 的 RSS）。如果index.xml是个tag，那么会生成index.xml的文件夹，而文件无法覆盖目录，会报错导致部署失败。建议把tag中的index.xml改成index-xml