ruibaby · Oct 14, 2026 · Sep 8, 2026 · Sep 8, 2026 · Oct 14, 2026 · Oct 14, 2026
diff --git a/docs/developer-guide/plugin/api-changelog.md b/docs/developer-guide/plugin/api-changelog.md
@@ -3,6 +3,18 @@ title: API 变更日志
 description: 按 Halo 版本查阅插件服务端 API、UI 构建工具、表单组件和依赖升级等变更，识别兼容性影响并完成插件迁移
 ---
 
+## 2.27.0
+
+### UI 构建工具移除旧入口，构建工具依赖改为可选
+
+`@halo-dev/ui-plugin-bundler-kit@2.27.0` 移除了包根入口及 `HaloUIPluginBundlerKit`。原先从包根入口导入 `viteConfig` 或 `rsbuildConfig` 的项目，需要分别改为从 `@halo-dev/ui-plugin-bundler-kit/vite` 或 `@halo-dev/ui-plugin-bundler-kit/rsbuild` 导入；使用 `HaloUIPluginBundlerKit` 的旧项目需要迁移到对应预配置。具体步骤请参考 [UI 构建迁移](./basics/ui/build.mdx#migration)。
+
+Vite、Rsbuild 及各自的 Vue 插件均改为可选 peer 依赖。升级时请显式安装所选构建工具及其 Vue 插件，无需安装另一套工具链。已有 IIFE 产物在 Halo 2.x 中仍可加载；此变更不要求提高插件或主题的 `spec.requires`。
+
+### 移除旧缩略图扩展点
+
+移除了自 2.22.0 起废弃的 `ThumbnailProvider` 接口及 `thumbnail-provider` 扩展点。仍使用旧接口的插件需要迁移到 `AttachmentHandler.getThumbnailLinks()`，并调整扩展注册，具体说明请参考[附件存储策略扩展点](./extension-points/server/attachment.md)。主题使用的缩略图 Finder 和 HTTP API 不受此变更影响。
+
 ## 2.26.0
 
 ### UI 构建工具新增独立入口

diff --git a/docs/developer-guide/plugin/basics/devtools.md b/docs/developer-guide/plugin/basics/devtools.md
@@ -65,7 +65,7 @@ API 文档：http://localhost:8090/swagger-ui.html
 
 ```groovy
 halo {
-  version = '2.26'
+  version = '2.27'
   superAdminUsername = 'admin'
   superAdminPassword = 'admin'
   port = 8090
@@ -153,7 +153,7 @@ logging:
 
 ```groovy
 halo {
-  version = '2.26'
+  version = '2.27'
 }
 ```
 

diff --git a/docs/developer-guide/plugin/basics/ui/build.mdx b/docs/developer-guide/plugin/basics/ui/build.mdx
@@ -7,13 +7,13 @@ import { Steps } from "@rspress/core/theme";
 
 通过 [halo-dev/create-halo-plugin](https://github.com/halo-dev/create-halo-plugin) 创建的项目已经包含可用构建配置。没有特殊需求时沿用脚手架配置，不要重新实现 Halo 的输出协议。
 
-| 任务                                 | 阅读位置                                                |
-| ------------------------------------ | ------------------------------------------------------- |
-| 在 Vite 或 Rsbuild 间选择            | [ui-plugin-bundler-kit](#bundler-kit)                   |
-| 配置图标组件                         | [使用图标组件](#使用图标组件)                           |
-| 确认 ESM、IIFE 与最低 Halo 版本      | [输出格式与 Halo 目标](#output-format)                  |
-| 使用 Halo 提供的 Vue、Axios 和 UI 包 | [共享运行时依赖](#shared-runtime-dependencies)          |
-| 从旧版 plugin-starter 迁移           | [HaloUIPluginBundlerKit（已过时）](#legacy-bundler-kit) |
+| 任务                                 | 阅读位置                                       |
+| ------------------------------------ | ---------------------------------------------- |
+| 在 Vite 或 Rsbuild 间选择            | [ui-plugin-bundler-kit](#bundler-kit)          |
+| 配置图标组件                         | [使用图标组件](#使用图标组件)                  |
+| 确认 ESM、IIFE 与最低 Halo 版本      | [输出格式与 Halo 目标](#output-format)         |
+| 使用 Halo 提供的 Vue、Axios 和 UI 包 | [共享运行时依赖](#shared-runtime-dependencies) |
+| 从旧版 plugin-starter 迁移           | [迁移旧版构建插件](#legacy-bundler-kit)        |
 
 ## 原理
 
@@ -26,13 +26,14 @@ Halo 插件的 UI 部分（Console / UC）以 `index.ts` 为源码入口，默
 
 ## @halo-dev/ui-plugin-bundler-kit {#bundler-kit}
 
-这个库提供两个当前预配置和一个兼容旧项目的入口：
+这个库提供两个构建工具预配置：
 
 1. `viteConfig`: Vite 的预配置
 2. `rsbuildConfig`: Rsbuild 的预配置
-3. `HaloUIPluginBundlerKit`：已过时，迁移方式可以参考下面的文档
 
-从 2.26.0 开始，`viteConfig` 和 `rsbuildConfig` 分别通过构建工具专用入口导出。包根入口中的同名导出仅用于兼容已有项目，已标记为过时，并计划在 2.27.0 中移除。
+从 2.26.0 开始，`viteConfig` 和 `rsbuildConfig` 分别通过 `/vite` 和 `/rsbuild` 专用入口导出。2.27.0 移除了包根入口及 `HaloUIPluginBundlerKit`，已有项目请参考[迁移说明](#migration)。
+
+从 2.27.0 开始，Vite、Rsbuild 及各自的 Vue 插件均为可选 peer 依赖。只需显式安装所选构建工具及其 Vue 插件，无需安装另一套工具链。以下安装示例使用 2.27.0。
 
 ### viteConfig
 
@@ -43,7 +44,7 @@ Halo 插件的 UI 部分（Console / UC）以 `index.ts` 为源码入口，默
 安装依赖：
 
 ```bash
-pnpm install @halo-dev/ui-plugin-bundler-kit@2.26.0 vite @vitejs/plugin-vue -D
+pnpm install @halo-dev/ui-plugin-bundler-kit@2.27.0 vite @vitejs/plugin-vue -D
 ```
 
 创建 vite.config.ts:
@@ -129,7 +130,7 @@ Rsbuild 是基于 Rspack 开发的上层构建工具，其优势在于兼容 Web
 安装依赖：
 
 ```bash
-pnpm install @halo-dev/ui-plugin-bundler-kit@2.26.0 @rsbuild/core @rsbuild/plugin-vue -D
+pnpm install @halo-dev/ui-plugin-bundler-kit@2.27.0 @rsbuild/core @rsbuild/plugin-vue -D
 ```
 
 创建 rsbuild.config.ts:
@@ -363,9 +364,9 @@ ESM 入口仍需默认导出已有的 `PluginModule`，不应通过顶层副作
 
 单个 provider 的入口、样式或注册失败时，Halo 会跳过该 provider，并继续启动核心 UI 和其他 provider。入口求值产生的定时器、事件监听器等任意副作用无法保证回滚，因此插件安装、升级、启用、禁用或重新加载后，完整刷新 Console 或 UC 页面是受支持的模块替换和恢复边界。
 
-## HaloUIPluginBundlerKit（已过时） {#legacy-bundler-kit}
+## 迁移旧版构建插件 {#legacy-bundler-kit}
 
-旧版本 [plugin-starter](https://github.com/halo-dev/plugin-starter) 使用的方式，目前已经不再推荐，也不支持 ESM 或主题 UI provider。`HaloUIPluginBundlerKit` 计划在 2.27.0 中移除，请改用构建工具专用入口中的 `viteConfig` 或 `rsbuildConfig`。
+旧版本 [plugin-starter](https://github.com/halo-dev/plugin-starter) 使用的 `HaloUIPluginBundlerKit` 已在 2.27.0 中移除。升级前请按[迁移步骤](#migration)改用 `viteConfig` 或 `rsbuildConfig`。此变更不影响已有 IIFE 产物在 Halo 2.x 中的兼容性。
 
 ## 构建输出
 
@@ -378,16 +379,32 @@ ESM 入口仍需默认导出已有的 `PluginModule`，不应通过顶层副作
 
 ## 迁移{#migration}
 
-如果你当前的插件使用的是旧版本的 [plugin-starter](https://github.com/halo-dev/plugin-starter)，并且想使用新的 `viteConfig` 和 `rsbuildConfig`，可以参考以下步骤：
+### 从包根入口迁移
+
+如果已经使用 `viteConfig` 或 `rsbuildConfig`，只需修改导入路径，并按上文安装所选构建工具及其 Vue 插件。现有配置参数和 Gradle 打包配置无需因此修改。
+
+```ts
+// Vite 项目
+import { viteConfig } from "@halo-dev/ui-plugin-bundler-kit/vite";
+```
+
+```ts
+// Rsbuild 项目
+import { rsbuildConfig } from "@halo-dev/ui-plugin-bundler-kit/rsbuild";
+```
+
+### 从 HaloUIPluginBundlerKit 迁移
+
+如果当前插件使用旧版本 [plugin-starter](https://github.com/halo-dev/plugin-starter) 中的 `HaloUIPluginBundlerKit`，可以参考以下步骤迁移到 Vite 预配置：
 
 <Steps>
 
 ### 更新 `@halo-dev/ui-plugin-bundler-kit`
 
-更新至 `2.26.0` 或更高版本：
+更新至 `2.27.0` 或更高版本：
 
 ```bash
-pnpm install @halo-dev/ui-plugin-bundler-kit@2.26.0 vite @vitejs/plugin-vue -D
+pnpm install @halo-dev/ui-plugin-bundler-kit@2.27.0 vite @vitejs/plugin-vue -D
 ```
 
 ### 更新 `vite.config.ts`

diff --git a/docs/developer-guide/plugin/extension-points/server/attachment.md b/docs/developer-guide/plugin/extension-points/server/attachment.md
@@ -41,7 +41,9 @@ public interface AttachmentHandler extends ExtensionPoint {
 - `delete` 方法用于删除附件，返回值为 `Mono<Attachment>`，其中 `Attachment` 为删除后的附件对象。
 - `getSharedURL` 方法用于获取附件的共享链接，返回值为 `Mono<URI>`，其中 `URI` 为附件的共享链接。
 - `getPermalink` 方法用于获取附件的永久链接，返回值为 `Mono<URI>`，其中 `URI` 为附件的永久链接。
-- `getThumbnailLinks` 方法用于按 `ThumbnailSize` 返回附件的缩略图链接。新实现应使用此方法提供缩略图，不要再实现已废弃的 `thumbnail-provider`（`ThumbnailProvider`）扩展点。
+- `getThumbnailLinks` 方法用于按 `ThumbnailSize` 返回附件的缩略图链接。
+
+从 Halo 2.27.0 开始，已移除自 2.22.0 起废弃的 `ThumbnailProvider` 接口及 `thumbnail-provider` 扩展点。旧插件应将缩略图能力迁移到 `AttachmentHandler.getThumbnailLinks()`，并将对应 `ExtensionDefinition` 的 `extensionPointName` 改为 `attachment-handler`。如果插件已经注册了 `AttachmentHandler` 实现，应在该实现中提供缩略图链接，并移除旧的缩略图扩展实现和注册定义。
 
 `AttachmentHandler` 对应的 `ExtensionPointDefinition` 如下：
 

diff --git a/docs/developer-guide/theme/ui-plugin.md b/docs/developer-guide/theme/ui-plugin.md
@@ -47,12 +47,14 @@ export default definePlugin({
 
 可用字段、路由和扩展点请参考 [插件 UI 入口文件](../plugin/basics/ui/entry.md)。
 
+从 `@halo-dev/ui-plugin-bundler-kit@2.27.0` 开始，两套构建工具及各自的 Vue 插件均为可选 peer 依赖。以下示例使用 2.27.0，只需安装所选工具链，并通过 `/vite` 或 `/rsbuild` 专用入口导入配置函数。构建工具升级不要求将主题的最低 Halo 版本提高到 2.27.0。
+
 ## 使用 Vite 构建
 
 安装依赖：
 
 ```bash
-pnpm install @halo-dev/ui-plugin-bundler-kit@2.26.0 vite @vitejs/plugin-vue -D
+pnpm install @halo-dev/ui-plugin-bundler-kit@2.27.0 vite @vitejs/plugin-vue -D
 ```
 
 创建构建配置：
@@ -71,7 +73,7 @@ export default viteConfig({
 安装依赖：
 
 ```bash
-pnpm install @halo-dev/ui-plugin-bundler-kit@2.26.0 @rsbuild/core @rsbuild/plugin-vue -D
+pnpm install @halo-dev/ui-plugin-bundler-kit@2.27.0 @rsbuild/core @rsbuild/plugin-vue -D
 ```
 
 创建构建配置：

diff --git a/docs/guide/faq.md b/docs/guide/faq.md
@@ -98,15 +98,15 @@ docker run \
   --name halo-1 \
   -p 8090:8090 \
   -v ~/.halo2:/root/.halo2 \
-  registry.fit2cloud.com/halo/halo-pro:2.26 \
+  registry.fit2cloud.com/halo/halo-pro:2.27 \
 
 # 第二个 Halo 容器
 docker run \
   -it -d \
   --name halo-2 \
   -p 8091:8090 \
   -v ~/.halo2_2:/root/.halo2 \
-  registry.fit2cloud.com/halo/halo-pro:2.26 \
+  registry.fit2cloud.com/halo/halo-pro:2.27 \
 ```
 
 更多 Docker 相关的教程请参考：[使用 Docker 部署 Halo](./install/docker.mdx)

diff --git a/docs/guide/install/config.md b/docs/guide/install/config.md
@@ -16,7 +16,7 @@ Halo 支持通过多种方式进行配置，目前 [Docker Compose 部署文档]
 ```yaml {5-10}
 services:
   halo:
-    image: registry.fit2cloud.com/halo/halo-pro:2.26
+    image: registry.fit2cloud.com/halo/halo-pro:2.27
     ...
     command:
       - --spring.r2dbc.url=r2dbc:pool:postgresql://halodb/halo
@@ -158,7 +158,7 @@ version: "3"
 
 services:
   halo:
-    image: registry.fit2cloud.com/halo/halo-pro:2.26
+    image: registry.fit2cloud.com/halo/halo-pro:2.27
     restart: on-failure:3
     depends_on:
       halodb:
@@ -197,7 +197,7 @@ version: "3"
 
 services:
   halo:
-    image: registry.fit2cloud.com/halo/halo-pro:2.26
+    image: registry.fit2cloud.com/halo/halo-pro:2.27
     restart: on-failure:3
     depends_on:
       halodb:

diff --git a/docs/guide/install/docker-compose.mdx b/docs/guide/install/docker-compose.mdx
@@ -49,7 +49,7 @@ mkdir ~/halo && cd ~/halo
 ```yaml {25-31,45} title="~/halo/docker-compose.yaml"
 services:
   halo:
-    image: registry.fit2cloud.com/halo/halo-pro:2.26
+    image: registry.fit2cloud.com/halo/halo-pro:2.27
     restart: on-failure:3
     depends_on:
       halodb:
@@ -110,7 +110,7 @@ networks:
 ```yaml {25-31,53} title="~/halo/docker-compose.yaml"
 services:
   halo:
-    image: registry.fit2cloud.com/halo/halo-pro:2.26
+    image: registry.fit2cloud.com/halo/halo-pro:2.27
     restart: on-failure:3
     depends_on:
       halodb:
@@ -181,7 +181,7 @@ networks:
 ```yaml {21} title="~/halo/docker-compose.yaml"
 services:
   halo:
-    image: registry.fit2cloud.com/halo/halo-pro:2.26
+    image: registry.fit2cloud.com/halo/halo-pro:2.27
     restart: on-failure:3
     volumes:
       - ./halo2:/root/.halo2
@@ -208,7 +208,7 @@ services:
 ```yaml {5,13-20} title="~/halo/docker-compose.yaml"
 services:
   halo:
-    image: registry.fit2cloud.com/halo/halo-pro:2.26
+    image: registry.fit2cloud.com/halo/halo-pro:2.27
     restart: on-failure:3
     network_mode: "host"
     volumes:
@@ -289,7 +289,7 @@ docker compose logs -f
 ```yaml {3}
 services:
   halo:
-    image: registry.fit2cloud.com/halo/halo-pro:2.26
+    image: registry.fit2cloud.com/halo/halo-pro:2.27
 ```
 
 ```bash
@@ -353,7 +353,7 @@ networks:
 
 services:
   halo:
-    image: registry.fit2cloud.com/halo/halo-pro:2.26
+    image: registry.fit2cloud.com/halo/halo-pro:2.27
     restart: on-failure:3
     volumes:
       - ./halo2:/root/.halo2

diff --git a/docs/guide/install/docker.mdx b/docs/guide/install/docker.mdx
@@ -32,7 +32,7 @@ import DockerRegistryList from "./slots/_docker-registry-list.md";
 ### 创建容器
 
 ```bash
-docker run -it -d --name halo -p 8090:8090 -v ~/.halo2:/root/.halo2 -e JVM_OPTS="-Xmx256m -Xms256m" registry.fit2cloud.com/halo/halo-pro:2.26
+docker run -it -d --name halo -p 8090:8090 -v ~/.halo2:/root/.halo2 -e JVM_OPTS="-Xmx256m -Xms256m" registry.fit2cloud.com/halo/halo-pro:2.27
 ```
 
 :::info 默认使用 H2 数据库
@@ -78,7 +78,7 @@ docker run -it -d --name halo -p 8090:8090 -v ~/.halo2:/root/.halo2 -e JVM_OPTS=
 ### 拉取新版本镜像
 
 ```bash
-docker pull registry.fit2cloud.com/halo/halo-pro:2.26
+docker pull registry.fit2cloud.com/halo/halo-pro:2.27
 ```
 
 ### 停止运行中的容器
@@ -93,7 +93,7 @@ docker rm halo
 修改版本号后，按照最初安装的方式，重新创建容器即可。
 
 ```bash
-docker run -it -d --name halo -p 8090:8090 -v ~/.halo2:/root/.halo2 -e JVM_OPTS="-Xmx256m -Xms256m" registry.fit2cloud.com/halo/halo-pro:2.26
+docker run -it -d --name halo -p 8090:8090 -v ~/.halo2:/root/.halo2 -e JVM_OPTS="-Xmx256m -Xms256m" registry.fit2cloud.com/halo/halo-pro:2.27
 ```
 
 </Steps>
diff --git a/docs/guide/install/jar-file.mdx b/docs/guide/install/jar-file.mdx
@@ -71,7 +71,7 @@ Halo 主要区分为[社区版和付费版](../prepare.md#发行版本)，这两
 :::
 
 ```bash
-wget https://dl.halo.run/release/halo-pro-2.26.0.jar -O halo.jar
+wget https://dl.halo.run/release/halo-pro-2.27.0.jar -O halo.jar
 ```
 
 ### 创建 [工作目录](../prepare#工作目录)
@@ -286,7 +286,7 @@ service halo stop
 下载新版本的 Halo 运行包，覆盖原有的运行包
 
 ```bash
-wget https://dl.halo.run/release/halo-pro-2.26.0.jar -O /home/halo/app/halo.jar
+wget https://dl.halo.run/release/halo-pro-2.27.0.jar -O /home/halo/app/halo.jar
 ```
 
 :::info Halo 运行包下载地址

diff --git a/docs/guide/install/other/nginxproxymanager.mdx b/docs/guide/install/other/nginxproxymanager.mdx
@@ -109,7 +109,7 @@ networks:
 
 services:
   halo:
-    image: registry.fit2cloud.com/halo/halo-pro:2.26
+    image: registry.fit2cloud.com/halo/halo-pro:2.27
     container_name: halo
     restart: on-failure:3
     volumes:

diff --git a/docs/guide/install/other/traefik.md b/docs/guide/install/other/traefik.md
@@ -107,7 +107,7 @@ networks:
 
 services:
   halo:
-    image: registry.fit2cloud.com/halo/halo-pro:2.26
+    image: registry.fit2cloud.com/halo/halo-pro:2.27
     container_name: halo
     restart: on-failure:3
     volumes:

diff --git a/docs/guide/install/podman.mdx b/docs/guide/install/podman.mdx
@@ -62,7 +62,7 @@ Podman 采用无守护进程的包容性架构，因此可以更安全、更简
 
 ```bash
 mkdir -p ~/.halo2
-podman run -it -d --name halo -p 8090:8090 -v ~/.halo2:/root/.halo2:Z registry.fit2cloud.com/halo/halo-pro:2.26
+podman run -it -d --name halo -p 8090:8090 -v ~/.halo2:/root/.halo2:Z registry.fit2cloud.com/halo/halo-pro:2.27
 ```
 
 :::info 默认使用 H2 数据库
@@ -108,7 +108,7 @@ podman run -it -d --name halo -p 8090:8090 -v ~/.halo2:/root/.halo2:Z registry.f
 ### 拉取新版本镜像
 
 ```bash
-podman pull registry.fit2cloud.com/halo/halo-pro:2.26
+podman pull registry.fit2cloud.com/halo/halo-pro:2.27
 ```
 
 ### 停止运行中的容器
@@ -123,7 +123,7 @@ podman rm halo
 修改版本号后，按照最初安装的方式，重新创建容器即可。
 
 ```bash
-podman run -it -d --name halo -p 8090:8090 -v ~/.halo2:/root/.halo2:Z registry.fit2cloud.com/halo/halo-pro:2.26
+podman run -it -d --name halo -p 8090:8090 -v ~/.halo2:/root/.halo2:Z registry.fit2cloud.com/halo/halo-pro:2.27
 ```
 
 </Steps>
@@ -161,7 +161,7 @@ Environment=SPRING_CONFIG_LOCATION="optional:classpath:/;optional:file:/.halo/"
 Environment=TZ=Asia/Shanghai
 Volume=/opt/podman-data/halo:/.halo:Z
 PublishPort=127.0.0.1:8090:8090
-Image=ghcr.io/halo-dev/halo:2.26
+Image=ghcr.io/halo-dev/halo:2.27
 Exec=--halo.external-url=https://localhost:8090 --spring.sql.init.platform=postgresql --spring.r2dbc.url=r2dbc:pool:postgresql://host.containers.internal:5432/my-db --spring.r2dbc.username=my-user --spring.r2dbc.password=my-password
 
 [Service]
@@ -189,7 +189,7 @@ Podman Quadlet 解析：
 
 `[Container]` 部分：
 
-- `AutoUpdate=registry`指定了自动拉取容器。假设后续 Halo 镜像支持了`latest`标签，你需要`systemctl enable --now podman-auto-update.timer`以启用容器自动更新。本文示例`ghcr.io/halo-dev/halo:2.26`，将会自动更新适用与`2.26`版本的 patch，例如您创建容器时是`2.26.1`，在官方发布`2.26.2`版本时，容器会自动更新到`2.26.2`。
+- `AutoUpdate=registry`指定了自动拉取容器。你需要`systemctl enable --now podman-auto-update.timer`以启用容器自动更新。本文示例`ghcr.io/halo-dev/halo:2.27`，将会自动更新到`2.27`系列的最新 patch 版本，例如您创建容器时是`2.27.0`，假设后续官方发布`2.27.1`版本，容器会自动更新到`2.27.1`。
 - `ContainerName=`指定了 systemd 将生成的服务名称。
 - `User=60000 Group=60000 UserNS=keep-id:uid=60000,gid=60000` 限制容器以 id 60000 的用户运行，提高安全性。注意这个 id 60000 请根据你实际想要运行的用户名来修改，可通过`id user`获得你的用户的 id.
 - `Environment=`字段指定了容器的环境变量，其中你需要注意的是`Environment=HALO_WORK_DIR="/.halo"` `Environment=SPRING_CONFIG_LOCATION="optional:classpath:/;optional:file:/.halo/"`这两个变量中的`/.halo`路径。
@@ -231,7 +231,7 @@ AutoUpdate=registry
 ContainerName=halo
 Volume=/opt/podman-data/halo:/root/.halo2:Z
 PublishPort=127.0.0.1:8090:8090
-Image=ghcr.io/halo-dev/halo:2.26
+Image=ghcr.io/halo-dev/halo:2.27
 Exec=--halo.external-url=https://localhost:8090 --spring.sql.init.platform=postgresql --spring.r2dbc.url=r2dbc:pool:postgresql://host.containers.internal:5432/my-db --spring.r2dbc.username=my-user --spring.r2dbc.password=my-password
 
 [Service]