MoonEdge

EsurfingGo 技术解析：中国电信校园网认证与保活机制

Fri, 28 Aug 2026 00:00:00 GMT

EsurfingGo 技术解析：中国电信校园网认证与保活机制#

摘要#

EsurfingGo 是一个使用 Go 语言实现的中国电信天翼校园网（ESurfing）自动认证客户端。它能够在检测到强制门户（Captive Portal）后自动完成登录，并通过周期性心跳维持在线状态，支持断线自动重连与多网卡绑定。本文从源码层面详细解析其网络检测、会话加密、票据获取、登录认证与心跳保活的完整技术流程。

1. 项目概述#

1.1 背景#

在许多高校和公共场所，中国电信提供的校园网接入采用 Web Portal 认证方式。用户连接 Wi-Fi 或有线网络后，首次访问互联网会被重定向到认证页面，需要手动输入账号密码登录。EsurfingGo 将该过程自动化，适用于路由器、服务器或个人电脑长期挂机场景。

1.2 核心功能#

自动门户检测：通过访问小米 captive 探测地址判断网络状态。
自动认证：解析 portal 页面配置，完成加密登录。
心跳保活：按服务端指定间隔发送心跳，断线后自动重连。
多拨支持：可绑定指定网络接口，实现多网卡同时在线。
跨平台部署：Go 编译为单文件二进制，支持 Windows、Linux、macOS 及 ARM 路由器。

1.3 依赖#

go.mod

1
require (
2
    github.com/emmansun/gmsm v0.41.1  // 国密 SM4 / ZUC
3
    github.com/google/uuid v1.6.0      // UUID 生成
4
)

2. 项目结构#

1
.
2
├── main.go              // 程序入口、命令行解析、信号处理
3
├── client.go            // 认证主循环与登录逻辑
4
├── session.go           // ZSM 解析与加密会话管理
5
├── states.go            // 线程安全全局状态
6
├── constants.go         // 常量定义
7
├── iface.go             // 网络接口列举与绑定
8
├── network/
9
│   ├── client.go        // HTTP 客户端与请求封装
10
│   └── connectivity.go  // 强制门户检测与短信验证码
11
├── cipher/
12
│   ├── cipher.go        // 加密算法工厂
13
│   ├── keydata.go       // 各算法密钥
14
│   └── ...              // AES、3DES、SM4、ZUC、ModXTEA 实现
15
├── utils/               // 工具函数
16
└── model/               // 数据模型

展开收起

3. 认证整体流程#

认证流程可以概括为五个阶段：

门户检测：判断当前是否已联网，或是否需要认证。
配置解析：从 portal 页面提取认证接口地址、用户 IP、AC IP 等。
会话初始化：向服务端请求 ZSM 数据，确定本次加密算法。
票据获取：使用加密会话请求 ticket。
登录与保活：携带 ticket 登录，获取心跳地址后周期性保活。

1
启动
2
  │
3
  ▼
4
访问 generate_204
5
  │
6
  ├── HTTP 204 ────────────────► 已联网，轮询检测
7
  │
8
  └── HTML / 重定向 ───────────► 解析 portal 配置
9
            │
10
            ▼
11
      提取 auth-url、ticket-url、userIp、acIp
12
            │
13
            ▼
14
      请求 ZSM，初始化加密会话
15
            │
16
            ▼
17
      getTicket ──► login ──► 获取 keep-url / term-url
18
            │
19
            ▼
20
      心跳保活（失败则回到检测阶段）

展开收起

4. 强制门户检测#

4.1 探测原理#

客户端使用小米标准的 Captive Portal 探测 URL：

1
const CaptiveURL = "http://connect.rom.miui.com/generate_204"

该地址设计为：

如果设备已联网，返回 HTTP 204 No Content。
如果设备处于强制门户网络，会被重定向到认证页面，返回 HTML。

4.2 代码实现#

检测逻辑位于 network/connectivity.go:56 的 DetectConfigWithClient：

1
func DetectConfigWithClient(httpClient *http.Client, state StateProvider, verbose bool) ConfigResult

主要步骤：

发送 GET 请求到 captiveURL，携带 User-Agent、Accept、Client-ID 头。
如果返回 204，直接认为已联网。
如果返回 HTML，尝试在页面内容中定位门户配置：

//config.campus.js.chinatelecom.com

1
<config>
2
    <auth-url>...</auth-url>
3
    <ticket-url>...</ticket-url>
4
    <funcfg>...</funcfg>
5
</config>
6
//config.campus.js.chinatelecom.com-->

如果页面没有直接返回配置，可能是 JS 跳转，代码会解析 location.href="..." 等模式并跟随，最多尝试 6 次。

4.3 提取关键信息#

从 ticket-url 的 query 参数中解析用户 IP 和 AC IP：

1
parsedURL, _ := url.Parse(result.TicketURL)
2
result.UserIP = parsedURL.Query().Get("wlanuserip")
3
result.AcIP   = parsedURL.Query().Get("wlanacip")

同时从 HTTP 响应头或 portal 配置中提取 CDC-Area、CDC-SchoolId、CDC-Domain，用于后续请求路由。

5. 短信验证码流程#

部分学校账号登录需要短信验证码。client.go:177 的 checkSMSVerify 函数处理该逻辑：

1
if network.CheckVerifyCodeStatus(...) && network.GetVerifyCode(...) {
2
    log.Println("This login requires a SMS verification code.")
3
    // 从标准输入读取验证码
4
}

两个网络接口定义在 network/connectivity.go:379：

CheckVerifyCodeStatus：查询是否需要验证码。
GetVerifyCode：触发服务端下发短信。

请求体为 JSON：

1
{
2
  "schoolid": "...",
3
  "username": "...",
4
  "timestamp": "172...",
5
  "authenticator": "..."
6
}

其中 authenticator 的计算方式为：

1
hash := md5.Sum([]byte(schoolID + timestamp + "Eshore!@#"))
2
authenticator := strings.ToUpper(hex.EncodeToString(hash[:]))

这是一个简单的时间戳 + 共享密钥的校验机制。

6. 加密会话初始化（ZSM）#

6.1 什么是 ZSM#

ZSM 是服务端返回的一段二进制数据，包含了本次连接使用的加密算法标识（algoID）和密钥信息。客户端解析后创建对应的加解密器。

6.2 请求 ZSM#

client.go:195：

1
body, err := network.PostRaw(
2
    c.httpClient,
3
    c.states.GetTicketURL(),
4
    c.states.GetAlgoID(), // 初始为 "00000000-0000-0000-0000-000000000000"
5
    c.states,
6
)
7
c.session.Initialize(body)

6.3 ZSM 解析#

session.go:31 的 load 方法解析二进制格式：

1
[0..3]        4 字节头部
2
[3]           1 字节 keyLen
3
[4..4+keyLen] 密钥数据
4
[...]         分隔符 '$'
5
[...]         36 字节 algoID（UUID 字符串）
6
[...]         ']' 字符
7
[...]         后续数据

解析出 algoID 后，通过 cipher.NewCipher(algoID) 创建算法实例。

6.4 支持的加密算法#

cipher/cipher.go 实现了工厂模式，支持 9 种算法：

算法 UUID	算法
`CAFBCBAD-B6E7-4CAB-8A67-14D39F00CE1E`	AES-CBC
`A474B1C2-3DE0-4EA2-8C5F-7093409CE6C4`	AES-ECB
`5BFBA864-BBA9-42DB-8EAD-49B5F412BD81`	3DES-CBC
`6E0B65FF-0B5B-459C-8FCE-EC7F2BEA9FF5`	3DES-ECB
`B809531F-0007-4B5B-923B-4BD560398113`	ZUC-128
`F3974434-C0DD-4C20-9E87-DDB6814A1C48`	SM4-CBC
`ED382482-F72C-4C41-A76D-28EEA0F1F2AF`	SM4-ECB
`B3047D4E-67DF-4864-A6A5-DF9B9E525C79`	ModXTEA
`C32C68F9-CA81-4260-A329-BBAFD1A9CCD1`	ModXTEA-XTEAIV

密钥数据硬编码在 cipher/keydata.go 中。

6.5 双重 AES-CBC 示例#

以 AES-CBC 为例，cipher/aescbc.go:41：

1
func (a *AESCBC) Encrypt(text string) string {
2
    r1 := a.aesEncrypt([]byte(text), a.key1)
3
    r2 := a.aesEncrypt(r1, a.key2)
4
    return hexEncode(r2)
5
}

即先用 key1 加密一次，再用 key2 加密一次，最后返回大写十六进制字符串。解密则反向操作。

7. 票据获取（getTicket）#

7.1 请求 XML#

client.go:207 构造如下 XML：

1
<?xml version="1.0" encoding="utf-8"?>
2
<request>
3
    <user-agent>CCTP/android64_vpn/2093</user-agent>
4
    <client-id>%s</client-id>
5
    <local-time>%s</local-time>
6
    <host-name>%s</host-name>
7
    <ipv4>%s</ipv4>
8
    <ipv6></ipv6>
9
    <mac>%s</mac>
10
    <ostag>%s</ostag>
11
    <gwip>%s</gwip>
12
</request>

填充字段：

client-id：随机生成的 UUID。
local-time：北京时间格式化字符串。
host-name / ostag：随机 10 位字符串。
ipv4：从 ticket-url 解析出的 wlanuserip。
mac：随机生成的 MAC 地址。
gwip：从 ticket-url 解析出的 wlanacip。

7.2 加密传输#

1
encrypted, _ := c.session.Encrypt(payload)
2
data, _ := network.Post(c.httpClient, c.states.GetTicketURL(), encrypted, c.states, nil)
3
decrypted, _ := c.session.Decrypt(data)
4
ticket := extractXMLTag(decrypted, "ticket")

请求体是十六进制密文字符串，响应也是十六进制密文，解密后提取 <ticket>。

8. 登录认证（login）#

8.1 请求 XML#

client.go:250：

1
<?xml version="1.0" encoding="utf-8"?>
2
<request>
3
    <user-agent>CCTP/android64_vpn/2093</user-agent>
4
    <client-id>%s</client-id>
5
    <ticket>%s</ticket>
6
    <local-time>%s</local-time>
7
    <userid>%s</userid>
8
    <passwd>%s</passwd>
9
    <verify>%s</verify>  <!-- 可选 -->
10
</request>

用户名、密码、短信验证码会做 XML 转义，防止 &、< 等字符破坏 XML 结构。

8.2 解析登录响应#

解密后提取三个关键字段：

1
c.keepURL   = extractXMLTag(decrypted, "keep-url")
2
c.termURL   = extractXMLTag(decrypted, "term-url")
3
c.keepRetry = extractXMLTag(decrypted, "keep-retry")

8.3 登录成功判定#

client.go:165：

1
if c.keepURL == "" {
2
    log.Println("[Client] KeepUrl is empty, login may have failed.")
3
    c.session.Free()
4
    c.states.SetRunning(false)
5
    return
6
}
7

8
c.tick = time.Now().UnixMilli()
9
c.states.SetLogged(true)

只有服务端返回了 keep-url，才认为登录成功并进入心跳阶段。

9. 心跳保活机制#

9.1 触发逻辑#

client.go:57 主循环中：

1
if c.session.IsInitialized() && c.states.IsLogged() {
2
    nowMs := time.Now().UnixMilli()
3
    retryMs, err := strconv.ParseInt(c.keepRetry, 10, 64)
4
    if err == nil && retryMs > 0 && nowMs - c.tick >= retryMs * 1000 {
5
        if err := c.heartbeat(c.states.GetTicket()); err != nil {
6
            c.states.SetLogged(false)
7
            c.statusChanged = true
8
            continue
9
        }
10
        c.tick = time.Now().UnixMilli()
11
    }
12
    time.Sleep(1 * time.Second)
13
    continue
14
}

每秒检查一次。
当距离上次心跳或登录超过 keep-retry 秒时，触发心跳。
心跳失败则重置登录状态，下一次循环重新进入检测和认证流程，实现自动重连。

9.2 心跳请求体#

client.go:302：

1
<?xml version="1.0" encoding="utf-8"?>
2
<request>
3
    <user-agent>CCTP/android64_vpn/2093</user-agent>
4
    <client-id>%s</client-id>
5
    <local-time>%s</local-time>
6
    <host-name>%s</host-name>
7
    <ipv4>%s</ipv4>
8
    <ticket>%s</ticket>
9
    <ipv6></ipv6>
10
    <mac>%s</mac>
11
    <ostag>%s</ostag>
12
</request>

心跳使用 ticket 作为身份凭证，不再携带用户名密码。

9.3 动态心跳间隔#

client.go:337：

1
interval := extractXMLTag(decrypted, "interval")
2
if interval != "" {
3
    c.keepRetry = interval
4
}

服务端可以在心跳响应中下发新的 <interval>，客户端会更新下一次心跳间隔。

10. HTTP 请求封装#

所有认证相关 POST 都经过 network/client.go:179 的 Post() 或 PostRaw()，统一封装请求头：

请求头	来源/含义
`User-Agent`	`CCTP/android64_vpn/2093`
`Accept`	固定 Accept 字符串
`Content-Type`	`application/x-www-form-urlencoded`
`CDC-Checksum`	请求体 MD5 大写十六进制
`Client-ID`	`states.GetClientID()`
`Algo-ID`	`states.GetAlgoID()`
`CDC-SchoolId`	学校路由 ID
`CDC-Domain`	域名路由
`CDC-Area`	区域路由

10.1 重定向拦截器#

network/client.go:34 的 redirectInterceptor 自定义处理重定向：

读取响应头中的 CDC-Area、CDC-SchoolId、CDC-Domain 并写入状态。
后续请求自动带上这些头，确保路由正确。
最多跟随 5 次重定向。

11. 网卡绑定与多拨#

11.1 列出网卡#

iface.go:19 的 ListNetworkInterfaces() 使用 Go 标准库 net.Interfaces()，过滤掉回环接口和未启用接口。

11.2 绑定指定网卡#

iface.go:72 的 NewBoundHTTPTransport()：

根据网卡名获取接口。
获取接口上第一个 IPv4 地址。
构造 net.Dialer，设置 LocalAddr 为该 IPv4。
所有 HTTP 连接的 TCP 连接都从该地址发起。

这种方式跨平台有效，不依赖操作系统特定的 socket option。

12. 安全下线#

main.go:97 注册信号监听：

1
sigCh := make(chan os.Signal, 1)
2
signal.Notify(sigCh, syscall.SIGINT, syscall.SIGTERM)
3
go func() {
4
    <-sigCh
5
    if session.IsInitialized() && states.IsLogged() {
6
        client.Term()
7
        session.Free()
8
    }
9
    os.Exit(0)
10
}()

client.go:345 的 Term() 构造与心跳类似的 XML，但 POST 到 term-url，通知服务端主动下线。

13. 线程安全设计#

states.go 使用 sync.RWMutex 保护所有全局状态，每个字段都有 getter/setter。例如：

1
func (s *States) GetClientID() string {
2
    s.mu.RLock()
3
    defer s.mu.RUnlock()
4
    return s.clientID
5
}
6

7
func (s *States) SetClientID(v string) {
8
    s.mu.Lock()
9
    defer s.mu.Unlock()
10
    s.clientID = v
11
}

这保证了主循环、心跳 goroutine、信号处理 goroutine 并发访问状态时的安全性。

14. 总结#

EsurfingGo 的认证流程可以概括为：探测 → 解析 → 会话 → 票据 → 登录 → 心跳。整个流程基于状态机驱动，任何阶段失败都会回到检测阶段重新尝试，从而实现长期稳定的自动在线。

其技术亮点包括：

使用 generate_204 标准机制检测 Captive Portal。
通过 ZSM 二进制数据动态协商 9 种加密算法之一。
自定义 redirectInterceptor 处理电信校园网特有的 CDC 路由头。
心跳保活 + 失败自动重连，适合无人值守部署。
网卡绑定机制简单有效，支持跨平台多拨。

对于希望理解校园网认证协议、开发类似自动登录工具，或学习 Go 网络编程的开发者，EsurfingGo 是一个结构清晰、值得参考的实战项目。

参考#

项目仓库：EsurfingGo
协议逻辑继承自：Rsplwe/EsurfingDialer
小米 Captive Portal 探测：http://connect.rom.miui.com/generate_204

部署测试：验证 CI/CD 流水线

Fri, 24 Apr 2026 00:00:00 GMT

测试目的#

这篇文章用于验证博客的自动部署流水线是否正常工作。

验证清单#

GitHub Actions 触发构建
rsync 推送到服务器
网站内容更新

结论#

如果这篇文章能正常显示，说明 CI/CD 配置正确，后续可以放心推送内容更新。

从零配置 GitHub Actions CI/CD 自动化部署

Thu, 12 Mar 2026 00:00:00 GMT

前言#

最近为我的博客配置了 GitHub Actions CI/CD，实现了代码推送后自动构建和部署。这篇文章记录整个配置过程，希望能帮助到有同样需求的朋友。

什么是 CI/CD#

CI (Continuous Integration) 持续集成：代码合并后自动构建和测试 CD (Continuous Deployment) 持续部署：构建通过后自动部署到服务器

对于静态博客来说，这意味着：

本地写好文章，push 到 GitHub
GitHub Actions 自动构建
构建成功后自动部署到服务器
全程无需手动操作

准备工作#

服务器环境#

Linux 服务器（我的是 Alibaba Cloud Linux）
已安装 Nginx 或其他 Web 服务器
确保有 SSH 访问权限

安装必要软件#

在服务器上安装 rsync（用于文件同步）：

Terminal window

1
# CentOS/RHEL/Alibaba Cloud Linux
2
sudo yum install -y rsync
3

4
# Ubuntu/Debian
5
sudo apt-get update && sudo apt-get install -y rsync

GitHub 仓库配置#

在 GitHub 创建仓库，上传博客源码
确保仓库有构建脚本（如 pnpm build）

配置 GitHub Actions#

1. 创建 Workflow 文件#

在仓库根目录创建 .github/workflows/deploy.yml：

1
name: Deploy to Server
2

3
on:
4
  push:
5
    branches: [ main ]
6
  pull_request:
7
    branches: [ main ]
8

9
env:
10
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
11

12
jobs:
13
  build:
14
    runs-on: ubuntu-latest
15

16
    steps:
17
    - name: Checkout
18
      uses: actions/checkout@v4
19

20
    - name: Setup Node.js
21
      uses: actions/setup-node@v4
22
      with:
23
        node-version: '22'
24

25
    - name: Setup pnpm
26
      uses: pnpm/action-setup@v2
27
      with:
28
        version: 9
29

30
    - name: Get pnpm store directory
31
      shell: bash
32
      run: |
33
        echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
34

35
    - name: Setup pnpm cache
36
      uses: actions/cache@v4
37
      with:
38
        path: ${{ env.STORE_PATH }}
39
        key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
40
        restore-keys: |
41
          ${{ runner.os }}-pnpm-store-
42

43
    - name: Install dependencies
44
      run: pnpm install
45

46
    - name: Build
47
      run: pnpm build
48

49
    - name: Deploy to Server
50
      if: github.ref == 'refs/heads/main'
51
      uses: easingthemes/ssh-deploy@v5.0.3
52
      with:
53
        SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
54
        ARGS: "-rltgoDzvO --delete"
55
        SOURCE: "dist/"
56
        REMOTE_HOST: ${{ secrets.REMOTE_HOST }}
57
        REMOTE_USER: ${{ secrets.REMOTE_USER }}
58
        REMOTE_PORT: ${{ secrets.REMOTE_PORT }}
59
        TARGET: ${{ secrets.REMOTE_TARGET }}
60
        EXCLUDE: "/dist/, /node_modules/"

展开收起

2. 配置 Secrets#

在 GitHub 仓库 Settings → Secrets and variables → Actions 中添加以下 secrets：

Secret	说明
`SSH_PRIVATE_KEY`	服务器 SSH 私钥
`REMOTE_HOST`	服务器地址
`REMOTE_USER`	SSH 用户名
`REMOTE_PORT`	SSH 端口
`REMOTE_TARGET`	部署目标路径

生成 SSH 密钥#

在本地生成密钥对：

Terminal window

1
ssh-keygen -t ed25519 -C "github-actions" -f ~/.ssh/github_actions

将公钥添加到服务器的 ~/.ssh/authorized_keys：

Terminal window

1
cat ~/.ssh/github_actions.pub >> ~/.ssh/authorized_keys

将私钥内容复制到 GitHub Secrets 的 SSH_PRIVATE_KEY。

遇到的问题与解决#

问题 1：Node.js 版本警告#

GitHub Actions 提示 Node.js 20 actions 将在 2026年6月后弃用。

解决：添加环境变量强制使用 Node.js 24：

1
env:
2
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true

问题 2：类型检查失败#

Astro 的 astro check 报告类型错误，导致构建失败。

解决：跳过类型检查，只执行构建：

1
- name: Build
2
  run: pnpm build  # 不运行 pnpm astro check

问题 3：服务器缺少 rsync#

部署时报错 rsync: command not found。

解决：在服务器上安装 rsync（见准备工作）。

问题 4：SSH 连接被拒绝#

部署时无法连接到服务器。

解决：

检查 SSH 密钥是否正确配置
确认服务器防火墙允许 GitHub Actions IP
验证端口是否正确

优化配置#

跳过不必要的构建#

如果只想在代码文件变更时触发构建，可以添加路径过滤：

1
on:
2
  push:
3
    branches: [ main ]
4
    paths:
5
      - 'src/**'
6
      - 'public/**'
7
      - 'package.json'
8
      - 'pnpm-lock.yaml'

多 Node.js 版本测试#

如果需要测试多个 Node.js 版本：

1
strategy:
2
  matrix:
3
    node: [ 22, 23 ]

但对于个人博客，通常只需要一个版本即可。

验证部署#

配置完成后，push 代码到 main 分支，观察 GitHub Actions 运行状态：

进入仓库的 Actions 标签
查看 workflow 运行状态
绿色 ✅ 表示成功

部署成功后，访问博客域名查看效果。

总结#

通过 GitHub Actions 实现自动化部署后，博客的发布流程变得非常简单：

本地编写文章
git push origin main
等待 1-2 分钟
文章自动上线

不再需要手动构建、上传文件，大大提升了写作效率。

参考链接#

本文记录于 2026-03-12，配置环境：Astro + pnpm + GitHub Actions + Linux 服务器

使用 OpenClaw AI 助手快速搭建博客：从配置到部署的完整体验

Thu, 12 Mar 2026 00:00:00 GMT

前言#

最近尝试使用 OpenClaw 平台的 AI 助手来搭建和管理我的博客，整个体验非常流畅。这篇文章记录 AI 助手协助我完成的各项任务，以及遇到问题的解决方法，希望能给有同样需求的朋友一些参考。

OpenClaw 是什么#

OpenClaw 是一个 AI 助手平台，可以连接多种消息渠道（QQ、Telegram、Discord 等），帮助用户完成各种技术任务。它的特点是：

随时在线：24/7 响应，无需等待
多技能支持：内置各种技能，如文件操作、代码编辑、网络搜索等
安全可靠：敏感信息自动保护，不会泄露
持续学习：能记住用户的偏好和项目配置

AI 助手协助完成的任务#

1. 博客框架搭建#

AI 助手首先帮我完成了博客的基础搭建：

选择框架：推荐了 Astro + Fuwari 主题，静态生成、速度快
本地配置：指导安装 Node.js、pnpm 等依赖
项目初始化：克隆仓库、安装依赖、本地运行

整个过程只需要告诉 AI 需求，它会自动执行命令并反馈结果。

2. GitHub Actions CI/CD 配置#

这是整个过程中最复杂的部分，AI 助手一步步帮我完成了：

创建 Workflow 文件#

.github/workflows/deploy.yml展开收起

1
name: Deploy to Server
2

3
on:
4
  push:
5
    branches: [ main ]
6

7
jobs:
8
  build:
9
    runs-on: ubuntu-latest
10
    steps:
11
      - uses: actions/checkout@v4
12
      - uses: actions/setup-node@v4
13
        with:
14
          node-version: '22'
15
      # ... 其他步骤

展开收起

配置 Secrets#

AI 助手提醒我需要在 GitHub Settings 中配置：

SSH_PRIVATE_KEY - 服务器私钥
REMOTE_HOST - 服务器地址
REMOTE_USER - SSH 用户名
REMOTE_PORT - SSH 端口
REMOTE_TARGET - 部署路径

服务器准备#

AI 检测到服务器缺少 rsync，自动执行安装：

Terminal window

1
sudo yum install -y rsync

3. 问题解决记录#

问题 1：Node.js 版本警告#

现象：GitHub Actions 提示 Node.js 20 将被弃用

解决：AI 在 workflow 中添加环境变量：

1
env:
2
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true

问题 2：Astro 类型检查失败#

现象：pnpm astro check 报告类型错误，导致构建失败

解决：AI 建议跳过类型检查，只执行构建：

1
- name: Build
2
  run: pnpm build  # 不运行 astro check

问题 3：SSH 连接被拒绝#

现象：部署时无法连接到服务器

原因：SSH 端口配置错误

解决：AI 修改为正确的端口号

问题 4：rsync 未找到#

现象：部署报错 rsync: command not found

解决：AI 在服务器上安装 rsync

4. 文档整理#

AI 助手还帮我整理了相关文档：

操作手册：记录完整的配置步骤
问题汇总：整理遇到的问题和解决方案
博客文章：自动生成技术分享文章

GitHub 访问加速方法#

在配置过程中，AI 提供了几个 GitHub 加速方法：

方法一：使用代理域名#

将 github.com 替换为加速代理：

Terminal window

1
# 使用 ghfast.top 代理
2
git clone https://ghfast.top/https://github.com/user/repo.git
3

4
# 使用 githubproxy.cc 代理
5
git clone https://githubproxy.cc/github.com/user/repo.git

方法二：修改 Hosts#

使用 GitHub520 项目自动更新 hosts：

Terminal window

1
# Linux/Mac
2
sudo sh -c 'sed -i "/# GitHub520 Host Start/Q" /etc/hosts && curl https://raw.hellogithub.com/hosts >> /etc/hosts'

参考项目：GitHub520

方法三：使用 SSH 协议#

配置 SSH 密钥后，使用 SSH 方式克隆：

Terminal window

1
git clone git@github.com:user/repo.git

使用体验总结#

优势#

效率高：AI 可以同时处理多个任务，比如一边修改代码一边写文档
错误少：AI 会自动检查命令和配置，减少人为错误
学习价值：可以看到 AI 的解决思路，学习最佳实践
持续可用：随时响应，不受时间限制

适用场景#

✅ 重复性配置任务（如 CI/CD）
✅ 文档整理和写作
✅ 问题排查和解决
✅ 代码审查和优化

注意事项#

敏感信息（密码、密钥）需要妥善管理
关键操作（删除、修改配置）建议二次确认
保持代码仓库的备份

写在最后#

通过这次体验，我深刻感受到 AI 助手在开发工作中的价值。它不仅能快速完成任务，还能提供专业的建议和解决方案。对于独立开发者或个人博客维护者来说，这是一个非常实用的工具。

如果你也在考虑搭建博客或配置自动化部署，不妨尝试使用 AI 助手，相信会有不错的体验。

相关链接

本文记录于 2026-03-12，感谢 OpenClaw AI 助手的协助 🎉

OpenClaw 使用感想：从宝塔面板到 AI 托管的技术革命

Thu, 12 Mar 2026 00:00:00 GMT

本文由 OpenClaw 根据用户真实使用体验编写。

前言：传统运维的痛点#

在接触 OpenClaw 之前，我的服务器一直使用宝塔面板管理。虽然宝塔提供了图形化界面，但每一个服务的部署都需要我手动操作：

安装 Nginx，配置虚拟主机
部署 Fuwari 博客，处理依赖和构建
安装 OpenList，配置 Docker 容器
搭建 WireGuard，编写配置文件
配置安全策略，修改 SSH 端口
…

这些工作花费了我大量时间，尤其是 Docker 镜像拉取缓慢、网络环境配置等问题，常常让我焦头烂额。

遇见 OpenClaw#

后来我备份了服务器，重装系统，决定尝试 OpenClaw。

这个决定，彻底改变了我的运维方式。

惊人的效率对比#

博客部署：从数小时到 10 分钟#

以前用宝塔：

安装 Node.js、pnpm
上传博客源码
安装依赖（经常因为网络问题失败）
配置 Nginx 反向代理
配置 SSL 证书
调试各种路径问题

使用 OpenClaw：

把博客文件发给他
10 分钟后，博客上线了

没错，就是 10 分钟。AI 自己完成了依赖安装、构建、Nginx 配置、SSL 配置，我甚至不需要输入一条命令。

OpenList 部署：文档即代码#

我给了 OpenClaw 官网的安装文档，他就自己把 OpenList 搭起来了。

中途遇到 Docker 镜像拉取缓慢的问题，他自己解决了——没有问我，没有卡顿，直接处理了。

WireGuard：零配置上手#

以前配置 WireGuard，我要：

生成密钥对
编写服务端配置
编写客户端配置
配置防火墙规则

现在？AI 自己写了配置文件，生成了密钥，我只需要复制粘贴客户端配置。

Bitwarden：对话式安装#

安装 Bitwarden 只需要几句话：

“帮我安装 Bitwarden”
“端口用 8081”
“关闭注册”

然后就好了。Docker 容器运行，Nginx 反向代理配置完成，SSL 证书自动申请。

Star Office：Skills 文件即服务#

最神奇的是 Star Office 这个项目。OpenClaw 提供的不是命令，而是 skills 文件——让 AI 自己帮我配置。

我只需要说”安装 Star Office”，AI 就会：

读取 skills 文档
安装依赖
配置后端
设置 Nginx 反向代理
启动服务

全程无需我干预。

GitHub Actions：全自动 CI/CD#

我尝试把博客源代码给 OpenClaw，并为他配置了 GitHub CLI。

结果？他自己：

阅读了 GitHub Actions 文档
编写了 deploy.yml
配置了 Secrets
解决了 SSH 端口问题
安装了服务器端的 rsync
实现了完整的 CI/CD

现在，我只需要在本地写博客文章，push 到 GitHub，2 分钟后文章就自动上线了。

核心优势#

1. 完全托管#

我不需要管理 Nginx，不需要配置反向代理，不需要处理 SSL 证书。OpenClaw 全部自动完成。

2. 问题解决能力#

遇到 Docker 镜像拉取慢、类型检查失败、SSH 连接问题，AI 都能自己解决或提供方案。

3. 持续可用#

24/7 在线，随时响应。凌晨 1 点 push 代码，2 分钟后就能看到部署结果。

4. 知识沉淀#

所有配置、文档、解决方案都会被记录下来，形成知识库。下次遇到类似问题，直接复用。

使用建议#

如果你也在考虑使用 OpenClaw，建议：

大胆尝试：把任务交给 AI，你会发现它的能力超出预期
清晰描述：越清晰的需求描述，越能得到满意的结果
及时反馈：如果结果不符合预期，及时纠正，AI 会快速调整
信任但确认：关键操作（如删除、修改配置）可以要求 AI 二次确认

写在最后#

从宝塔面板到 OpenClaw，我的运维效率提升了不止 10 倍。

以前我需要：

学习 Nginx 配置
研究 Docker 网络
调试各种环境问题
手动执行重复命令

现在我只需要：

告诉 AI 我要什么
等待几分钟
享受成果

OpenClaw 太强大了。这不仅仅是工具的革命，更是工作方式的革命。

感谢 OpenClaw，让我从繁琐的运维工作中解放出来，把更多时间投入到创作和思考中。

作者: 焕新
编写协助: OpenClaw
时间: 2026-03-12

如果你也在使用 OpenClaw，欢迎分享你的使用体验！

Fuwari 博客主题深度架构解析：从源码到自定义开发

Thu, 12 Mar 2026 00:00:00 GMT

引言#

Fuwari 是一个基于 Astro 构建的静态博客主题，以其精美的设计、流畅的动画效果和丰富的功能受到众多博主的喜爱。本文将从架构层面深入剖析 Fuwari 的实现原理，帮助你理解其设计思想，并掌握自定义开发的方法。

一、整体架构概览#

1.1 技术栈组成#

Fuwari 采用了现代化的前端技术栈：

层级	技术	用途
框架	Astro 5.x	静态站点生成、 Islands 架构
样式	Tailwind CSS 3.x	原子化 CSS 样式
组件	Svelte 5.x	交互式组件（主题切换等）
动画	Swup + CSS	页面过渡动画
搜索	Pagefind	静态搜索索引
图标	Iconify	图标系统
代码高亮	Expressive Code	代码块渲染

1.2 项目结构#

1
fuwari/
2
├── src/
3
│   ├── components/          # 可复用组件
4
│   │   ├── control/         # 控制组件（分页、返回顶部）
5
│   │   ├── misc/            # 杂项组件（Markdown、图片）
6
│   │   └── widget/          # 侧边栏组件
7
│   ├── content/             # 内容集合配置
8
│   │   ├── config.ts        # 文章 schema 定义
9
│   │   └── posts/           # 博客文章目录
10
│   ├── i18n/                # 国际化
11
│   ├── layouts/             # 页面布局
12
│   ├── pages/               # 路由页面
13
│   ├── plugins/             # 自定义 remark/rehype 插件
14
│   ├── styles/              # 全局样式
15
│   ├── types/               # TypeScript 类型定义
16
│   └── utils/               # 工具函数
17
├── public/                  # 静态资源
18
└── scripts/                 # 构建脚本

展开收起

二、核心架构设计#

2.1 布局系统（Layout System）#

Fuwari 采用了三层布局架构：

2.1.1 Layout.astro - 基础布局层#

这是所有页面的根布局，负责：

HTML 骨架和元数据
主题色和暗色模式初始化
全局样式变量注入
PhotoSwipe 图片灯箱初始化
Swup 页面过渡配置

1
<!-- 关键代码片段：主题初始化 -->
2
<script is:inline>
3
  // 从 localStorage 读取主题设置
4
  const theme = localStorage.getItem('theme') || DEFAULT_THEME;
5
  switch (theme) {
6
    case LIGHT_MODE: document.documentElement.classList.remove('dark'); break;
7
    case DARK_MODE: document.documentElement.classList.add('dark'); break;
8
    case AUTO_MODE: // 根据系统偏好自动切换
9
  }
10

11
  // 读取主题色相
12
  const hue = localStorage.getItem('hue') || configHue;
13
  document.documentElement.style.setProperty('--hue', hue);
14
</script>

2.1.2 MainGridLayout.astro - 主网格布局层#

这是博客页面的主要布局，实现了响应式三栏设计：

1
┌─────────────────────────────────────────────┐
2
│                   Navbar                     │
3
├─────────────────────────────────────────────┤
4
│                                             │
5
│                   Banner                     │  ← 可选的顶部横幅
6
│                                             │
7
├──────────┬────────────────────────┬─────────┤
8
│          │                        │         │
9
│ Sidebar  │      Main Content      │   TOC   │  ← 文章目录（桌面端右侧）
10
│  (左侧)   │      (中间主内容)       │  (右侧)  │
11
│          │                        │         │
12
├──────────┴────────────────────────┴─────────┤
13
│                   Footer                     │
14
└─────────────────────────────────────────────┘

关键实现细节：

1
<!-- 主网格使用 CSS Grid 实现 -->
2
<div id="main-grid" class="grid grid-cols-[17.5rem_auto] lg:grid-rows-[auto]">
3
    <SideBar class="col-span-2 lg:col-span-1"></SideBar>
4
    <main id="swup-container" class="col-span-2 lg:col-span-1">
5
        <slot></slot>  <!-- 页面内容注入点 -->
6
    </main>
7
</div>

响应式断点策略：

lg (1024px+): 三栏布局（侧边栏 + 主内容 + TOC）
md (768px+): 两栏布局
移动端: 单栏，侧边栏移至底部

2.2 内容管理系统#

2.2.1 Astro Content Collections#

Fuwari 使用 Astro 的内容集合 API 管理文章：

src/content/config.ts展开收起

1
const postsCollection = defineCollection({
2
  schema: z.object({
3
    title: z.string(),
4
    published: z.date(),
5
    updated: z.date().optional(),
6
    draft: z.boolean().optional().default(false),
7
    description: z.string().optional().default(""),
8
    image: z.string().optional().default(""),
9
    tags: z.array(z.string()).optional().default([]),
10
    category: z.string().optional().nullable().default(""),
11
    lang: z.string().optional().default(""),
12
    // 内部使用的导航字段
13
    prevTitle: z.string().default(""),
14
    prevSlug: z.string().default(""),
15
    nextTitle: z.string().default(""),
16
    nextSlug: z.string().default(""),
17
  }),
18
});

展开收起

2.2.2 文章排序与导航#

getSortedPosts() 函数实现了文章排序和前后篇关联：

src/utils/content-utils.ts

1
export async function getSortedPosts() {
2
  const sorted = await getRawSortedPosts(); // 按发布日期降序
3

4
  // 构建前后篇导航
5
  for (let i = 1; i < sorted.length; i++) {
6
    sorted[i].data.nextSlug = sorted[i - 1].slug;
7
    sorted[i].data.nextTitle = sorted[i - 1].data.title;
8
  }
9
  for (let i = 0; i < sorted.length - 1; i++) {
10
    sorted[i].data.prevSlug = sorted[i + 1].slug;
11
    sorted[i].data.prevTitle = sorted[i + 1].data.title;
12
  }
13
  return sorted;
14
}

2.3 样式系统架构#

2.3.1 CSS 变量体系#

Fuwari 使用 Stylus 定义了一套完整的 CSS 变量系统：

src/styles/variables.styl

1
:root
2
  --radius-large: 1rem
3
  --primary: oklch(0.70 0.14 var(--hue))
4
  --page-bg: oklch(0.95 0.01 var(--hue))
5
  --card-bg: white
6
  // ... 更多变量
7

8
// 暗色模式覆盖
9
:root.dark
10
  --primary: oklch(0.75 0.14 var(--hue))
11
  --page-bg: oklch(0.16 0.014 var(--hue))
12
  --card-bg: oklch(0.23 0.015 var(--hue))

设计亮点：

使用 OKLCH 色彩空间，支持色相自定义
--hue 变量允许用户通过滑块调整主题色
明暗模式通过 CSS 类切换，无需重新加载

2.3.2 Tailwind 集成#

tailwind.config.cjs

1
module.exports = {
2
  content: ["./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue,mjs}"],
3
  darkMode: "class", // 手动切换暗色模式
4
  theme: {
5
    extend: {
6
      fontFamily: {
7
        sans: ["MiSans", "sans-serif", ...defaultTheme.fontFamily.sans],
8
      },
9
    },
10
  },
11
}

2.4 插件系统#

Fuwari 通过 Remark/Rehype 插件扩展 Markdown 功能：

2.4.1 阅读时间统计#

src/plugins/remark-reading-time.mjs

1
import { toString } from "mdast-util-to-string";
2
import getReadingTime from "reading-time";
3

4
export function remarkReadingTime() {
5
  return (tree, { data }) => {
6
    const textOnPage = toString(tree);
7
    const readingTime = getReadingTime(textOnPage);
8
    // 注入到 frontmatter
9
    data.astro.frontmatter.minutes = Math.max(1, Math.round(readingTime.minutes));
10
    data.astro.frontmatter.words = readingTime.words;
11
  };
12
}

2.4.2 文章摘要生成#

src/plugins/remark-excerpt.js

1
export function remarkExcerpt() {
2
  return (tree, { data }) => {
3
    let excerpt = "";
4
    // 遍历 AST，提取前 150 个字符
5
    for (const node of tree.children) {
6
      if (node.type === "paragraph") {
7
        excerpt += extractText(node);
8
        if (excerpt.length > 150) break;
9
      }
10
    }
11
    data.astro.frontmatter.excerpt = excerpt.slice(0, 150) + "...";
12
  };
13
}

2.4.3 自定义指令组件#

支持在 Markdown 中使用自定义指令：

1
:::github{repo="facebook/react"}
2
:::
3

4
:::tip
5
这是一个提示框
6
:::

实现原理：

astro.config.mjs

1
rehypePlugins: [
2
  [rehypeComponents, {
3
    components: {
4
      github: GithubCardComponent,
5
      tip: (x, y) => AdmonitionComponent(x, y, "tip"),
6
      // ...
7
    }
8
  }]
9
]

三、核心功能实现详解#

3.1 文章卡片组件（PostCard）#

这是博客列表的核心组件，实现了响应式双模式布局：

桌面端布局：

1
┌─────────────────────────────────────────┬─────────┐
2
│                                         │         │
3
│  Title                                  │  Cover  │
4
│                                         │  Image  │
5
│  Category • Date                        │  (右侧)  │
6
│                                         │         │
7
│  Description excerpt...                 │         │
8
│                                         │         │
9
│  1,234 words | 5 min                    │         │
10
│                                         │         │
11
└─────────────────────────────────────────┴─────────┘

移动端布局：

1
┌─────────────────────────────────────────┐
2
│  Cover Image (顶部)                      │
3
├─────────────────────────────────────────┤
4
│  Title >                                │
5
│  Category • Date                         │
6
│  Description...                          │
7
│  1,234 words | 5 min                     │
8
└─────────────────────────────────────────┘

关键代码实现：

1
<!-- 响应式布局切换 -->
2
<div class="flex flex-col-reverse md:flex-col ...">
3
    <!-- 内容区域：桌面端左侧，移动端下方 -->
4
    <div class="w-full md:w-[calc(100%_-_var(--coverWidth)_-_12px)]">
5
        <a href={url} class="group ...">
6
            {title}
7
            <!-- 悬停动画效果 -->
8
            <Icon class="opacity-0 group-hover:opacity-100 ..." />
9
        </a>
10
        <PostMetadata ... />
11
        <div class="line-clamp-2 md:line-clamp-1">{description}</div>
12
    </div>
13

14
    <!-- 封面区域：桌面端右侧绝对定位，移动端顶部 -->
15
    {hasCover && <a class="md:absolute md:right-3 ...">
16
        <ImageWrapper src={image} ... />
17
    </a>}
18
</div>

展开收起

3.2 侧边栏组件系统#

侧边栏由多个可复用的小部件组成：

3.2.1 个人资料卡片（Profile）#

1
<div class="card-base p-3">
2
    <!-- 头像区域 -->
3
    <a href="/about/" class="group block relative ...">
4
        <div class="absolute ... group-hover:bg-black/30">
5
            <Icon name="fa6-regular:address-card"
6
                  class="opacity-0 group-hover:opacity-100" />
7
        </div>
8
        <ImageWrapper src={config.avatar} ... />
9
    </a>
10

11
    <!-- 信息区域 -->
12
    <div class="text-center">
13
        <div class="font-bold text-xl">{config.name}</div>
14
        <div class="h-1 w-5 bg-[var(--primary)] mx-auto rounded-full">
15
        </div> <!-- 装饰性分隔线 -->
16
        <div class="text-neutral-400">{config.bio}</div>
17

18
        <!-- 社交链接 -->
19
        <div class="flex flex-wrap gap-2 justify-center">
20
            {config.links.map(item =>
21
                <a href={item.url} class="btn-regular rounded-lg h-10 w-10">
22
                    <Icon name={item.icon} />
23
                </a>
24
            )}
25
        </div>
26
    </div>
27
</div>

展开收起

3.2.2 分类和标签组件#

Categories.astro

1
<div class="flex flex-wrap gap-2">
2
    {categories.map(category =>
3
        <a href={category.url}
4
           class="btn-regular rounded-full px-3 py-1 text-sm">
5
            {category.name} {category.count}
6
        </a>
7
    )}
8
</div>

3.3 文章详情页实现#

文章页是功能最复杂的页面，包含：

3.3.1 动态路由生成#

src/pages/posts/[...slug].astro

1
---
2
export async function getStaticPaths() {
3
    const blogEntries = await getSortedPosts();
4
    return blogEntries.map((entry) => ({
5
        params: { slug: entry.slug },
6
        props: { entry },
7
    }));
8
}
9

10
const { entry } = Astro.props;
11
const { Content, headings } = await entry.render();
12
---

3.3.2 文章元数据展示#

文章头部包含：

字数统计和阅读时间（通过 remark 插件计算）
发布/更新日期
分类和标签
封面图片

1
<div class="flex flex-row text-black/30 dark:text-white/30 gap-5 mb-3">
2
    <div class="flex items-center">
3
        <Icon name="material-symbols:notes-rounded" />
4
        <div>{remarkPluginFrontmatter.words} words</div>
5
    </div>
6
    <div class="flex items-center">
7
        <Icon name="material-symbols:schedule-outline-rounded" />
8
        <div>{remarkPluginFrontmatter.minutes} min read</div>
9
    </div>
10
</div>

3.3.3 Markdown 渲染#

1
<Markdown class="mb-6 markdown-content onload-animation">
2
    <Content />
3
</Markdown>

Markdown.astro 组件封装了：

Tailwind Typography 样式 (prose)
代码块复制按钮
图片点击放大（PhotoSwipe）
锚点链接生成

3.4 搜索功能实现#

Fuwari 使用 Pagefind 实现静态搜索：

3.4.1 构建时索引生成#

package.json

1
{
2
  "scripts": {
3
    "build": "astro build && pagefind --site dist"
4
  }
5
}

3.4.2 前端搜索组件#

Search.svelte展开收起

1
<script>
2
  let keyword = "";
3
  let results = [];
4

5
  async function search() {
6
    if (!window.pagefind) return;
7
    const response = await window.pagefind.search(keyword);
8
    results = await Promise.all(
9
      response.results.map(item => item.data())
10
    );
11
  }
12
</script>
13

14
<div id="search-bar">
15
    <input bind:value={keyword} on:input={search} placeholder="Search..." />
16
</div>
17

18
<div id="search-results">
19
    {#each results as item}
20
        <a href={item.url}>
21
            <div>{item.meta.title}</div>
22
            <div>{@html item.excerpt}</div>
23
        </a>
24
    {/each}
25
</div>

展开收起

四、扩展开发指南#

4.1 添加新页面#

以添加”友链”页面为例：

步骤 1: 创建页面组件#

src/pages/friends.astro展开收起

1
---
2
import Layout from "@/layouts/Layout.astro";
3
---
4

5
<Layout title="友链 | Friends">
6
    <div class="max-w-4xl mx-auto px-4 py-8">
7
        <h1 class="text-4xl font-bold mb-8 text-center">✨ 友情链接</h1>
8

9
        <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
10
            <!-- 友链卡片 -->
11
            <a href="https://example.com"
12
               class="card-base p-4 flex items-center gap-4
13
                      hover:border-[var(--primary)] transition-all">
14
                <img src="avatar.jpg" class="w-12 h-12 rounded-full" />
15
                <div>
16
                    <h3 class="font-semibold">站点名称</h3>
17
                    <p class="text-sm text-[var(--text-muted)]">站点描述</p>
18
                </div>
19
            </a>
20
        </div>
21
    </div>
22
</Layout>

展开收起

步骤 2: 添加到导航栏#

src/config.ts

1
export const navBarConfig: NavBarConfig = {
2
    links: [
3
        LinkPreset.Home,
4
        LinkPreset.Archive,
5
        {
6
            name: "友链✨",
7
            url: "/friends/",
8
        },
9
        LinkPreset.About,
10
    ],
11
};

4.2 自定义主题色#

Fuwari 支持动态调整主题色相：

src/config.ts

1
export const siteConfig: SiteConfig = {
2
    themeColor: {
3
        hue: 250,        // 默认色相 (0-360)
4
        fixed: false,    // 是否隐藏主题色选择器
5
    },
6
};

实现原理：

所有颜色使用 oklch() 函数定义
色相通过 CSS 变量 --hue 控制
用户调整时更新 localStorage 和 CSS 变量

4.3 添加自定义组件#

步骤 1: 创建组件#

src/components/MyComponent.astro

1
---
2
interface Props {
3
    title: string;
4
    content: string;
5
}
6
const { title, content } = Astro.props;
7
---
8

9
<div class="card-base p-6 my-4 border-l-4 border-[var(--primary)]">
10
    <h3 class="text-xl font-bold mb-2">{title}</h3>
11
    <p class="text-[var(--text-muted)]">{content}</p>
12
</div>

步骤 2: 在 Markdown 中使用#

通过 rehype-components 插件注册：

astro.config.mjs

1
import { MyComponent } from "./src/components/MyComponent.astro";
2

3
rehypePlugins: [
4
    [rehypeComponents, {
5
        components: {
6
            mycomponent: MyComponent,
7
        }
8
    }]
9
]

Markdown 中使用：

1
:::mycomponent{title="提示" content="这是自定义组件"}
2
:::

4.4 修改文章 Schema#

添加自定义字段：

src/content/config.ts

1
const postsCollection = defineCollection({
2
    schema: z.object({
3
        // ... 原有字段
4
        author: z.string().optional().default("默认作者"),
5
        difficulty: z.enum(["简单", "中等", "困难"]).optional(),
6
        series: z.string().optional(), // 系列文章
7
    }),
8
});

在模板中使用：

1
<!-- 显示难度标签 -->
2
{entry.data.difficulty && (
3
    <span class="badge">
4
        {entry.data.difficulty}
5
    </span>
6
)}

五、性能优化策略#

5.1 Islands 架构#

Astro 的 Islands 架构确保：

静态内容在构建时生成 HTML
交互组件（如搜索）按需 hydrate
减少客户端 JavaScript 体积

1
<!-- 静态渲染 -->
2
<PostCard entry={entry} />
3

4
<!-- 客户端交互组件 -->
5
<Search client:only="svelte" />

5.2 图片优化#

1
<!-- ImageWrapper 组件封装了 Sharp 优化 -->
2
<ImageWrapper
3
    src="large-image.jpg"
4
    alt="描述"
5
    class="w-full h-auto"
6
/>

5.3 字体加载策略#

1
/* 使用 font-display: swap 防止 FOIT */
2
@font-face {
3
    font-family: 'MiSans';
4
    src: url('/fonts/MiSans-Normal.woff2') format('woff2');
5
    font-weight: 400;
6
    font-display: swap; /* 关键：先显示后备字体 */
7
}

六、部署与构建#

6.1 构建流程#

Terminal window

1
# 1. 类型检查
2
pnpm run type-check
3

4
# 2. 构建 Astro 站点
5
astro build
6

7
# 3. 生成搜索索引
8
pagefind --site dist
9

10
# 4. 输出目录: dist/

6.2 部署配置#

Vercel 配置：

vercel.json

1
{
2
  "framework": "astro"
3
}

GitHub Actions：

1
name: Deploy
2
on: [push]
3
jobs:
4
  build:
5
    runs-on: ubuntu-latest
6
    steps:
7
      - uses: actions/checkout@v4
8
      - uses: pnpm/action-setup@v2
9
      - run: pnpm install
10
      - run: pnpm build
11
      - uses: peaceiris/actions-gh-pages@v3
12
        with:
13
          github_token: ${{ secrets.GITHUB_TOKEN }}
14
          publish_dir: ./dist

七、总结#

Fuwari 的架构设计体现了以下优秀实践：

组件化设计：可复用的卡片、按钮、布局组件
配置驱动：通过 config.ts 集中管理站点配置
类型安全：全面的 TypeScript 类型定义
性能优先：静态生成、图片优化、按需加载
可扩展性：插件系统支持自定义 Markdown 组件
国际化：完整的 i18n 支持

通过理解这些架构设计，你可以：

自信地修改和扩展主题功能
添加自定义页面和组件
优化性能和用户体验
迁移到其他 Astro 项目

参考资源：

MoonEdge上线了！

Fri, 06 Feb 2026 00:00:00 GMT

欢迎来到 MoonEdge#

你好，世界！👋

这是 MoonEdge 的第一篇文章，也是我在这片数字星空下点亮的第一盏灯。 “MoonEdge”这个名字，源于我对夜晚、边缘思考与未知探索的热爱——就像月球的边缘，在光明与黑暗之间，总藏着值得凝视的故事。

Test

Wed, 01 Jan 2025 00:00:00 GMT

This post demonstrates how to include embedded video in a blog post.