该方案优点

  • GitHub仓库无需设置为公开，Hugo站点通过CF部署而不是GitHub Pages。
  • Cloudflare Pages (CF Pages) 是 Cloudflare 提供的 Jamstack 静态网站托管平台，同时免费提供如下功能：全球 CDN 加速、简便的 CI/CD 集成、无限的请求数和每月 500 次构建、内置 SSL 证书、Jamstack 友好、无服务器函数支持（Cloudflare Workers 集成）、便于关联自己的域名、安全、高扩展性。

安装Hugo

安装go：

All releases - The Go Programming Language

安装git：

winget install –id Git.Git -e –source winget

安装chocolatey：

Installing Chocolatey

以管理员模式cmd运行以下代码执行：

@"%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe" -NoProfile -InputFormat None -ExecutionPolicy Bypass -Command “iex ((New-Object System.Net.WebClient).DownloadString(’https://community.chocolatey.org/install.ps1’))” && SET “PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin”

安装hugo：

winget install Hugo.Hugo.Extended

choco install hugo-extended

安装完成，快速开始

Quick start

检查Hugo版本：hugo version

在本地创建一个 Hugo 静态网站，初始化 Git 仓库，并配置和启动 Hugo 服务器的示例。以下是命令及详细解释：

  1. hugo new site quickstart：

    • 这个命令会创建一个新的 Hugo 站点，名为 quickstart。它生成基本的站点文件夹结构，包括 config.toml 文件和内容目录。quickstart可更改为你希望的任何名字。

  2. cd quickstart：

    • 进入刚刚创建的 quickstart 站点目录。

  3. git init：

    • 初始化一个新的 Git 仓库，用于版本控制。这样你可以通过 Git 来跟踪 Hugo 站点的文件更改。

  4. git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke：

    • 添加 Ananke 主题作为 Git 子模块。Ananke 是一个 Hugo 官方推荐的主题。
    • 这条命令会把主题存放在 themes/ananke 文件夹中，以便可以用来渲染站点。

  5. echo "theme = 'ananke'" >> hugo.toml：

    • 将主题配置添加到 hugo.toml 文件中，告诉 Hugo 使用 ananke 主题来渲染网站。

  6. hugo server：

    • 启动 Hugo 开发服务器，Hugo 将编译站点并在本地启动一个服务器，默认运行在 http://localhost:1313。
    • 你可以在浏览器中打开该地址预览站点的实时变化。

  7. hugo new content posts/my-first-post.md：这条命令用于在 Hugo 网站中创建一个新的内容文件（博客文章）。

    • hugo new：用于在 Hugo 中创建新的内容（如文章、页面、项目等）。根据你的站点配置，Hugo 会自动生成一个带有基本前置元数据的 Markdown 文件。
    • content：这是 Hugo 默认的内容目录，存放你所有的文章和页面。Hugo 会根据此目录中的内容生成静态网页。
    • posts/my-first-post.md：posts 是内容类型或分类，表示这是一个博客帖子，可以根据需要修改为其他分类。
    • my-first-post.md 是生成的 Markdown 文件的名称，代表文章的文件名。
    • 在运行这条命令后，Hugo 会生成一个 content/posts/my-first-post.md 文件，并自动填充基本的元数据（front matter），例如文章的标题、日期和草稿状态。你可以打开该文件进行编辑，添加文章的内容。

发布到远程仓库（GitHub）

  • 在public文件夹执行git push -u origin master
  • 如果你还没有远程仓库，请参考下列方法创建：

1. 在 GitHub 上创建一个新的仓库

  • 登录到 GitHub。
  • 点击右上角的加号（+）并选择 Nw repository。
  • 填写仓库名称，设置为公开或私有，然后点击 Create repository 按钮。

2. 在本地仓库中设置远程仓库

打开终端（或命令行工具），然后进入您的本地 Git 仓库目录。运行以下命令，将本地仓库与 GitHub 上的远程仓库连接起来：

1

git remote add origin https://github.com/USERNAME/REPOSITORY_NAME.git

将 USERNAME 替换为您的 GitHub 用户名，REPOSITORY_NAME 替换为您在 GitHub 上创建的仓库名称。

3. 推送本地仓库到 GitHub

  • 如果您已经有文件并进行了提交，可以将这些提交推送到 GitHub：

    1

    git push -u origin mai

    如果您的分支不是 main（例如，master），请将 main 替换为您的当前分支名称。

  • 如果仓库是空的，您可以先初始化、添加文件并提交：

    1
2
3
4
5

    git init
git add .
git commit -m "Initial commit"
git branch -M main  # 将分支名称设置为 main（可选）
git push -u origin main

4. 验证远程连接

您可以通过以下命令查看已连接的远程仓库：

1

git remote -v

如果看到类似于 origin https://github.com/USERNAME/REPOSITORY_NAME.git (fetch) 和 origin https://github.com/USERNAME/REPOSITORY_NAME.git (push) 的输出，说明您的本地仓库已成功连接到 GitHub。至此，您的本地仓库已经成功连接到 GitHub，您可以随时推送更改到远程仓库。

PS：你可以下载GitHub Windows客户端来可视化完成上述操作

快速开始步骤四主题安装的补充说明

引入子模块（用于安装主题到themes文件夹）：

要将子模块引入到指定路径，你可以在 git submodule add 命令后面指定路径。以下是具体步骤：

  1. 在主仓库的根目录下打开终端或命令行界面。

  2. 运行 git submodule add <子模块的仓库URL> <指定路径> 命令，将子模块添加到指定路径中。例如：这将在主仓库的 /themes 目录中创建一个名为子模块的目录，并将子模块的代码克隆到该目录中。

    1

    git submodule add https://github.com/example/themes.git /themes

  3. 提交主仓库的更改，包括新添加的子模块。

在这种情况下，指定的路径就是你希望子模块在主仓库中的相对路径。

主题部署到cf pages出现错误？

引入主题子仓库时需要在网站根目录下的.gitmodules文件添加子仓库链接，缩进需要严格控制，否则会提示如下错误： fatal: No url found for submodule path ’themes/hugo-PaperMod’ in .gitmodules

尝试解决问题：

  • 初始化子模块：如果您刚克隆了仓库或子模块未被初始化，您需要初始化子模块。运行以下命令：git submodule update --init
  • 手动更新子模块 URL：如果子模块的 URL 已更改，您可能需要手动更新 .gitmodules 文件中的 URL。以下是具体内容示例：
1
2
3

[submodule "themes/terminal"]
	path = themes/terminal
	url = [https://github.com/panr/hugo-theme-terminal.git](https://github.com/panr/hugo-theme-terminal.git)
  • 更新子模块：如果仓库中的子模块引用发生了变化，或者子模块的仓库已经更新，您需要更新子模块。运行以下命令：git submodule update --recursive --remote

至此，你本地和远程仓库均已经有了一个Hugo站点，是时候让网友也能够访问了

部署Cloudflare Pages

要将您的站点部署到 Pages：

  1. 登录到 Cloudflare 仪表盘 并选择您的账户。
  2. 在账户主页中，选择 Workers & Pages > 创建应用 > Pages > 连接到 Git。
  3. 选择您新创建的 GitHub 仓库，并在“设置构建和部署”部分提供以下信息：
    配置选项 值
    生产分支 main
    构建命令 hugo
    构建目录 public

基础 URL 配置

Hugo 允许您配置应用程序的基本 URL。这使您能够利用助手函数来构建完整的规范 URL。要在 Pages 中做到这一点，您必须在构建命令中通过环境变量提供 baseURL 或 -b 标志。

最终的构建命令可能如下所示：

1

hugo -b $CF_PAGES_URL

完成部署配置后，选择 保存并部署。接下来您会看到 Cloudflare Pages 安装您的项目依赖项并构建站点，然后将其部署。

注意

部署您的站点后，您将获得项目的唯一子域（如 *.pages.dev）。每当您向 Hugo 站点提交新代码时，Cloudflare Pages 会自动重新构建项目并进行部署。您还可以在新拉取请求上预览部署的更改，从而在将更改部署到生产环境之前预览它们的效果。

使用特定或更新版本的 Hugo

要使用特定或更新版本的 Hugo，您可以在 Pages 项目的 设置 > 环境变量 中创建环境变量 HUGO_VERSION。将值设置为您想指定的 Hugo 版本（推荐使用 v0.112.0 或更高版本）。

例如：HUGO_VERSION = 0.115.4

注意

如果您计划使用预览部署，请确保也在预览环境中添加相应的环境变量。

关于BaseURL

URL管理 | Hugo官方文档 (opendocs.io)

不使用 BaseURL 的已知问题:

  • 在进行社交分享时无法预览图片
  • 搜索引擎无法索引网站地图,如果没有BaseURL，网站地图的 URL 都是相对的，这将导致搜索引擎无法索引您的网页。