Halo CMS 知识库

移除页面中多余的插件资源

howie_hzgo@outlook.com (HowieHz) — Tue, 14 Apr 2026 08:55:00 GMT

移除页面中多余的插件资源

问题背景

在 Halo CMS 中，有些插件为了尽量兼容主题的 Ajax、PJAX、Swup 等全站无刷新方案，会选择把自己的脚本和样式插入到每一个页面。

然而实际部署时，很多站点并不真正需要这样做，例如：

主题本身并没有使用全站无刷新方案
插件功能只会出现在少量页面

由此产生额外的请求、带宽消耗及脚本执行开销。

若不想直接修改插件源码，可使用页面转换器插件，在不需要的页面移除对应资源。

确定要移除哪些资源

在写规则之前，先确认插件实际注入了哪些资源。可以在浏览器开发者工具中查看页面源码或网络请求，重点留意插件插入的

配置示例

下面直接给出几个示例。这些规则的共同思路都是：

先用 CSS 选择器精确命中插件注入的资源标签。
再用匹配规则描述哪些页面允许保留。
最后在最外层取反，变成“除了这些页面，其他页面都移除”。

示例 1：按需移除“评论组件”插件的样式/脚本预加载

作用：在不需要的页面移除评论组件插件注入的预加载标签。

范围：

/archives/** 的文章页保留预加载资源。（/archives 和 /archives/page/* 是文章归档页，不保留预加载资源）
/moments 和 /moments/page/* 的瞬间列表页保留预加载资源。
/moments/* 的瞬间详情页保留预加载资源。
/about 是一个自定义的页面，在此保留预加载资源。导入后可按需调整此规则。
其他页面都移除资源。

json

{
  "$schema": "https://raw.githubusercontent.com/HowieHz/halo-plugin-transformer/main/ui/public/generated/transformer.schema.json",
  "version": 1,
  "resourceType": "rule",
  "data": {
    "enabled": true,
    "name": "按需移除“评论组件”插件的样式/脚本预加载",
    "description": "",
    "mode": "SELECTOR",
    "match": "link[href^=\"/plugins/PluginCommentWidget\"]",
    "position": "REMOVE",
    "wrapMarker": false,
    "runtimeOrder": 2147483645,
    "matchRuleSource": {
      "kind": "RULE_TREE",
      "data": {
        "type": "GROUP",
        "negate": true,
        "operator": "AND",
        "children": [
          {
            "type": "GROUP",
            "negate": false,
            "operator": "OR",
            "children": [
              {
                "type": "PATH",
                "negate": false,
                "matcher": "ANT",
                "value": "/archives/**"
              },
              {
                "type": "PATH",
                "negate": false,
                "matcher": "EXACT",
                "value": "/about"
              },
              {
                "type": "PATH",
                "negate": false,
                "matcher": "ANT",
                "value": "/moments/page/*"
              },
              {
                "type": "PATH",
                "negate": false,
                "matcher": "ANT",
                "value": "/moments/*"
              },
              {
                "type": "PATH",
                "negate": false,
                "matcher": "EXACT",
                "value": "/moments"
              }
            ]
          },
          {
            "type": "GROUP",
            "negate": true,
            "operator": "OR",
            "children": [
              {
                "type": "PATH",
                "negate": false,
                "matcher": "EXACT",
                "value": "/archives"
              },
              {
                "type": "PATH",
                "negate": false,
                "matcher": "ANT",
                "value": "/archives/page/*"
              }
            ]
          }
        ]
      }
    }
  }
}

示例 2：按需移除“联系表单”插件样式/脚本

作用：在不需要的页面移除联系表单插件注入的资源。

范围：

在 /about 这个自定义页面保留资源。（/about 是自己创建的页面，你可以将其改为其他的。）
其他页面都移除资源。

json

{
  "$schema": "https://raw.githubusercontent.com/HowieHz/halo-plugin-transformer/main/ui/public/generated/transformer.schema.json",
  "version": 1,
  "resourceType": "rule",
  "data": {
    "enabled": true,
    "name": "按需移除”联系表单”插件样式/脚本",
    "description": "",
    "mode": "SELECTOR",
    "match": "link[href^=\"/plugins/PluginContactForm\"], script[src^=\"/plugins/PluginContactForm\"]",
    "position": "REMOVE",
    "wrapMarker": false,
    "runtimeOrder": 2147483645,
    "matchRuleSource": {
      "kind": "RULE_TREE",
      "data": {
        "type": "GROUP",
        "negate": true,
        "operator": "AND",
        "children": [
          {
            "type": "PATH",
            "negate": false,
            "matcher": "EXACT",
            "value": "/about"
          }
        ]
      }
    }
  }
}

示例 3：按需移除 Shiki 代码高亮插件脚本注入

作用：在不需要的页面移除Shiki 代码高亮插件注入的脚本。

范围：同示例 1。

json

{
  "$schema": "https://raw.githubusercontent.com/HowieHz/halo-plugin-transformer/main/ui/public/generated/transformer.schema.json",
  "version": 1,
  "resourceType": "rule",
  "data": {
    "enabled": true,
    "name": "按需移除 Shiki 代码高亮插件脚本注入",
    "description": "",
    "mode": "SELECTOR",
    "match": "script[src^=\"/plugins/shiki\"]",
    "position": "REMOVE",
    "wrapMarker": false,
    "runtimeOrder": 2147483645,
    "matchRuleSource": {
      "kind": "RULE_TREE",
      "data": {
        "type": "GROUP",
        "negate": true,
        "operator": "AND",
        "children": [
          {
            "type": "GROUP",
            "negate": false,
            "operator": "OR",
            "children": [
              {
                "type": "PATH",
                "negate": false,
                "matcher": "ANT",
                "value": "/archives/**"
              },
              {
                "type": "PATH",
                "negate": false,
                "matcher": "EXACT",
                "value": "/about"
              },
              {
                "type": "PATH",
                "negate": false,
                "matcher": "ANT",
                "value": "/moments/page/*"
              },
              {
                "type": "PATH",
                "negate": false,
                "matcher": "ANT",
                "value": "/moments/*"
              },
              {
                "type": "PATH",
                "negate": false,
                "matcher": "EXACT",
                "value": "/moments"
              }
            ]
          },
          {
            "type": "GROUP",
            "negate": true,
            "operator": "OR",
            "children": [
              {
                "type": "PATH",
                "negate": false,
                "matcher": "EXACT",
                "value": "/archives"
              },
              {
                "type": "PATH",
                "negate": false,
                "matcher": "ANT",
                "value": "/archives/page/*"
              }
            ]
          }
        ]
      }
    }
  }
}

实现组件化与资源按需加载

howie_hzgo@outlook.com (HowieHz) — Tue, 10 Mar 2026 19:05:00 GMT

实现组件化与资源按需加载

问题背景

在 Halo CMS 主题开发中，很多主题都面临着相同的问题：

资源加载方式低效：所有页面共享一个庞大的 main.js 和 main.css，即使用户只访问了某一个页面，仍然要加载所有页面的所有代码和样式。
版本控制困难：很多主题通过在资源 URL 后添加查询参数（如 ?v=1.0.0）来控制版本，这存在安全隐患。恶意用户可以通过访问不存在的版本号（如 ?v=2.0.0）来提前缓存和污染 CDN。
组件复用困难：缺少统一的组件体系，开发者很难在不同页面间复用组件，容易导致代码冗余。

目标方案

本文将介绍如何通过现代前端技术栈，实现：

按页面分包：每个页面只加载自己需要的代码和样式
按组件分包：可复用组件拥有独立的代码包，自动去重
资源按需加载：页面初始化时只加载必要资源，其他资源按需加载
Hash 命名方案：通过内容哈希命名资源文件，彻底解决缓存问题

附加收益：

可扩展的前端工程能力：可接入 Tailwind 类名压缩、SRI 生成、构建期预压缩等插件能力，持续优化产物质量
自动生成：让浏览器提前获取依赖模块，减少后续模块执行前的等待时间

核心概念与技术栈

Vite 和 Rollup/Rolldown

Vite 是现代化的前端构建工具，采用 Rollup（v8 版本之前）或 Rolldown（v8 版本之后）作为生产构建器。在 Vite 中，build.rollupOptions.input 或 build.rolldownOptions.input 支持配置多个 HTML 入口文件，突破了单一 JS 入口的限制。

本文以 Vite v7 为例进行讲解，使用 build.rollupOptions.input 进行配置。若你使用的是 Vite v8 或更高版本，可直接使用 build.rolldownOptions.input 替代，不会影响功能实现。

这意味着什么？

之前的构建流程：index.html → main.js → 一个大的 bundle

Vite 多入口方案：archive.html, post.html, index.html → 独立的 bundle → 自动去重共享代码

Thymeleaf 模板

Thymeleaf 是 Halo CMS 使用的服务端模板引擎。它支持片段的概念，可以在模板中定义可复用的片段，并在多个地方插入。

组件化的核心设计理念

在理解具体实现前，需要掌握一个核心理念：组件是脚本、样式、HTML 的有机整体。

传统的前端开发中，常常这样组织代码：

plaintext

src/
  ├── scripts/
  │   └── pagination.js   ← 分页逻辑
  ├── styles/
  │   └── pagination.css  ← 分页样式
  └── templates/
      └── pagination.html ← 分页 HTML

问题是：这三个文件虽然逻辑相关，但在物理上分散开来，使用时容易遗漏其中某个文件。

而在组件化架构中，我们将它们放在一起，并通过 Thymeleaf 片段的机制一次性导入：

plaintext

src/components/pagination/
  ├── main.ts    ← 脚本 + 样式导入
  ├── styles.css ← 样式定义
  └── index.html ← Thymeleaf 模板（两个片段）

使用时：

html

这种设计带来以下好处：

自包含：脚本、样式、HTML 在一个目录中，开发者一目了然
易复用：引入此组件，只需两行 th:insert 代码
自动分包：Vite 会自动为每个组件生成独立的代码包
精确加载：页面只加载实际使用的组件代码，无冗余

架构比较

集中化架构

以 halo-dev/theme-modern-starter@c44c56c 为例：

plaintext

templates/
  ├── modules
  │   └── layout.html ← 公共布局模板（根级布局片段）
  ├── post.html       ← 文章详情页模板
  └── index.html      ← 首页模板

src/
  └── main.ts         ← 单一入口文件

构建结果：

plaintext

dist/
  ├── main.iife.js ← 所有页面共享的脚本文件
  └── style.css    ← 所有页面共享的样式文件

劣势：无论用户访问哪个页面，都需要加载完整的 main.iife.js 和 style.css 文件。这对于适配多个第三方插件的主题来说，会产生更明显的影响。

半组件化架构

以 HowieHz/halo-theme-higan-hz@95d7b8e 为例：

plaintext

src/
├── templates/
│   ├── fragments
│   │   └── layout.html ← 公共布局模板（根级布局片段）
│   ├── post.html       ← 文章详情页模板（包含：），编译后会替换为对应的样式表和脚本链接。
│   └── index.html      ← 首页模板（包含：）
├── components/
│   ├── component-a/    ← 组件 A
│   │   ├── main.ts     ← 组件 A 的脚本（包含 import "./styles.css";）
│   │   ├── styles.css  ← 组件 A 样式
│   │   └── index.html  ← 组件 A 的 HTML 文件
│   └── component-b/    ← 组件 B
│       ├── main.ts
│       ├── styles.css
│       └── index.html
├── styles/
│   ├── main.css        ← 公共样式文件
│   └── pages/          ← 各自的样式文件，在各自的入口文件中被导入
│       ├── post.css
│       └── index.css
└── scripts/
    ├── main.ts         ← 公共脚本文件（包含 import "../styles/main.css";）
    └── pages/          ← 各自的脚本入口文件
        ├── post.ts     ← 文章详情页脚本（包含 import "../../styles/pages/post.css";）
        └── index.ts    ← 首页脚本（包含 import "../../styles/pages/index.css";）

构建结果（由 Vite 自动处理）：

plaintext

dist/
  ├── BHmhdQc.js  ← 首页代码（仅此页面需要）
  ├── A1h342c.css ← 首页样式（仅此页面需要）
  ├── 0U3f2Kd.js  ← 文章详情页代码（仅此页面需要）
  ├── QbsQr12.css ← 文章详情页样式（仅此页面需要）
  ├── ChjrFNR.js  ← 共享代码
  ├── B0bwbiH.js  ← 组件 A 的代码
  ├── U12VxHi.css ← 组件 A 的样式
  └── Dt5VXXw.js  ← 组件 B 的代码

优势：每个页面只加载自己需要的代码，共享代码自动去重。

提示

src/components 文件夹下的每一个子文件夹都是一个组件，包含完整的脚本、样式、HTML 文件。
同理，在上面的结构中，templates/index.html 对应 styles/pages/index.css 和 scripts/pages/index.ts 本质也是一个组件，你可以依照自己的理解改变文件组织结构。

完全组件化架构

实现可参考：HowieHz/halo-theme-higan-hz@daa7038。

组件化架构实现细节

步骤 1：项目结构设计

首先，建立以下示例文件结构：

plaintext

src/
  ├── styles/
  │   ├── main.css        ← 全局样式
  │   └── pages/
  │       ├── post.css    ← 文章页样式
  │       └── index.css   ← 首页样式
  ├── scripts/
  │   ├── main.ts         ← 全局脚本
  │   └── pages/
  │       ├── post.ts     ← 文章页脚本
  │       └── index.ts    ← 首页脚本
  ├── components/
  │   ├── pagination/     ← 分页组件
  │   │   ├── main.ts
  │   │   ├── styles.css
  │   │   └── index.html
  │   ├── post-list/      ← 文章列表组件
  │   │   ├── main.ts
  │   │   ├── styles.css
  │   │   └── index.html
  │   └── header/         ← 页面头部组件（如页面导航）
  │       ├── main.ts
  │       ├── styles.css
  │       └── index.html
  └── templates/
      ├── fragments
      │   └── layout.html ← 公共布局模板（根级布局片段）
      ├── post.html       ← 文章详情页模板
      └── index.html      ← 首页模板

随后在 ts 文件中导入对应 css 文件：

提示

在 Typescript 文件导入资源文件，需要配置客户端类型。

// src/scripts/main.ts
import "../styles/main.css";

// src/scripts/pages/post.ts
import "../../styles/pages/post.css";

// src/scripts/pages/index.ts
import "../../styles/pages/index.css";

// src/components/pagination/main.ts
// src/components/post-list/main.ts
// src/components/header/main.ts
import "./styles.css";

步骤 2：Vite 配置

配置 Vite 使用 HTML 入口：

// vite.config.ts
import { resolve } from "node:path";
import { defineConfig } from "vite";

export default defineConfig({
  // 关键配置：必须与 theme.yaml 中 metadata.name 对应
  // 如果 theme.yaml 中配置为 name: howiehz-higan
  // 这里就应该是 "/themes/howiehz-higan/"
  base: "/themes/howiehz-higan/",

  build: {
    rollupOptions: {
      // 必要配置：指定多个 HTML 文件作为入口
      input: {
        // 页面模板
        post: resolve(__dirname, "src/templates/post.html"),
        index: resolve(__dirname, "src/templates/index.html"),
        // 公共布局模板（根级布局片段）
        layout: resolve(__dirname, "src/templates/fragments/layout.html"),
        // 组件
        pagination: resolve(__dirname, "src/components/pagination/index.html"),
        "post-list": resolve(__dirname, "src/components/post-list/index.html"),
        header: resolve(__dirname, "src/components/header/index.html"),
      },
      // Vite 默认会为产物生成带内容哈希的文件名；如有命名规范需求，可按需自定义
    },
  },
});

警告

由于 Vite 的构建机制限制，当前的组织方式可能导致模板文件的生成位置不符合预期。如遇到此问题，请参考常见问题 - 模板文件生成位置错误章节获取解决方案。

步骤 3：创建根级布局片段

在所有页面编写之前，需要先创建一个根级的布局片段。这个片段定义了整个 HTML 的基础结构（、、等），所有具体页面都会基于这个布局：

html

这样每个页面都复用同一个 HTML 结构，避免重复：

th:fragment="html(title, head, content, header)"：定义了一个根级片段，接收至少 4 个参数；调用时也可额外传入具名参数（如 language），以控制 lang 等属性。
th:insert="${head}"：将页面传入的 head 片段内容插入
th:insert="${content}"：将页面传入的 body 片段内容插入

步骤 4：在页面模板文件中引入脚本

在每个 Thymeleaf 模板中，在标签内引入该页面对应的脚本。Vite 会自动识别这个脚本作为该页面的构建入口：

html

构建时流程：

Vite 扫描 HTML 中的

window.open

html

pjax.loadUrl

html

window.location.href（无 th:inline）

html

window.open（无 th:inline）

html

pjax.loadUrl（无 th:inline）

html

拓展

在上面模板代码中 allPostList[randomIndex] 返回的是 ListedPostVo 类型的变量。
因此你可以拿到文章更多相关信息，如：标题，创建时间，发布时间，是否置顶，摘要内容等。

将超链接的文字替换为目标文章标题：

html

弹出一个带有消息和确认按钮的警告框，显示目标文章标题：

html

使用官方 Finder API 实现

自 Halo CMS v2.24.1

将以下代码插入模板，会创建一个指向随机文章的超链接。

html


  随机文章

结合 JavaScript 使用

插入以下代码到模板中，之后调用 toRandomPost() 即可跳转到随机文章。

window.location.href（无 th:inline）	html
window.open（无 th:inline）	html
pjax.loadUrl（无 th:inline）	html

Halo CMS 知识库

移除页面中多余的插件资源

移除页面中多余的插件资源 ​

问题背景 ​

确定要移除哪些资源 ​

配置示例 ​

示例 1：按需移除“评论组件”插件的样式/脚本预加载 ​

示例 2：按需移除“联系表单”插件样式/脚本 ​

示例 3：按需移除 Shiki 代码高亮插件脚本注入 ​

实现组件化与资源按需加载

问题背景 ​

目标方案 ​

核心概念与技术栈 ​

Vite 和 Rollup/Rolldown ​

Thymeleaf 模板 ​

组件化的核心设计理念 ​

架构比较 ​

集中化架构 ​

半组件化架构 ​

完全组件化架构 ​

组件化架构实现细节 ​

步骤 1：项目结构设计 ​

步骤 2：Vite 配置 ​

步骤 3：创建根级布局片段 ​

步骤 4：在页面模板文件中引入脚本 ​

拓展 ​

使用官方 Finder API 实现 ​

结合 JavaScript 使用 ​

移除页面中多余的插件资源

问题背景

确定要移除哪些资源

配置示例

示例 1：按需移除“评论组件”插件的样式/脚本预加载

示例 2：按需移除“联系表单”插件样式/脚本

示例 3：按需移除 Shiki 代码高亮插件脚本注入

问题背景

目标方案

核心概念与技术栈

Vite 和 Rollup/Rolldown

Thymeleaf 模板

组件化的核心设计理念

架构比较

集中化架构

半组件化架构

完全组件化架构

组件化架构实现细节

步骤 1：项目结构设计

步骤 2：Vite 配置

步骤 3：创建根级布局片段

步骤 4：在页面模板文件中引入脚本

拓展

使用官方 Finder API 实现

结合 JavaScript 使用