halo-theme-WarmIsland/docs/customize/development.md

开发指南

本文档面向 WarmIsland 主题的开发者，介绍如何搭建开发环境、构建主题以及参与贡献。

环境要求

工具	最低版本	推荐版本
Node.js	18.x	20.x LTS
pnpm	8.x	9.x
Git	2.x	最新

安装 pnpm

npm install -g pnpm

验证环境

node -v    # v20.x.x
pnpm -v    # 9.x.x
git --version  # git version 2.x.x

克隆与安装

git clone https://github.com/your-username/WarmIsland.git
cd WarmIsland
pnpm install

开发模式

启动开发服务器

pnpm dev

启动后，Astro 开发服务器会在 http://localhost:4321 运行，支持热更新。

使用 Halo DevTools

WarmIsland 使用 vite-plugin-halo-theme 插件，可以与 Halo 实例联动开发：

1. 确保本地 Halo 实例正在运行
2. 在 Halo 后台安装主题的开发版本
3. 修改源码后，主题会自动重新构建并推送到 Halo

pnpm dev:halo

构建

生产构建

pnpm build

构建产物位于 dist/ 目录，包含所有模板文件和静态资源。

打包主题

pnpm package

生成 .zip 主题包，可直接在 Halo 后台上传安装。

项目结构

WarmIsland/
├── src/                          # 源代码
│   ├── components/               # Astro 组件
│   │   ├── HeroSection.astro     # Hero 首屏
│   │   ├── PostCard.astro        # 文章卡片
│   │   ├── Pagination.astro      # 分页组件
│   │   ├── TableOfContents.astro # 目录组件
│   │   ├── ReadingProgress.astro # 阅读进度条
│   │   ├── LikeButton.astro      # 点赞按钮
│   │   ├── CommentSection.astro  # 评论区
│   │   ├── Footer.astro          # 页脚
│   │   └── ...
│   ├── layouts/                  # 布局组件
│   │   ├── BaseLayout.astro      # 基础布局
│   │   └── PostLayout.astro      # 文章布局
│   ├── lib/                      # 工具库
│   │   ├── pages.ts              # 页面路由定义
│   │   └── utils.ts              # 工具函数
│   ├── pages/                    # 页面入口
│   │   ├── index.astro           # 首页
│   │   ├── post.astro            # 文章详情
│   │   ├── archives.astro        # 归档
│   │   ├── categories.astro      # 分类
│   │   ├── tags.astro            # 标签
│   │   ├── moments.astro         # 瞬间
│   │   ├── photos.astro          # 图库
│   │   ├── links.astro           # 友情链接
│   │   ├── friends.astro         # 朋友圈
│   │   ├── page.astro            # 自定义页面
│   │   ├── page_messageboard.astro # 留言板
│   │   ├── douban.astro          # 豆瓣
│   │   ├── equipments.astro      # 装备
│   │   ├── footprints.astro      # 足迹
│   │   └── steam.astro           # Steam
│   └── styles/                   # 样式文件
│       ├── main.scss             # 主样式入口
│       ├── _variables.scss       # SCSS 变量
│       ├── _colors.scss          # 颜色定义
│       ├── _typography.scss      # 排版
│       ├── _spacing.scss         # 间距
│       ├── _animations.scss      # 动画
│       ├── _mixins.scss          # 混入
│       └── components/           # 组件样式
├── templates/                    # Thymeleaf 模板（构建输出）
├── public/                       # 静态资源
│   └── assets/                   # 编译后的 CSS/JS
├── docs/                         # 文档
├── theme.yaml                    # 主题元信息
├── settings.yaml                 # 主题设置定义
├── astro.config.mjs              # Astro 配置
├── package.json                  # 项目依赖
├── tsconfig.json                 # TypeScript 配置
└── vite.config.ts                # Vite 配置

技术栈

核心框架

技术	版本	用途
Astro	5.x	静态站点生成，组件开发
vite-plugin-halo-theme	-	Halo 主题开发集成
Thymeleaf	-	Halo 服务端模板引擎

前端技术

技术	用途
Vue 3	交互组件（目录、点赞、无限滚动等）
SCSS	样式预处理
Prism.js	代码高亮
LightGallery	图片灯箱

构建工具

技术	用途
Vite	构建打包
pnpm	包管理
TypeScript	类型安全

模板语法

WarmIsland 使用 Astro 编写组件，构建后输出为 Thymeleaf 模板供 Halo 使用。

Astro 组件 → Thymeleaf 模板

Astro 组件中的前端代码会被 vite-plugin-halo-theme 转换为 Thymeleaf 模板：

---
// Astro 前置脚本
const title = "Hello";
---
<h1>{title}</h1>

转换为 Thymeleaf：

<h1 th:text="${title}">Hello</h1>

Halo Finder API

在模板中使用 Halo 的 Finder API 获取数据：

<!-- 获取文章列表 -->
<th:block th:each="post : ${postFinder.list(1, 10)}">
  <a th:href="@{${post.status.permalink}}" th:text="${post.spec.title}"></a>
</th:block>

<!-- 获取分类 -->
<th:block th:each="category : ${categoryFinder.listAll()}">
  <span th:text="${category.spec.displayName}"></span>
</th:block>

<!-- 获取标签 -->
<th:block th:each="tag : ${tagFinder.listAll()}">
  <span th:text="${tag.spec.displayName}"></span>
</th:block>

Vue 3 交互组件

需要客户端交互的组件使用 Vue 3 编写，通过 <script> 标签引入：

<div id="toc-app"></div>
<script type="module" src="/assets/js/toc.js"></script>

Docker 部署

构建镜像

docker build -t warmisland-theme .

运行

docker run -d \
  --name warmisland \
  -p 8090:8090 \
  -v ~/.halo2:/root/.halo2 \
  warmisland-theme

Docker Compose

version: '3'
services:
  halo:
    image: warmisland-theme
    ports:
      - "8090:8090"
    volumes:
      - ./halo2:/root/.halo2
    restart: unless-stopped

贡献指南

提交 Issue

• 使用 GitHub Issues 提交 Bug 报告或功能建议
• 请提供详细的复现步骤和环境信息
• 附上截图或错误日志

提交 Pull Request

1. Fork 本仓库
2. 创建特性分支：git checkout -b feature/your-feature
3. 提交更改：git commit -m 'feat: add your feature'
4. 推送分支：git push origin feature/your-feature
5. 提交 Pull Request

Commit 规范

使用 Conventional Commits 规范：

类型	说明
feat	新功能
fix	修复 Bug
docs	文档更新
style	样式调整（不影响功能）
refactor	代码重构
perf	性能优化
test	测试相关
chore	构建/工具变更

代码规范

BEM 命名

WarmIsland 使用 BEM（Block Element Modifier）命名规范，前缀为 wi-：

.wi-block
.wi-block__element
.wi-block__element--modifier

示例：

.wi-post { }                    /* Block */
.wi-post__title { }             /* Element */
.wi-post__title--large { }      /* Modifier */
.wi-post__content { }           /* Element */
.wi-post__meta { }              /* Element */
.wi-post__meta-item { }         /* Element */
.wi-post__like { }              /* Element */
.wi-post__like--active { }      /* Modifier */

SCSS 规范

• 使用 SCSS 变量（$variable）定义设计 token
• 使用 CSS 变量（--variable）暴露可覆盖的值
• 嵌套不超过 3 层
• 使用 @mixin 封装复用样式
• 使用 @include 引入混入

Vue 组件规范

• 使用 Composition API
• 使用 <script setup> 语法
• Props 使用 TypeScript 类型定义
• 事件使用 defineEmits

文件命名

类型	规范	示例
Astro 组件	PascalCase	PostCard.astro
Vue 组件	PascalCase	TableOfContents.vue
SCSS 文件	kebab-case	_variables.scss
页面文件	kebab-case	page_messageboard.astro
工具文件	camelCase	utils.ts