MacWk Halo Theme

面向软件目录、专题与内容站点的 Halo 2.x 主题

在线演示 · 下载主题 · 问题反馈

界面预览 · 核心能力 · 安装 · 配置 · 开发 · 文档

项目定位

MacWk Halo Theme 是一个以 Halo 原生服务端渲染为基础的软件内容主题。Astro 将组件化源码构建为 Thymeleaf 模板，Halo 在请求时注入真实数据，Vue Island 只负责下载与评论等必要交互。

主题既能展示 Halo 原生文章，也能消费 plugin-software 提供的软件数据、专题和公共路由。

Important

plugin-software 是独立的软件管理插件，不是为本主题定制的后端。插件拥有领域数据和公共契约，本主题只是其中一个展示层消费者。

界面预览

_{首页预览会跟随 GitHub 的明暗模式切换；实际内容、品牌与强调色均可在 Halo 中配置。}

查看更多页面：软件列表与软件详情

软件列表	软件详情

更多桌面端、移动端及明暗模式截图见视觉回归基线。

核心能力

能力	说明
Halo 原生内容	首页、文章、分类、标签、归档、独立页面和 404/500 页面
软件目录	软件列表、分类/标签筛选、排序分页、详情、版本、下载与评论
软件专题	专题列表、专题详情、装机必备、精品推荐和推荐入口
多套外观	自动、明亮、复古、护眼、海天、深邃和暗黑，可自定义强调色
渐进增强	核心内容由 SSR 输出；无 JavaScript 时仍保留主要链接与正文
页面导航	Swup 仅替换主内容区域，并避让登录、Console、API 和下载链接
SEO 与可用性	Canonical、结构化数据、动态页面 noindex、键盘交互和 reduced motion
工程化门禁	Biome、Astro Check、Vitest、资源预算、ZIP 校验、Playwright 和视觉回归

主题与插件的职责边界

`plugin-software`	本主题
软件、版本、下载源、分类、标签、专题	卡片、列表、侧栏和详情页布局
发布状态、搜索、过滤、排序和分页	网格/列表显示模式及浏览器本地偏好
Finder、公共 REST API 和主题路由	调用公共契约并渲染模板
下载登录/验证门禁与敏感字段隔离	下载面板、错误提示和交互反馈
软件评论资源与 Console 权限	评论组件的展示与挂载

getHome() / SoftwareHomeVo 保留为主题中立的首页聚合接口，用于一次取得最新、热门、推荐、评论、专题和分类数据。view=list|grid 等布局状态只属于主题，不进入插件查询参数或 Router 模型。

完整契约见软件插件契约。

安装与启用

环境要求

组件	要求
Halo	`>= 2.25.0`
plugin-software	软件页面需要；普通 Halo 内容页可不安装
Node.js / pnpm	仅源码开发需要：Node.js `>= 22.12.0`、pnpm `10.34.5`

安装主题

从 GitHub Releases 下载 frontend-macwk-halo-theme-<version>.zip。
在 Halo Console 的“外观 → 主题”中上传安装包。
启用主题并执行“重载主题配置”。
如需软件目录，安装并启用 plugin-software。
按需创建下方列出的独立页面并选择对应自定义模板。

如启用了受验证码保护的下载源，请在 plugin-software 设置中完整配置 Cloudflare Turnstile。主题只在用户选择此类下载源时加载验证组件；配置缺失或验证服务不可用时会保持关闭授权，不会绕过插件门禁。

独立页面

建议 slug	自定义模板
`about`	关于页面
`privacy`	隐私政策
`feedback`	留言反馈
`reward`	打赏支持
`genuine`	正版推荐
`must`	装机必备
`perfect`	精彩软件推荐
`recommend`	推荐应用
`special`	软件专题

开发环境可使用幂等脚本初始化这些页面：

HALO_ORIGIN=http://127.0.0.1:8099 \
HALO_USERNAME="$HALO_USERNAME" \
HALO_PASSWORD="$HALO_PASSWORD" \
pnpm setup:pages

页面与数据来源

地址	数据提供方	用途
`/`	Halo Finder + `softwareFinder`	Hero、软件、专题和文章栏目
`/archives`、文章、分类、标签	Halo	原生内容列表与详情
`/soft/{category}/p{page}`	`plugin-software`	软件列表、分类、搜索、排序和分页
`/soft/tag/{slug}/p{page}`	`plugin-software`	标签筛选的软件列表
`/soft/{slug}`	`plugin-software`	软件详情、版本、下载和评论
`/special/{slug}`	`plugin-software`	软件专题详情
`/special`、`/must`、`/perfect`、`/recommend`	Halo Page + `softwareFinder`	主题自定义软件页面
`/about`、`/privacy`、`/feedback`、`/reward`、`/genuine`	Halo Page	站点说明和运营页面

插件未安装或未启用时，主题会隐藏软件导航和 Finder 入口；主题拥有的自定义 Page 会显示降级提示，普通 Halo 内容页不受影响。插件拥有的 /soft/... 和 /special/{slug} 路由在此状态下不存在。

主题配置

所有可变内容集中在 settings.yaml：

分组	可配置内容
外观	默认配色、强调色、浏览器主题色和动画开关
品牌	Halo 站点 Logo、自定义 Logo 和站点标题
导航	主导航、顶部快捷菜单、页脚菜单和搜索提示
首页	轮播、专题、软件与文章模块及显示数量
文章	特色文章、安装必读和无封面占位图
软件	下载文字、评论、官网入口、版本数量和装机专题
运营页面	联系方式、打赏、正版推荐、维护说明和横幅
页脚与 SEO	ICP、版权、Halo 扩展位和标题后缀

修改 theme.yaml 或 settings.yaml 后，需要在 Halo Console 中重新加载主题配置。

技术架构

Astro / TypeScript 源码
          ↓ 构建
Thymeleaf 模板 + 哈希静态资源
          ↓ Halo 请求时渲染
完整 HTML + 必要的 Vue Island

src/pages/*.astro 与最终 Halo 模板名一一对应。
Astro props 和 slot 只存在于构建期；Halo 运行时数据必须保留为 th:* 表达式。
public/assets/ 会复制到 templates/assets/。
templates/ 和 dist/ 都是生成目录，禁止手工编辑。
评论与下载使用 client:load；评论数据仍在用户首次打开面板时按需获取。

项目结构

frontend-macwk-halo-theme/
├── .github/workflows/           # CI 与发布
├── audits/                      # 审查记录与性能报告
├── docs/                        # 架构、契约、开发和发布文档
├── public/assets/               # 原样发布的静态资源
├── scripts/                     # 配置、资源、预算和安装包校验
├── src/
│   ├── pages/                   # Halo 模板入口
│   ├── layouts/                 # 页面骨架
│   ├── components/              # SEO 与共享组件
│   ├── features/                # shell、home、article、software
│   ├── integrations/            # Halo 与软件插件适配层
│   ├── scripts/runtime/         # 浏览器运行时与生命周期
│   ├── lib/                     # 通用工具
│   └── styles/                  # Token、主题与功能样式
├── tests/                       # unit、contract、e2e、visual
├── templates/                   # Astro 生成，Git 忽略
├── dist/                        # 主题 ZIP，Git 忽略
├── theme.yaml
├── settings.yaml
└── package.json

完整的目录边界和参考项目对照见架构说明与优化计划。

开发与构建

corepack enable
pnpm install --frozen-lockfile
pnpm dev

pnpm dev 监听源码并重建 templates/，页面仍由 Halo 提供。开发环境建议关闭 Thymeleaf 缓存：

spring:
  thymeleaf:
    cache: false

常用命令

命令	作用
`pnpm check`	Biome、Astro、配置和 Vitest 检查
`pnpm build`	完整检查、模板构建、预算、打包和 ZIP 校验
`pnpm build:templates`	仅重建 Halo 模板
`pnpm test:e2e`	桌面/移动交互和 Swup 生命周期
`pnpm test:visual`	桌面/移动 × 浅色/深色视觉回归
`pnpm check:performance`	校验 gzip 静态资源预算
`pnpm package`	生成发布白名单主题安装包

浏览器测试需要一个已启用当前主题和软件插件的 Halo：

HALO_ORIGIN=http://127.0.0.1:8099 pnpm test:e2e
HALO_ORIGIN=http://127.0.0.1:8099 pnpm test:visual

验证插件禁用降级时，额外设置 HALO_PLUGIN_DISABLED_ORIGIN；未提供时对应测试会明确跳过。

安装包输出位置：

dist/frontend-macwk-halo-theme-<version>.zip

CI 与发布

ci.yaml 对 push 和 Pull Request 执行完整静态构建与主题打包。
cd.yaml 在 GitHub Release 发布时使用 Halo 官方工作流重新构建安装包。
真实 Halo 的交互和视觉回归测试按需在本地运行，不依赖长期维护的自托管 Runner。
Halo 应用市场发布暂未启用，配置 app-id 与 HALO_PAT 后可开启。

frontend-macwk-halo-theme