# Xiuno BBS htmx + Alpine.js 开发指南
> 本文档面向 Xiuno BBS 4.5+ 开发者，详细阐述 htmx + Alpine.js 架构的设计理念、核心原则、组件规范与实战模式。
> 最后更新：2026-06-04
---
## 目录
1. [架构概览](#1-架构概览)
2. [脚本加载顺序与依赖关系](#2-脚本加载顺序与依赖关系)
3. [七条核心原则](#3-七条核心原则)
4. [已注册 Alpine.data 组件详解](#4-已注册-alpindata-组件详解)
5. [htmx 交换策略与 morph 机制](#5-htmx-交换策略与-morph-机制)
6. [实战模式与代码示例](#6-实战模式与代码示例)
7. [常见问题与排错指南](#7-常见问题与排错指南)
8. [迁移与最佳实践清单](#8-迁移与最佳实践清单)
---
## 1. 架构概览
### 1.1 为什么选择 htmx + Alpine.js
Xiuno BBS 4.5+ 的前端架构以 **htmx** 和 **Alpine.js** 为核心，替代了传统的 jQuery 方案。这一选择基于以下考量：
| 维度 | htmx | Alpine.js |
|------|------|-----------|
| **核心职责** | 服务端交互（请求/响应/局部更新） | 前端 UI 状态管理（开关/折叠/临时验证） |
| **工作方式** | 通过 HTML 属性声明式驱动 AJAX | 通过 HTML 属性声明式驱动响应式状态 |
| **学习成本** | 极低——只需了解 HTML 属性 | 极低——Vue.js 子集语法 |
| **包体积** | ~14KB gzipped | ~15KB gzipped |
| **与后端协作** | 天然适配服务端渲染（SSR） | 不关心数据来源，只管 UI 状态 |
两者组合的核心优势：**服务端仍然掌控页面渲染权**，htmx 负责将服务端返回的 HTML 片段智能更新到页面中，Alpine.js 负责在浏览器端管理纯 UI 交互状态。无需构建 SPA，无需 API 化，无需前端路由。
### 1.2 整体架构图
```
┌─────────────────────────────────────────────────────┐
│ 浏览器端 │
│ │
│ ┌──────────────┐ ┌──────────────────────┐ │
│ │ htmx │────────▶│ idiomorph + │ │
│ │ (请求/交换) │ │ alpine-morph │ │
│ └──────┬───────┘ │ (智能 DOM diff) │ │
│ │ └──────────┬───────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────────────────────────────────────────┐ │
│ │ DOM（HTML 片段） │ │
│ │ ┌─────────────────────────────────────────┐ │ │
│ │ │ Alpine.js（x-data 管理局部 UI 状态） │ │ │
│ │ │ - likeBtn / favBtn / followBtn / ... │ │ │
│ │ └─────────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────┐ │
│ │ xiuno-modern.js（兼容层） │ │
│ │ XN.post() / XN.toast() / XN.url() / ... │ │
│ └──────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘
│
HTTP 请求
│
▼
┌─────────────────────────────────────────────────────┐
│ PHP 服务端 │
│ 路由 → 控制器 → 模板渲染 → 返回 HTML 片段 │
│ CSRF 校验 / 权限检查 / 数据查询 │
└─────────────────────────────────────────────────────┘
```
### 1.3 与 xiuno-modern.js 的关系
`xiuno-modern.js` 是 jQuery 兼容层，提供了以下关键 API：
- **`XN.post(url, data, callback)`**：发送 POST 请求，自动携带 CSRF token（从 `` 读取）
- **`XN.toast(message, type)`**：显示提示消息（success / danger / warning）
- **`XN.url(route)`**：生成站内 URL
- **`XN.$(selector)`** / **`XN.$$(selector)`**：选择器
- **其他**：DOM 操作、事件绑定、表单序列化等
Alpine.data 组件内部大量使用 `XN.post()` 进行服务端交互，这是 Alpine.js 与后端通信的标准方式。
---
## 2. 脚本加载顺序与依赖关系
### 2.1 加载顺序（严格固定）
脚本加载顺序是系统正常运行的**前提条件**，任何调整都可能导致功能异常。当前顺序在 `view/htm/header.inc.htm` 和 `view/htm/footer.inc.htm` 中定义：
```
① htmx 2.0.x view/vendor/htmx/htmx.min.js
② idiomorph 0.7.4 view/vendor/idiomorph/idiomorph-ext.min.js
③ alpine-morph 2.0.0 view/vendor/htmx-ext-alpine-morph/alpine-morph.js
④ Alpine morph 插件 view/vendor/alpinejs-morph/cdn.min.js
⑤ Alpine.js 3.x view/vendor/alpinejs/cdn.min.js （最后加载）
```
### 2.2 为什么是这个顺序
| 顺序 | 脚本 | 依赖关系 | 说明 |
|------|------|----------|------|
| ① | htmx | 无 | 核心引擎，必须最先加载 |
| ② | idiomorph | htmx | htmx 扩展，注册为 `idiomorph` 扩展，提供 DOM morph 算法 |
| ③ | alpine-morph | htmx + idiomorph + Alpine.js | htmx 扩展，桥接 idiomorph 与 Alpine.js，使 morph 操作保留 Alpine 状态 |
| ④ | Alpine morph 插件 | Alpine.js | Alpine.js 官方插件，提供 `Alpine.morph()` API |
| ⑤ | Alpine.js | 无（但 morph 插件需在其之前） | 核心引擎，最后加载以避免初始化时序问题 |
**关键理解**：`alpine-morph`（③）作为 htmx 扩展在 header 中加载，但它会在 Alpine.js 初始化后才开始工作。它依赖 `Alpine.morph()` 这个由 ④ 提供的 API。所以 ④ 必须在 ⑤ 之前，而 ③ 在 header 中注册扩展即可，htmx 会在需要时调用。
### 2.3 Body 标签配置
```html
```
各属性含义：
- **`hx-boost="true"`**：全局启用链接和表单的 htmx 增强，普通 `` 和 `` 会自动变为 htmx 请求
- **`hx-target="#body"`**：默认将响应内容注入 `#body` 元素
- **`hx-select="#body"`**：从服务端返回的完整 HTML 中只提取 `#body` 部分
- **`hx-swap="innerHTML"`**：默认交换策略为替换内部 HTML
- **`hx-ext="idiomorph, alpine-morph"`**：全局启用 idiomorph 和 alpine-morph 扩展
### 2.4 Main 标签配置
```html
```
- **`id="body"`**：与 body 标签上的 `hx-target` / `hx-select` 对应
- **`hx-swap="morph:innerHTML"`**：覆盖默认的 `innerHTML` 交换策略，使用 morph 算法进行智能 DOM diff，**保留 Alpine.js 组件状态**
### 2.5 全局 JavaScript 变量
在页面模板中，以下全局变量可供 Alpine 组件使用：
```javascript
window.uid // 当前登录用户 ID，0 表示未登录
window.__likesData // 点赞初始数据，键为 pid，如 {123: {liked: true, count: 5}}
window.__favoritesData // 收藏初始数据，键为 tid
window.__followData // 关注初始数据，键为 uid
```
---
## 3. 七条核心原则
### 原则 1：职责分离
**htmx 管服务端交互，Alpine.js 管前端 UI 状态。**
```
✅ 正确：
htmx → hx-get / hx-post / hx-boost（获取/提交数据）
Alpine → x-show / x-bind / x-on:click（控制 UI 展示/交互）
❌ 错误：
用 Alpine 的 x-init 发 AJAX 请求获取数据
用 htmx 的 hx-on:click 控制一个纯前端弹窗
```
**为什么**：htmx 的核心价值是将服务端返回的 HTML 智能插入页面，Alpine 的核心价值是管理纯前端状态。混用会导致职责不清、调试困难。
### 原则 2：禁止全局 $store
**禁止任何形式的 `Alpine.store()` 和 `$store.xxx`。**
```javascript
// ❌ 绝对禁止
Alpine.store('user', { uid: 0, username: '' });
// 模板中：$store.user.uid
// ✅ 正确：局部 x-data
```
**为什么**：全局 store 在 htmx morph 交换时会产生状态同步问题——morph 可能替换了 DOM 节点但 store 中的状态已经过时，导致 UI 与数据不一致。局部 `x-data` 随 DOM 节点创建/销毁，天然与 morph 兼容。
### 原则 3：自包含原则
**通过 htmx 动态加载的任何 HTML 片段，必须自带完整的 `x-data` 定义，不得依赖父级作用域中的 Alpine 数据。**
```html
回复
回复表单
回复
回复表单
```
**为什么**：htmx morph 交换可能重新创建 DOM 节点，Alpine.js 的作用域树会随之重建。如果片段依赖父级作用域，morph 后可能找不到预期的数据引用。
### 原则 4：必须使用 morph 交换
**需要保留状态的容器使用 `hx-swap="morph:innerHTML"` 或 `hx-swap="morph:outerHTML"`。**
```html
```
**为什么**：普通的 `innerHTML` 交换会完全替换目标元素的内容，导致所有 Alpine.js 组件状态丢失（如点赞按钮的 liked 状态会被重置）。morph 算法会对比新旧 DOM 树，只更新变化的部分，保留未变化的节点及其 Alpine 状态。
### 原则 5：时序冲突用 $nextTick
**当 Alpine 状态更新与 htmx 请求同时发生时，必须将 Alpine 状态更新包裹在 `$nextTick()` 中。**
```html
提交
处理中...
```
**为什么**：Alpine.js 的状态更新是同步的，但 htmx 的请求是异步的。如果在 htmx 请求回调中更新 Alpine 状态，可能会与 htmx 的 DOM 交换产生冲突。`$nextTick` 确保状态更新在下一个渲染周期执行，避免时序问题。
### 原则 6：Alpine.data 复用规范
**使用 `Alpine.data()` 定义可复用组件时，必须在 `alpine:init` 事件中注册。优先使用内联 `x-data`，除非多处复用同一逻辑。**
```javascript
// ✅ 正确：在 alpine:init 中注册
document.addEventListener('alpine:init', () => {
Alpine.data('likeBtn', function(pid, tid) {
return { /* ... */ };
});
});
// ❌ 错误：在 Alpine.js 加载后直接调用
Alpine.data('likeBtn', function(pid, tid) { /* ... */ });
// 可能 Alpine 还未完全初始化
```
**何时使用 Alpine.data**：
- ✅ 同一交互逻辑在多个页面/帖子中重复出现（如点赞、收藏、关注）
- ❌ 只在单个位置使用的简单状态（直接用内联 `x-data`）
### 原则 7：不确定时优先 morph + $nextTick
**遇到不确定的时序或状态保留问题，优先使用 morph 交换和 `$nextTick`，不要引入全局状态作为解决方案。**
```
问题：Alpine 状态在 htmx 交换后丢失
❌ 解决：用 Alpine.store 保存状态
✅ 解决：使用 hx-swap="morph:innerHTML"
问题：Alpine 状态更新与 htmx 交换时序冲突
❌ 解决：用全局变量中转
✅ 解决：用 $nextTick 延迟状态更新
```
---
## 4. 已注册 Alpine.data 组件详解
所有组件均在 `view/htm/footer.inc.htm` 中通过 `alpine:init` 事件注册。
### 4.1 likeBtn(pid, tid) — 点赞按钮
**功能**：帖子的点赞/取消点赞交互。
**参数**：
- `pid`：帖子 ID（Post ID）
- `tid`：主题 ID（Thread ID）
**初始数据来源**：`window.__likesData[pid]`，由服务端在页面渲染时注入。
**后端路由**：`thread-like-{tid}-{pid}`（POST）
**使用方式**：
```html
```
**行为细节**：
1. 未登录用户点击 → 跳转登录页（`user-login`）
2. 已登录用户点击 → 调用 `XN.post('thread-like-{tid}-{pid}', {})` 切换点赞状态
3. 成功时：`liked` 取反，`count` 增减
4. 失败时：显示 `XN.toast()` 错误提示
**服务端数据注入示例**（在页面模板中）：
```php
window.__likesData = window.__likesData || {};
window.__likesData[] = {
liked: ,
count:
};
```
### 4.2 favBtn(tid) — 收藏按钮
**功能**：主题的收藏/取消收藏交互。
**参数**：
- `tid`：主题 ID（Thread ID）
**初始数据来源**：`window.__favoritesData[tid]`
**后端路由**：`thread-favorite-{tid}`（POST）
**使用方式**：
```html
```
**行为细节**：
1. 未登录用户点击 → 跳转登录页
2. 已登录用户点击 → 调用 `XN.post('thread-favorite-{tid}', {})` 切换收藏状态
3. 成功时：`favorited` 取反，`count` 增减
4. 失败时：显示错误提示
### 4.3 followBtn(followUid) — 关注用户
**功能**：关注/取消关注其他用户。
**参数**：
- `followUid`：被关注用户的 ID
**初始数据来源**：`window.__followData[followUid]`（布尔值）
**后端路由**：`user-follow-{followUid}`（POST）
**使用方式**：
```html
```
**行为细节**：
1. 未登录用户点击 → 跳转登录页
2. 已登录用户点击 → 调用 `XN.post('user-follow-{followUid}', {})` 切换关注状态
3. 成功时：`followed` 取反
4. 失败时：显示错误提示
**注意**：此组件没有 `count` 属性，因为关注操作通常不需要显示计数。
### 4.4 forumFollowBtn(fid, initFollowed) — 关注版块
**功能**：关注/取消关注版块。
**参数**：
- `fid`：版块 ID（Forum ID）
- `initFollowed`：初始关注状态（布尔值，直接传入而非从全局变量读取）
**后端路由**：
- 关注：`forum-follow`（POST，参数 `{fid: fid}`）
- 取消关注：`forum-unfollow`（POST，参数 `{fid: fid}`）
**使用方式**：
```html
```
**行为细节**：
1. 未登录用户点击 → 跳转登录页
2. 已登录用户点击 → 根据 `followed` 状态调用不同路由
- 未关注 → `XN.post('forum-follow', {fid: fid})`
- 已关注 → `XN.post('forum-unfollow', {fid: fid})`
3. 成功时：`followed` 取反，显示成功提示
4. 失败时：显示错误提示
**与其他组件的区别**：`forumFollowBtn` 的初始状态通过参数 `initFollowed` 直接传入，而非从 `window.__followData` 读取。这是因为版块关注通常只在版块详情页出现，不需要批量预加载数据。
### 4.5 组件注册源码
所有组件在 `footer.inc.htm` 中统一注册：
```javascript
document.addEventListener('alpine:init', () => {
// 点赞按钮
Alpine.data('likeBtn', function(pid, tid) {
var initData = (window.__likesData && window.__likesData[pid]) || {liked: false, count: 0};
return {
liked: initData.liked || false,
count: initData.count || 0,
toggle: function() {
if(!window.uid || window.uid === 0) {
window.location.href = XN.url('user-login');
return;
}
var self = this;
XN.post('thread-like-' + tid + '-' + pid, {}, function(code, msg) {
if(code === 0) {
self.liked = !self.liked;
self.count = self.liked ? self.count + 1 : self.count - 1;
} else {
if(typeof XN.toast === 'function') XN.toast(msg || '操作失败', 'danger');
}
});
}
};
});
// 收藏按钮
Alpine.data('favBtn', function(tid) {
var initData = (window.__favoritesData && window.__favoritesData[tid]) || {favorited: false, count: 0};
return {
favorited: initData.favorited || false,
count: initData.count || 0,
toggle: function() {
if(!window.uid || window.uid === 0) {
window.location.href = XN.url('user-login');
return;
}
var self = this;
XN.post('thread-favorite-' + tid, {}, function(code, msg) {
if(code === 0) {
self.favorited = !self.favorited;
self.count = self.favorited ? self.count + 1 : self.count - 1;
} else {
if(typeof XN.toast === 'function') XN.toast(msg || '操作失败', 'danger');
}
});
}
};
});
// 关注用户
Alpine.data('followBtn', function(followUid) {
var initFollowed = (window.__followData && window.__followData[followUid]) || false;
return {
followed: initFollowed,
toggle: function() {
if(!window.uid || window.uid === 0) {
window.location.href = XN.url('user-login');
return;
}
var self = this;
XN.post('user-follow-' + followUid, {}, function(code, msg) {
if(code === 0) {
self.followed = !self.followed;
} else {
if(typeof XN.toast === 'function') XN.toast(msg || '操作失败', 'danger');
}
});
}
};
});
// 关注版块
Alpine.data('forumFollowBtn', function(fid, initFollowed) {
return {
followed: initFollowed || false,
toggle: function() {
if(!window.uid || window.uid === 0) {
window.location.href = XN.url('user-login');
return;
}
var self = this;
var url = self.followed ? 'forum-unfollow' : 'forum-follow';
XN.post(url, {fid: fid}, function(code, msg) {
if(code === 0) {
self.followed = !self.followed;
if(typeof XN.toast === 'function') XN.toast(self.followed ? '关注成功' : '已取消关注', 'success');
} else {
if(typeof XN.toast === 'function') XN.toast(msg || '操作失败', 'danger');
}
});
}
};
});
});
```
---
## 5. htmx 交换策略与 morph 机制
### 5.1 三种交换策略对比
| 策略 | 语法 | 行为 | Alpine 状态 | 适用场景 |
|------|------|------|-------------|----------|
| `innerHTML` | `hx-swap="innerHTML"` | 完全替换目标元素的子节点 | ❌ 丢失 | 无状态内容更新 |
| `morph:innerHTML` | `hx-swap="morph:innerHTML"` | 用 morph 算法 diff 后更新子节点 | ✅ 保留 | 有状态组件的局部更新 |
| `morph:outerHTML` | `hx-swap="morph:outerHTML"` | 用 morph 算法 diff 后替换目标元素本身 | ✅ 保留 | 需要替换整个容器时 |
### 5.2 morph 算法工作原理
idiomorph 是 htmx 官方的 morph 扩展，其核心算法流程：
```
1. 接收：旧 DOM 树（当前页面）+ 新 DOM 树（服务端返回）
2. 匹配：通过 id 属性和元素位置建立新旧节点对应关系
3. Diff：对比对应节点的属性、文本、子节点差异
4. Patch：只更新变化的部分，保留未变化的节点
5. 结果：Alpine.js 绑定的 DOM 节点如果未被替换，其状态自然保留
```
**关键**：morph 算法依赖 `id` 属性进行节点匹配。如果目标区域内的元素有稳定的 `id`，morph 效果最佳。
### 5.3 alpine-morph 扩展的作用
`alpine-morph` 是连接 idiomorph 和 Alpine.js 的桥梁。当 morph 操作需要移除一个 Alpine 组件节点时，alpine-morph 会：
1. 在移除前保存该节点的 Alpine 状态
2. 如果新 DOM 中有对应的节点（通过 id 匹配），将保存的状态恢复到新节点
3. 确保组件的 `x-data` 值不会因 morph 操作而重置
### 5.4 全局导航与局部更新
**全局导航**（页面切换）：
```html
```
当用户点击链接时：
1. `hx-boost` 拦截链接点击，转为 htmx AJAX 请求
2. 服务端返回完整 HTML 页面
3. `hx-select="#body"` 从中提取 `` 的内容
4. `main` 上的 `hx-swap="morph:innerHTML"` 使用 morph 算法更新内容
5. 导航栏、侧边栏等不变的部分保持不变，Alpine 状态保留
**局部更新**（组件级交互）：
```html
```
### 5.5 交换策略选择决策树
```
需要更新 DOM？
├── 目标区域包含 Alpine 组件？
│ ├── 是 → 使用 morph:innerHTML 或 morph:outerHTML
│ └── 否 → 使用 innerHTML（更简单，性能略好）
└── 不需要 → 不用 htmx，用纯 Alpine 状态切换
```
---
## 6. 实战模式与代码示例
### 6.1 模式一：纯前端交互（无服务端通信）
适用场景：折叠面板、弹窗开关、Tab 切换等纯 UI 交互。
```html
展开详情
这里是折叠的详细内容...
```
```html
基本信息
统计数据
基本信息内容
统计数据内容
```
**要点**：纯前端交互不需要 htmx，只用 Alpine.js 的 `x-data` 管理状态即可。
### 6.2 模式二：服务端交互 + 状态保留（Alpine.data 组件）
适用场景：点赞、收藏、关注等需要服务端确认且需要保留 UI 状态的交互。
```html
```
**要点**：
- 使用 `Alpine.data` 注册的组件名作为 `x-data` 的值
- 传入参数由 PHP 模板渲染
- 组件内部通过 `XN.post()` 与服务端通信
- 状态由组件自身管理，morph 交换后保留
### 6.3 模式三：htmx 局部刷新 + Alpine 状态
适用场景：提交表单后刷新列表区域，同时保留其他组件的状态。
```html
评论列表
发表评论
```
**要点**：
- 表单提交后，服务端返回更新后的评论列表 HTML
- `hx-swap="morph:innerHTML"` 确保 morph 更新，保留已有评论的点赞状态
- 每个评论的 `id="post-{pid}"` 帮助 morph 算法精确匹配节点
### 6.4 模式四：htmx 加载动态片段
适用场景：点击按钮加载一个弹窗、表单或详情面板。
```html
查看详情
```
**服务端返回的片段**（必须自包含）：
```html
更多信息
创建时间：
```
**要点**：
- 片段自带完整的 `x-data`，不依赖父级作用域（原则 3）
- 使用 `morph:innerHTML` 交换，保留目标区域中已有组件的状态
### 6.5 模式五：创建新的 Alpine.data 组件
适用场景：需要复用的交互逻辑，如投票、举报、分享等。
**步骤 1：在 footer.inc.htm 的 `alpine:init` 事件中注册组件**
```javascript
document.addEventListener('alpine:init', () => {
// ... 已有组件注册 ...
// 新增：举报按钮组件
Alpine.data('reportBtn', function(type, id) {
return {
showForm: false,
reason: '',
submitted: false,
toggleForm: function() {
if(!window.uid || window.uid === 0) {
window.location.href = XN.url('user-login');
return;
}
this.showForm = !this.showForm;
},
submit: function() {
if(!this.reason.trim()) {
XN.toast('请填写举报原因', 'warning');
return;
}
var self = this;
XN.post('report-create', {
type: type,
id: id,
reason: self.reason
}, function(code, msg) {
if(code === 0) {
self.submitted = true;
self.showForm = false;
XN.toast('举报已提交', 'success');
} else {
XN.toast(msg || '操作失败', 'danger');
}
});
}
};
});
});
```
**步骤 2：在模板中使用**
```html
举报
提交
已举报
```
### 6.6 模式六：表单提交 + htmx 验证
适用场景：需要服务端验证的表单，如注册、发帖、修改资料。
```html
昵称
签名
保存修改
保存中...
```
**要点**：
- `x-on:htmx:before-request` / `x-on:htmx:after-request` 监听 htmx 事件
- `$nextTick` 确保状态更新在正确的渲染周期（原则 5）
- `x-bind:disabled` 根据状态禁用按钮，防止重复提交
- CSRF token 通过 `CsrfService::input()` 自动包含
---
## 7. 常见问题与排错指南
### 7.1 Alpine 状态在 htmx 交换后丢失
**症状**：点击链接导航后，之前点赞/收藏的状态被重置。
**原因**：交换策略不是 morph。
**排查**：
```html
```
**解决**：确保 `` 上设置了 `hx-swap="morph:innerHTML"`，同时 body 标签上声明了 `hx-ext="idiomorph, alpine-morph"`。
### 7.2 htmx 加载的片段中 Alpine 不生效
**症状**：通过 htmx 加载的 HTML 片段中，`x-data` / `x-show` 等 Alpine 指令不工作。
**原因**：片段在 Alpine.js 初始化之后才插入 DOM，Alpine 没有自动初始化新节点。
**排查**：检查是否启用了 alpine-morph 扩展。
**解决**：
1. 确认 body 标签上有 `hx-ext="idiomorph, alpine-morph"`
2. 确认 alpine-morph 脚本已正确加载
3. 如果问题仍存在，手动触发 Alpine 初始化：
```javascript
// 在 htmx 交换完成后触发
document.body.addEventListener('htmx:afterSettle', function(event) {
// Alpine.js 通常会自动处理，但如果需要手动触发：
Alpine.initTree(event.target);
});
```
### 7.3 $nextTick 相关的闪烁问题
**症状**：状态切换时出现短暂的闪烁（如按钮先变灰再变回来）。
**原因**：Alpine 状态更新和 DOM 渲染的时序不一致。
**解决**：
```html
加载中...
```
### 7.4 CSRF Token 失效
**症状**：POST 请求返回 403 或 CSRF 验证失败。
**原因**：页面长时间未刷新，CSRF token 过期。
**排查**：
```javascript
// 检查 meta 标签中的 token
console.log(document.querySelector('meta[name="csrf-token"]')?.content);
```
**解决**：
1. `XN.post()` 会自动从 `` 读取 token
2. 如果 token 过期，需要刷新页面获取新 token
3. 可以在 htmx 请求中配置自动刷新：
```javascript
document.body.addEventListener('htmx:responseError', function(event) {
if(event.detail.xhr.status === 403) {
// CSRF 验证失败，刷新页面
window.location.reload();
}
});
```
### 7.5 morph 交换导致意外的 DOM 变化
**症状**：morph 交换后，某些元素被意外修改或移动。
**原因**：morph 算法依赖 id 属性进行节点匹配，如果 id 缺失或重复，匹配会出错。
**解决**：
1. **确保关键元素有唯一 id**：
```html
...
...
```
2. **避免 id 重复**：
```html
...
...
```
3. **morph 调试**：在浏览器控制台启用 idiomorph 调试：
```javascript
htmx.config.debug = true;
```
### 7.6 htmx boost 与普通链接的冲突
**症状**：某些链接不希望被 htmx boost 拦截，但被拦截了。
**解决**：
```html
外部链接
这个区域内的链接不被 boost
```
### 7.7 Alpine 组件参数传递错误
**症状**：组件接收到的参数不是预期的值。
**常见错误**：
```html
```
### 7.8 清理缓存后仍看到旧模板
**症状**：修改模板后，页面上仍显示旧内容。
**原因**：Xiuno BBS 的模板编译缓存存储在 `tmp/` 目录。
**解决**：
```bash
# 清理 tmp 目录下的编译缓存
rm -rf tmp/*.php
```
或在后台手动清理缓存。修改 CSS 后还需要浏览器硬刷新（Ctrl+F5 / Cmd+Shift+R）。
---
## 8. 迁移与最佳实践清单
### 8.1 从 jQuery 迁移到 htmx + Alpine.js
| jQuery 模式 | htmx + Alpine.js 模式 | 说明 |
|-------------|----------------------|------|
| `$.ajax({url, method, data, success})` | `hx-post` + `hx-target` + `hx-swap` | htmx 声明式替代命令式 AJAX |
| `$.post(url, data, callback)` | `XN.post(url, data, callback)` | 兼容层 API，用于 Alpine 组件内部 |
| `$(selector).show() / .hide()` | `x-show` | Alpine 声明式控制可见性 |
| `$(selector).addClass() / .removeClass()` | `x-bind:class` | Alpine 声明式 class 绑定 |
| `$(selector).on('click', handler)` | `x-on:click` | Alpine 声明式事件绑定 |
| `$(selector).html(content)` | `hx-get` + `hx-swap="morph:innerHTML"` | htmx 从服务端获取并更新 |
| `$(form).serialize()` | htmx 自动序列化表单 | htmx 原生支持表单提交 |
| `$(selector).val()` | `x-model` | Alpine 双向数据绑定 |
### 8.2 新功能开发检查清单
开发新功能时，请按以下清单逐项确认：
- [ ] **职责分离**：服务端交互用 htmx，纯 UI 状态用 Alpine，不混用
- [ ] **无全局 store**：所有 Alpine 数据在局部 `x-data` 中定义，不使用 `Alpine.store()`
- [ ] **自包含**：htmx 动态加载的片段自带完整 `x-data`，不依赖父级作用域
- [ ] **morph 交换**：有 Alpine 组件的区域使用 `hx-swap="morph:innerHTML"` 或 `morph:outerHTML`
- [ ] **CSRF 防护**：POST 表单包含 ``
- [ ] **XSS 防护**：输出用户内容使用 ``
- [ ] **登录检查**：需要登录的操作先检查 `window.uid`，未登录则跳转登录页
- [ ] **错误处理**：服务端返回非 0 code 时，使用 `XN.toast()` 显示错误提示
- [ ] **唯一 id**：morph 目标区域内的关键元素设置唯一 `id` 属性
- [ ] **缓存清理**：修改模板后清理 `tmp/` 目录
- [ ] **脚本顺序**：不修改 header.inc.htm 和 footer.inc.htm 中的脚本加载顺序
### 8.3 新建 Alpine.data 组件的规范
当需要创建新的可复用组件时，遵循以下规范：
**命名规范**：
- 使用 camelCase 命名：`likeBtn`、`favBtn`、`followBtn`
- 名称应体现功能 + UI 类型：`xxxBtn`（按钮）、`xxxForm`（表单）、`xxxPanel`（面板）
**参数规范**：
- 第一个参数通常是实体 ID（如 `pid`、`tid`、`fid`、`uid`）
- 初始状态优先从 `window.__xxxData` 全局变量读取（服务端预注入）
- 如果只在单个页面使用，可以直接传参（如 `forumFollowBtn(fid, initFollowed)`）
**结构规范**：
```javascript
Alpine.data('componentName', function(param1, param2) {
// 1. 读取初始数据
var initData = (window.__componentData && window.__componentData[param1]) || {key: defaultValue};
return {
// 2. 声明响应式状态
state1: initData.key || defaultValue,
state2: false,
// 3. 定义方法
toggle: function() {
// 3a. 登录检查
if(!window.uid || window.uid === 0) {
window.location.href = XN.url('user-login');
return;
}
// 3b. 服务端交互
var self = this;
XN.post('route-name', {param: param1}, function(code, msg) {
if(code === 0) {
// 3c. 更新状态
self.state1 = !self.state1;
} else {
// 3d. 错误提示
if(typeof XN.toast === 'function') XN.toast(msg || '操作失败', 'danger');
}
});
}
};
});
```
**注册位置**：在 `view/htm/footer.inc.htm` 的 `alpine:init` 事件回调中，与已有组件放在一起。
### 8.4 htmx 属性速查
| 属性 | 作用 | 示例 |
|------|------|------|
| `hx-get` | 发送 GET 请求 | `hx-get="/api/data"` |
| `hx-post` | 发送 POST 请求 | `hx-post="/api/submit"` |
| `hx-put` | 发送 PUT 请求 | `hx-put="/api/update"` |
| `hx-delete` | 发送 DELETE 请求 | `hx-delete="/api/delete"` |
| `hx-target` | 指定响应内容的目标元素 | `hx-target="#result"` |
| `hx-select` | 从响应中提取指定部分 | `hx-select="#content"` |
| `hx-swap` | 指定交换策略 | `hx-swap="morph:innerHTML"` |
| `hx-boost` | 增强链接和表单 | `hx-boost="true"` |
| `hx-trigger` | 指定触发条件 | `hx-trigger="click"` |
| `hx-include` | 包含额外表单数据 | `hx-include="#extra-data"` |
| `hx-params` | 过滤请求参数 | `hx-params="name,email"` |
| `hx-confirm` | 显示确认对话框 | `hx-confirm="确定删除？"` |
| `hx-indicator` | 指定加载指示器 | `hx-indicator="#spinner"` |
| `hx-disable` | 禁用 htmx 处理 | `hx-disable` |
| `hx-ext` | 启用扩展 | `hx-ext="idiomorph, alpine-morph"` |
### 8.5 Alpine.js 指令速查
| 指令 | 作用 | 示例 |
|------|------|------|
| `x-data` | 声明组件数据作用域 | `x-data="{ open: false }"` |
| `x-show` | 控制元素可见性（display） | `x-show="open"` |
| `x-bind` | 动态绑定属性 | `x-bind:class="active ? 'on' : 'off'"` |
| `x-on` | 绑定事件监听器 | `x-on:click="open = !open"` |
| `x-model` | 双向数据绑定 | `x-model="username"` |
| `x-text` | 设置文本内容 | `x-text="count"` |
| `x-html` | 设置 HTML 内容 | `x-html="content"` |
| `x-if` | 条件渲染（需 `XIUNOX版本发布地址：https://xiuno.xcxgy.cn