部署站点

文档

指南

部署站点

Hugo 生成静态网站，允许灵活的托管选项。本页提供了在各种平台上部署 MaiyiDocs 站点的指南。

从模板快速开始

imfing/hextra-starter-template

您可以通过使用上述模板仓库快速入门。

我们提供了一个 GitHub Actions 工作流，可以帮助自动构建并将您的站点部署到 GitHub Pages，并免费托管。更多选项，请查看部署站点。

🌐 演示 ↗

作为新项目开始

有两种主要方式将 MaiyiDocs 主题添加到您的 Hugo 项目中：

Hugo 模块（推荐）：最简单且推荐的方法。Hugo 模块允许您直接从在线源拉取主题。主题会自动下载并由 Hugo 管理。
Git 子模块：或者，将 MaiyiDocs 添加为 Git 子模块。主题由 Git 下载并存储在您项目的 themes 文件夹中。

将 MaiyiDocs 设置为 Hugo 模块

先决条件

在开始之前，您需要安装以下软件：

步骤

初始化一个新的 Hugo 站点

hugo new site my-site --format=yaml

通过模块配置 MaiyiDocs 主题

# 初始化 Hugo 模块
cd my-site
hugo mod init github.com/username/my-site

# 添加 MaiyiDocs 主题
hugo mod get github.com/imfing/hextra

配置 hugo.yaml 以使用 MaiyiDocs 主题，添加以下内容：

module:
  imports:
    - path: github.com/imfing/hextra

创建您的内容页面

为主页和文档页面创建新的内容页面：

hugo new content/_index.md
hugo new content/docs/_index.md

本地预览站点

hugo server --buildDrafts --disableFastRender

恭喜，您的新站点预览可在 http://localhost:1313/ 查看。

如何更新主题？

要更新项目中所有 Hugo 模块到最新版本，请运行以下命令：

hugo mod get -u

要将 MaiyiDocs 更新到最新发布版本，请运行以下命令：

hugo mod get -u github.com/imfing/hextra

有关更多详细信息，请参阅 Hugo 模块。

将 MaiyiDocs 设置为 Git 子模块

先决条件

在开始之前，您需要安装以下软件：

步骤

初始化一个新的 Hugo 站点

hugo new site my-site --format=yaml

将 MaiyiDocs 主题添加为 Git 子模块

git submodule add https://github.com/imfing/hextra.git themes/hextra

配置 hugo.yaml 以使用 MaiyiDocs 主题，添加以下内容：

theme: hextra

创建您的内容页面

为主页和文档页面创建新的内容页面：

hugo new content/_index.md
hugo new content/docs/_index.md

本地预览站点

hugo server --buildDrafts --disableFastRender

您的新站点预览可在 http://localhost:1313/ 查看。

当使用 CI/CD 部署 Hugo 网站时，确保在运行 hugo 命令之前执行以下命令至关重要。

git submodule update --init

如果不运行此命令，主题文件夹将不会被 MaiyiDocs 主题文件填充，导致构建失败。

如何更新主题？

要更新仓库中所有子模块到最新提交，请运行以下命令：

git submodule update --remote

要将 MaiyiDocs 更新到最新提交，请运行以下命令：

git submodule update --remote themes/hextra

有关更多详细信息，请参阅 Git 子模块。

Hugo 模块系统的初始化命令

hugo mod init github.com/username/my-site 是 Hugo 模块系统的初始化命令，它的核心作用是将你的 Hugo 项目转化为一个 Go 模块（Go Module），为使用 Hugo Modules 管理依赖（如主题）做准备。具体作用如下：

1. 创建模块标识符

github.com/username/my-site 是你自定义的 模块路径（Module Path），通常格式为：
```
仓库托管平台/你的用户名/项目名
```
- 示例：github.com/john/my-blog
这个路径是项目的唯一标识符，在依赖管理中使用（即使项目不上传至 GitHub 也可使用此格式）。

2. 生成 `go.mod` 文件

执行命令后会在项目根目录生成一个 go.mod 文件，内容如下：

module github.com/username/my-site // 你定义的模块路径
go 1.21 // Hugo 依赖的 Go 版本（自动检测）

此文件是 Go 模块的配置文件，记录项目依赖和版本。
Hugo 模块基于 Go Modules 实现，因此需要此文件。

3. 启用 Hugo 模块系统

此操作将传统 Hugo 项目（依赖 themes 目录）升级为模块化项目。
后续可通过 hugo mod get 直接拉取远程主题/组件（如 hugo mod get github.com/imfing/hextra），无需手动复制文件。

4. 依赖管理

初始化后，可通过模块路径管理依赖：

# hugo.yaml
module:
  imports:
    - path: github.com/imfing/hextra  # 直接引用远程主题

Hugo 会自动下载依赖到本地缓存（~/.cache/hugo_modules/），不污染项目目录。
版本控制：支持语义化版本（如 @v0.7.0）或 Git 提交哈希。

重要注意事项

模块路径可自定义：
- 如果项目不上传 GitHub，可用任意路径（如 example.com/site）。
- 实际托管时建议与仓库地址一致。
本地开发无需 Go 知识：
- 虽然基于 Go Modules，但用户只需操作 Hugo 命令（hugo mod init/get）。
与传统方式的区别：
方式主题位置管理方法
Git 子模块 themes/hextra 手动更新子模块
Hugo 模块 本地缓存 hugo mod get

方式	主题位置	管理方法
Git 子模块	`themes/hextra`	手动更新子模块
Hugo 模块	本地缓存	`hugo mod get`

执行流程示例

hugo new site my-site --format=yaml  # 创建新项目
cd my-site
hugo mod init github.com/john/my-site  # 初始化模块

此时项目结构：

my-site/
├── go.mod     # 生成的模块文件
├── hugo.yaml  # 站点配置
└── content/   # 内容目录

总结：hugo mod init 是使用 Hugo 模块化管理依赖的必要第一步，它通过创建 go.mod 文件和定义模块路径，使你的项目能直接引用远程主题/组件，简化依赖管理流程。

GitHub Pages

GitHub Pages 是推荐的方式，可以免费部署和托管您的网站。

如果您使用 hextra-starter-template 引导站点，它已经提供了开箱即用的 GitHub Actions 工作流，帮助自动部署到 GitHub Pages。

GitHub Actions 配置

以下是 hextra-starter-template 的示例配置：

.github/workflows/pages.yaml

# 用于构建和部署 Hugo 站点到 GitHub Pages 的示例工作流
name: 部署 Hugo 站点到 Pages

on:
  # 在推送到默认分支时运行
  push:
    branches: ["main"]

  # 允许您从 Actions 选项卡手动运行此工作流
  workflow_dispatch:

# 设置 GITHUB_TOKEN 的权限以允许部署到 GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# 只允许一个并发部署，跳过在运行中和最新排队之间的运行。
# 但是，不要取消正在运行的运行，因为我们希望这些生产部署能够完成。
concurrency:
  group: "pages"
  cancel-in-progress: false

# 默认使用 bash
defaults:
  run:
    shell: bash

jobs:
  # 构建任务
  build:
    runs-on: ubuntu-latest
    env:
      HUGO_VERSION: 0.147.7
    steps:
      - name: 检出
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # 获取所有历史记录以支持 .GitInfo 和 .Lastmod
          submodules: recursive
      - name: 设置 Go
        uses: actions/setup-go@v5
        with:
          go-version: '1.22'
      - name: 设置 Pages
        id: pages
        uses: actions/configure-pages@v4
      - name: 设置 Hugo
        run: |
          wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
          && sudo dpkg -i ${{ runner.temp }}/hugo.deb
      - name: 使用 Hugo 构建
        env:
          # 为了最大程度地兼容 Hugo 模块
          HUGO_ENVIRONMENT: production
          HUGO_ENV: production
        run: |
          hugo \
            --gc --minify \
            --baseURL "${{ steps.pages.outputs.base_url }}/"
      - name: 上传工件
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./public

  # 部署任务
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: 部署到 GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

在您的仓库设置中，将 Pages > Build and deployment > Source 设置为 GitHub Actions：

默认情况下，上述 GitHub Actions 工作流 .github/workflows/pages.yaml 假设站点部署到 https://<USERNAME>.github.io/<REPO>/。

如果您部署到 https://<USERNAME>.github.io/，请修改 --baseURL：

.github/workflows/pages.yaml

54
55
56
57
run: |
  hugo \
    --gc --minify \
    --baseURL "https://${{ github.repository_owner }}.github.io/"

如果您部署到自己的域名，请相应地更改 --baseURL 值。

Cloudflare Pages

将您的站点源代码放入 Git 仓库（例如 GitHub）
登录 Cloudflare 仪表板并选择您的账户
在账户主页中，选择 Workers & Pages > Create application > Pages > Connect to Git
选择仓库，并在 Set up builds and deployments 部分提供以下信息：

配置项	值
生产分支	`main`
构建命令	`hugo --gc --minify`
构建目录	`public`

更多详情，请查看：

部署 Hugo 站点。
语言支持和工具。

Netlify

将代码推送到您的 Git 仓库（GitHub、GitLab 等）
导入项目到 Netlify
如果您没有使用 [hextra-starter-template][hextra-starter-template]，请手动配置以下内容：
- 将构建命令配置为 hugo --gc --minify
- 指定发布目录为 public
- 添加环境变量 HUGO_VERSION 并设置为 0.147.7，或者将其设置在 netlify.toml 文件中
部署！

查看 Netlify 上的 Hugo 了解更多详情。

Vercel

将代码推送到您的 Git 仓库（GitHub、GitLab 等）
前往 Vercel 仪表板并导入您的 Hugo 项目
配置项目，选择 Hugo 作为框架预设
覆盖构建命令和安装命令：
1. 将构建命令设置为 hugo --gc --minify
2. 将安装命令设置为 yum install golang

Vercel 部署配置

短代码高级

从模板快速开始

作为新项目开始

将 MaiyiDocs 设置为 Hugo 模块

先决条件

步骤

初始化一个新的 Hugo 站点

通过模块配置 MaiyiDocs 主题

创建您的内容页面

本地预览站点

将 MaiyiDocs 设置为 Git 子模块

先决条件

步骤

初始化一个新的 Hugo 站点

将 MaiyiDocs 主题添加为 Git 子模块

创建您的内容页面

本地预览站点

Hugo 模块系统的初始化命令

1. 创建模块标识符

2. 生成 go.mod 文件

3. 启用 Hugo 模块系统

4. 依赖管理

重要注意事项

执行流程示例

GitHub Pages

Cloudflare Pages

Netlify

Vercel

2. 生成 `go.mod` 文件