CF+hugo部署要点随记

该方案优点

• 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 上的远程仓库连接起来：

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

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

3. 推送本地仓库到 GitHub

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

git push -u origin mai

• 如果您的分支不是 main（例如，master），请将 main 替换为您的当前分支名称。
• 如果仓库是空的，您可以先初始化、添加文件并提交：

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

4. 验证远程连接

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

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客户端来可视化完成上述操作

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

• 去哪里获取主题：https://themes.gohugo.io/

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

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

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

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

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

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

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

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

尝试解决问题：

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

[submodule "themes/terminal"]
  path = themes/terminal
  url = <https://github.com/panr/hugo-theme-terminal.git>

• 更新子模块：如果仓库中的子模块引用发生了变化，或者子模块的仓库已经更新，您需要更新子模块。运行以下命令：git submodule update --recursive --remote

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

部署Cloudflare Pages

• 参阅官方文档：部署 Hugo 站点 ·Cloudflare Pages 文档，当然如果你需要中文版本：

要将您的站点部署到 Pages：

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

基础 URL 配置

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

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

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 都是相对的，这将导致搜索引擎无法索引您的网页。

为网站添加评论区

推荐使用已有的评论系统，比如Waline：https://waline.js.org/guide/deploy/

计算资源可以使用阿里云或Waline支持的其他数据库

写文章

创建文件

指定根目录 hugo --source /path/to/your/hugo-site

输入hugo new 文章名称.md就会在content目录下生成 “文章名称.md” 名字的文件，所有文章都是放在content这个文件夹里

hugo new /posts/blog

hugo new /posts/read

hugo new /posts/tech

hugo new /posts/life

把文章生成到指定目录，可以用以上命令。

文章标题

• title：文章标题
• date：发布日期，通常会自动生成
• draft：如果是 true，文章不会发布，设为 false 可以发布
• categories 或 tags：可以添加文章的分类或标签

撰写正文

在 --- 分隔符下方，撰写你的文章内容。使用 Markdown 语法非常简便：

• 标题：使用 # 表示，例如 # 一级标题, ## 二级标题
• 段落：直接写普通文字
• 加粗：使用 *文字** 或 __文字__
• 斜体：使用 文字* 或 _文字_
• 图片：![图片描述](图片路径)  TIP:关于映射关系，/static/images目录映射到你网站的根目录下，比如 http://yoursite.com/images/your-image.jpg ，因此插入图片只需![图片描述](/img/图片名.png)
• 链接：[链接文字](链接地址)