花费了三四天的时间，终于将博客的主体搭好了，也做了很多个性化的修改，也算是基本达到了我的要求。在这期间，我遇到了不少问题，比如一开始面对 Halo 后台界面时的茫然，想要对现有的网页做一些修改但无从下手，现有的页面不足以满足我的需求，想要添加一些自定义的页面，Halo 后端的 API 访问问题。

这些问题有一些有现成的解决方案，有一些我没有看到。所以这篇文章多少是有一点总结的意味在里面。先叠甲，我是一个前端纯小白，然后也是第一次使用 Halo 创建博客，如果我下面吐槽的问题现在已经有了成熟的解决方案，还请在评论区指出。

一、Halo 界面的使用方法

Halo 有一个自己的使用说明（基础说明 | Halo 文档），但是我感觉还是不太够，于是我在这里补充一点东西。

插件界面

image-20250927105926278

如果你是第一次登录的话，你或许会发现我这里相比于你多了一些东西，比如“链接”、“瞬间”这些。这些东西是由插件提供的选项，有许多主题会提供一些自定义的美化页面供这些插件使用，关于这部分内容我会放到 第二节：如何使用主题定义好的页面，着急的话可以直接跳转。

一般放在上面的是 Halo 官方提供的插件，还有一些插件放在下面的工具界面中，如图所示。

image-20250927110823846

插件的位置基本就这两个，如果你安装了插件但是在内容栏没有找到，不妨去工具栏找一找。

主题界面

image-20250927111229004

这一部分界面应当是 DIY 自己的博客最常使用的界面，主题的创作者在这里定义了很多自定义选项供用户设置。不过这里的设置是可以改变的，比如如果你使用的同样是 Dream 主题的话，你可能会发现我多了两个页面，“关于我”和“我推的”，这部分涉及自定义页面的内容，我将它放在了 第三节：添加自定义页面。着急的话可以直接跳转。

还有一个问题，就是下面的这个用户名一定要填对，不然主题没办法读取你的头像和名字。

image-20250927111723036

具体的寻找方法在这里：

image-20250927111922416

如果你开启了文字闪烁，但是你发现容器时大时小，那么就是你的个人描述没有设置。点击上面图片中用户的名字即可进入下面的页面，在这里可以设置自己的描述和头像。

image-20250927112301673

菜单页面

image-20250927112509043

这里设置的是主菜单的导航栏，按照我这种方式创建就会有下面的结果。注意，一定要加“/”，这样的话是绝对路径，不然使用相对路径的话会出现 https://blog.tirsenna.xyz/moments/archives 的情况。上面这种定义的方式最终得到的访问路径为：https://你的IP/moments 这种形式。

image-20250927112540489

设置页面

如果你想自定义站点标题和头像的话就需要修改这里的配置。

image-20250927113132507

这里定义了 Halo 的默认路由，这里一般不用改动，基本上每个主题都会提供这里的美化界面，访问诸如：https://你的IP/archives 就可以看到。然后你可以像我上面提到的一样在菜单栏创建导航。

image-20250927113505400

概览页面

如果你有域名，那么可以在这里修改访问路径。

image-20250927114035050

二、如何使用主题定义好的页面

一般主题的创作者除了必须要给出的 archives 等界面以外，还会给出一些其他的美化页面供用户选择。这些页面多由插件提供路由。

以 Dream 主题为例，下面的三个页面是供插件使用的，用户需要先下载插件，然后使用插件配置的路由进行访问。

image-20250927114724480

插件名称

前台路由

使用的页面模板

链接管理

/links

links.html

图库

/photos

photos.html

瞬间

/moments

moments.html

上面这些是官方插件所支持的，基本上主流主题都会支持，直接在应用市场中就可以下载。

还有一些社区插件，具体可查阅 halo-sigs/awesome-halo 获取相关信息，比如 plugin-friends。这个社区插件提供的订阅功能使用的就是 /friends 以及 friends.html。

因为社区插件太多了，我也没办法全收集到，所以如果你发现你的主题页面中有一些不知道干什么的页面有两种可能：

  1. 作者的自定义页面，如下图所示，这是我自定义的页面。

  2. 给插件使用的页面，需要你自己去搜集和查询了，或者去看看作者的描述，应该会告诉你他依赖了什么插件。

下载完插件之后，插件会自动检索模板根目录底下的对应的 HTML 文件，不用自己去配置，只要在菜单项中配置导航即可。

image-20250927124542013

三、自定义页面

如果你像我一样，感觉模板中的样式不符合自己的要求，想要自己修改，那么我在这里分享一下我的经验。Dream 主题的作者好像提供了编辑主题的功能，但是我不会使用。于是我选择了最暴力的一种解法——直接修改源代码。这样有一些弊端，就是以后无法升级主题了。但是这对我来说不是问题，主题对于我来说只是个骨架，最后还是需要我自己去完善它。

首先，下载一个插件，这个插件提供了编辑、刷新模板的功能。注意：每一次修改完成之后都要 保存 -> 重载 -> 清理缓存 -> Ctrl+F5 一条龙。

image-20250927141555129

theme.yaml 配置

theme.yaml 是模板配置选项，用于自定义模板，这里的配置主要用于页面选项，这也是自定义页面的基础。

image-20250927142153618

image-20250927142222731

settings.yaml 配置

settings.yaml 是自定义模板的动态配置选项，主要用于模板内容的动态加载，这部分的写法按照你的模板的套路写就可以。这里配置的选项会在主题界面进行展示和配置，你也可以修改已有的配置。

image-20250927142355933

image-20250927142426152

好，现在你已经知道了页面的配置，可以开始编写 HTML 文件了。以 Dream 主题为例，你上面定义的 mylikes.html 什么的应当保存在 templates 目录的根目录下，这样才方便检索。当然，应当也能定义到其他文件夹中，只不过我没有试过，在此不做赘述。

image-20250927142857666

下面是我的代码结构介绍。

根目录文件

  • archives.html: 归档页面模板，用于按时间（通常是月份或年份）展示所有文章的列表。

  • index.html: 首页模板，是网站的入口页面，通常展示最新的文章列表或特色内容。

  • categories.html: 分类列表页面模板，用于展示所有的文章分类。

  • search.html: 搜索结果页面模板，用于显示用户搜索关键词后匹配到的内容。

  • moments.html: 瞬间/动态页面模板，用于发布类似社交媒体的短内容、图片或想法。

  • mylikes.html: “我的喜欢”页面模板，用于展示用户点赞过的文章或内容。

  • friends.html: 友链页面模板，用于展示朋友的博客或网站链接。

  • photos.html: 相册/图库页面模板，专门用于展示图片集。

  • tag.html: 单个标签页面模板，用于显示标记了特定标签的所有文章。

  • tags.html: 标签云/列表页面模板，用于展示网站上所有的标签。

  • links.html: 链接页面模板，与 friends.html 类似，可以用于展示各类推荐链接。

  • page.html: 独立页面模板，用于创建自定义页面，如不属于文章分类的独立内容页。

  • post.html: 文章详情页面模板，用于展示单篇文章的完整内容、评论等。

  • category.html: 单个分类页面模板，用于显示属于某个特定分类下的所有文章。

  • about.html: “关于我”页面模板，一个特殊的独立页面，用于介绍作者或网站信息。

文件夹

  • templates: 根文件夹，包含了主题所有的 HTML 模板文件。

    • common: 公共组件文件夹，存储在多个页面间共享的模块，如：

      • navbar.html: 导航栏

      • footer.html: 页脚

      • head.html: HTML 的 <head> 部分

      • layout.html: 网站的基础布局框架

    • widget: 侧边栏模块文件夹，定义了可以在网站侧边栏使用的各种小工具，如：

      • profile.html: 作者简介模块

      • recent_posts.html: 最新文章模块

    • main: 主要内容区域文件夹，包含构成页面核心内容的部分模板。

    • error: 错误页面文件夹，存放不同 HTTP 错误（如 404）的显示页面。

  • assets: 静态资源文件夹，存放网站所需的非 HTML 文件，包括：

    • css: 存放样式表文件。

    • js: 存放 JavaScript 脚本文件。

    • img: 存放图片资源。

    • font: 存放网站使用的自定义字体文件。

    • lib: 存放引用的第三方库。

配置外部访问路由

好，现在假设你已经编写完了 HTML 页面，也配置好了 YAML。接下来就是配置路由，让外部可以访问了。这一步是最艰难的一步，直到现在我也没有搞明白为什么会出现下面的问题，我只能告诉你们我是怎么做到的，但是我相信你们大多数情况还是会遇到我下面提到的问题，不要灰心，多去试试，总能成功的。

image-20250927145236395

image-20250927145258457

image-20250927145527123

image-20250927145614881

问题自查

保存并发布之后，按照正常情况是可以正常访问的，但是就我遇到的情况而言，绝大多数是不正常的。接下来是自查流程。

image-20250927150656065

如果是这个 500 错误，恭喜你，路由配置没有问题，只是你的代码写错了。接下来你可以运行下面的命令来查看错误日志，修正后即可访问了。

docker logs -f halo容器名 -n 200

image-20250927145801394

如果是这个问题，说明模板没有被找到，这是最复杂的，你不知道有没有配置正确。同理还有一个错误：

Extension content.halo.run/v1alpha1/SinglePage/b1c3c2b9-f399-44f8-80a5-418d9f9663b4 was not found.

这个错误是说你之前定义了一个页面，但是后来你又删掉了他，然后你又创建了一个参数一样的页面，但是数据库指向的还是之前的页面。当然上面是我的猜测，也有可能是网页缓存的问题，谁知道呢。

这里给出我的解决方法，首先先按照下面的流程检查配置：

  1. 缓存清理：是否点击按钮清理了模板缓存？是否 Ctrl+F5 强制刷新清理了网页缓存？

  2. 文件配置：theme.yaml 配置是否正确？对应的 HTML 文件是否存在？有没有写错名字？

  3. 页面配置：后台的页面配置是否正确调用了模板？路由配置是否正确？

  4. 访问路径：访问的 URL 路径是否写错？

当然，我也按照上面的流程检查了，全部正确，但还是不行，这是我的真实经历。

那么还有一个办法：将现在你配置的所有和这个页面相关的东西全部删掉，然后换成一个变化很大的配置再次重试。

比如：

  • 删掉 like.html 然后创建新的 mylikes.html。

  • 将 yaml 中的配置从“我推的” -> “安利墙”，like.html -> mylike.html。

  • 删掉之前在后台配置的页面，然后清理回收站。

  • 之后重新配置页面，路由也变成新的 mylike。

相当于完全回滚之前的配置之后，重新再走一遍流程。记得一定要清理缓存。

这只能是我的经验，有一次我整了快两个小时，全都正确，就是不行，然后我回滚，然后重新创建换成新的名字一次就成功了。真是神奇。

之后就没什么了，再在菜单项中配置访问路径就可以使用了。

碎碎念

这应当是我的第一篇博客，也不知道写的怎么样，希望我的内容能够对你有所帮助。以上。