年华

GitHub Actions 自动构建并部署 Cloudflare Workers 实现思路

Thu, 04 Jun 2026 00:00:00 GMT

Warning

这个项目在 Cloudflare Workers 上构建时可能会翻车。Astro 构建过程依赖 sharp（图片处理）和一些 Node.js 原生模块，Cloudflare Workers 的构建环境对这些支持有限。如果你在 Workers 上构建失败，别慌，这是正常操作。解决方案是：在 GitHub Actions 里构建好，只把产物丢过去，让 Workers 只管托管静态文件，别让它干重活。

为什么要搞这个#

每次手动构建、再部署，累不累啊？反正我累了。目标是：推送代码到 master 分支后，GitHub Actions 自动帮你搞定三件事：

构建 Astro 项目（让它在 CI 里卷）
把构建产物推送到 build 分支（留个备份）
部署到 Cloudflare Workers（上线，收工）

一条龙服务，你只需要 git push，剩下的交给机器人。

整体流程#

1
push master → checkout → 安装依赖 → pnpm build → 推送 dist 到 build 分支 → wrangler deploy

实现思路#

1. 触发条件#

监听 master 分支的 push 事件，同时支持手动触发（workflow_dispatch）。手动触发的好处是：万一自动部署翻车了，你可以点一下重试，不用再 push 一个空提交。

1
on:
2
  push:
3
    branches: [master]
4
  workflow_dispatch:

2. 环境准备#

GitHub Actions 的 Ubuntu 镜像里没有 pnpm，得自己装。顺序有讲究：先装 pnpm，再装 Node.js，这样 Node.js 的缓存机制才能识别 pnpm。搞反了缓存就废了。

1
- name: Setup pnpm
2
  uses: pnpm/action-setup@v4
3
  with:
4
    version: 9.14.4
5

6
- name: Setup Node.js
7
  uses: actions/setup-node@v4
8
  with:
9
    node-version: '24'
10
    cache: 'pnpm'  # 必须在 pnpm 安装之后

3. 构建项目#

pnpm run build 其实是个三连：先生成图标，再用 Astro 构建，最后用 Pagefind 做全文搜索索引。这三步缺一不可，少了哪个搜索功能都会出问题。

1
- name: Install Dependencies
2
  run: pnpm install --frozen-lockfile
3

4
- name: Build
5
  run: pnpm run build

4. 推送到 build 分支#

用 peaceiris/actions-gh-pages 这个 action，把 dist/ 目录的内容推到 build 分支。它每次都会暴力覆盖，不会保留历史。不过也没关系，反正构建产物每次都一样。

1
- name: Push to build branch
2
  uses: peaceiris/actions-gh-pages@v4
3
  with:
4
    github_token: ${{ secrets.GITHUB_TOKEN }}
5
    publish_dir: ./dist
6
    publish_branch: build

5. 部署到 Cloudflare Workers#

最后一步，用 wrangler deploy 把构建好的静态文件丢到 Workers 上。这一步需要两个 secrets：API Token 和 Account ID，没这俩东西.wrangler 连不上 Cloudflare。

1
- name: Deploy to Cloudflare Workers
2
  run: npx wrangler deploy
3
  env:
4
    CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
5
    CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

完整源码#

1
# 构建项目并将产物推送到 build 分支，然后部署到 Cloudflare Workers
2
name: Build to Branch
3

4
# 当推送到 master 分支时触发，也支持手动触发
5
on:
6
  push:
7
    branches: [master]
8
  workflow_dispatch:
9

10
# 需要写入权限来推送 build 分支
11
permissions:
12
  contents: write
13

14
# 同一时间只运行一个构建任务，取消正在运行的旧任务
15
concurrency:
16
  group: build
17
  cancel-in-progress: true
18

19
jobs:
20
  build:
21
    runs-on: ubuntu-latest
22
    steps:
23
      # 检出代码
24
      - name: Checkout
25
        uses: actions/checkout@v4
26

27
      # 安装 pnpm 包管理器
28
      - name: Setup pnpm
29
        uses: pnpm/action-setup@v4
30
        with:
31
          version: 9.14.4
32

33
      # 安装 Node.js 并配置 pnpm 缓存
34
      - name: Setup Node.js
35
        uses: actions/setup-node@v4
36
        with:
37
          node-version: '24'
38
          cache: 'pnpm'
39

40
      # 安装项目依赖
41
      - name: Install Dependencies
42
        run: pnpm install --frozen-lockfile
43

44
      # 构建项目：生成图标 → Astro 构建 → Pagefind 索引
45
      - name: Build
46
        run: pnpm run build
47

48
      # 推送 dist 目录到 build 分支
49
      - name: Push to build branch
50
        uses: peaceiris/actions-gh-pages@v4
51
        with:
52
          github_token: ${{ secrets.GITHUB_TOKEN }}
53
          publish_dir: ./dist
54
          publish_branch: build
55

56
      # 使用 wrangler CLI 部署到 Cloudflare Workers
57
      - name: Deploy to Cloudflare Workers
58
        run: npx wrangler deploy
59
        env:
60
          # Cloudflare API Token，需要 Edit Cloudflare Workers 权限
61
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
62
          # Cloudflare 账户 ID，在 Dashboard 右侧栏可见
63
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

展开收起

需要配置的 Secrets#

在 GitHub 仓库 Settings → Secrets and variables → Actions 里加两个 secret，不加的话 workflow 会直接报错退出。

Secret	说明	获取方式
`CLOUDFLARE_API_TOKEN`	API 令牌	Cloudflare Dashboard → My Profile → API Tokens → Create Token
`CLOUDFLARE_ACCOUNT_ID`	账户 ID	Cloudflare Dashboard 右侧栏

API Token 要选 “Edit Cloudflare Workers” 模板，这个模板包含 Workers 脚本编辑权限，部署够用了。

注意事项#

--frozen-lockfile 是个好东西，确保 CI 里不会偷偷给你更新依赖版本，避免”我本地能跑线上挂了”的经典剧情
concurrency 配置能避免同时跑多个构建任务，省点 CI 分钟数
wrangler deploy 会老老实实读取仓库根目录的 wrangler.toml，所以记得把这个文件提交上去
build 分支只包含 dist/ 的内容，源码不会泄露，放心用

Firefly 主题添加WelcomeToast 组件

Sun, 31 May 2026 00:00:00 GMT

Firefly 主题 WelcomeToast 组件分析#

Firefly是一个基于 Astro的博客主题。

CuteLeaf

Firefly

Waiting for api.github.com...

00K

Waiting...

WelcomeToast 是我自己加的一个小组件，效果就是访客第一次打开页面时，右下角会弹出一个欢迎卡片，还带了 IP 地理位置的个性化问候，5 秒后自动消失。

WelcomeToast 效果演示

涉及的文件#

整个组件涉及两个文件：

文件	路径
组件本身	`src/components/widget/WelcomeToast.astro`
在布局中引用	`src/layouts/MainGridLayout.astro`

组件是怎么实现的#

这个组件的 frontmatter 是空的，没有任何服务端逻辑。所有事情都在浏览器端的 <script> 和 <style> 里完成。

页面上长什么样#

组件本身不输出任何 HTML，所有 DOM 都是 JS 动态生成的。结构大概是这样：

1
#welcome-toast（固定在右下角，z-50）
2
└── 一个卡片 div（白色背景、圆角、阴影）
3
    ├── 👋 表情
4
    ├── 文字区
5
    │   ├── 问候语（一开始显示"正在加载..."，后面会变成具体地址）
6
    │   └── 副标题"欢迎来到我的博客"
7
    └── 关闭按钮（一个 ×）

几个关键函数#

整个逻辑不复杂，就是 5 个函数各管各的事：

1
// 用 sessionStorage 做会话标识，防止重复弹出
2
const VISIT_SESSION_KEY = 'blog_visit_flag';
3
let hasShownToast = false;
4

5
// 创建 Toast 的 DOM 结构，插入到页面上
6
function createWelcomeToast()
7

8
// 关掉 Toast：先滑出去，500ms 后把节点从 DOM 里移掉
9
function closeWelcomeToast()
10

11
// 请求一个免费的 IP API，拿到访客的位置信息
12
async function fetchLocation()
13

14
// 整个弹出流程的"导演"：创建 → 滑入 → 拿位置 → 5秒后自动关闭
15
async function showWelcomeToast()
16

17
// 入口函数：判断是不是第一次访问，是的话才弹
18
function initWelcome()

展开收起

执行顺序#

说白了就是这么个流程：

怎么适配 SPA 导航的#

这里有个坑：Firefly 用了 Swup 做客户端路由，页面切换的时候不会走完整的 DOMContentLoaded。所以组件同时绑了两个事件：

1
if (document.readyState === 'loading') {
2
    document.addEventListener('DOMContentLoaded', initWelcome);
3
    document.addEventListener('astro:page-load', initWelcome);  // Swup 专用
4
} else {
5
    initWelcome();
6
}

另外关闭按钮用的是内联 onclick，所以函数得挂到 window 上才能调用：

1
(window as any).closeWelcomeToast = closeWelcomeToast;

样式部分#

桌面端：固定在右下角（fixed bottom-4 right-4 z-50），用 CSS transition 做滑入滑出动画，500ms ease-out。
移动端（640px 以下）：改到屏幕底部居中，宽度 90%，不会遮挡太多内容。
深色模式：用 Tailwind 的 dark: 变体自动切换背景色、边框色和文字色。

在 MainGridLayout 里怎么放的#

MainGridLayout 是 Firefly 的主布局，导航栏、壁纸、侧边栏、Footer 都在这里面。WelcomeToast 在第 7 行被 import，然后放在了第 858 行：

1
import WelcomeToast from "@components/widget/WelcomeToast.astro";

具体位置是在 #swup-container 里面、<slot /> 后面：

1
<main id="swup-container" class="transition-main">
2
    <div id="content-wrapper">
3
        <slot></slot>
4
    </div>
5
    <WelcomeToast />
6
</main>

整个布局大概是这么个层级关系：

1
Layout.astro
2
└── MainGridLayout.astro
3
    ├── Navbar（导航栏）
4
    ├── Wallpaper（背景壁纸）
5
    ├── <main id="swup-container">      ← Swup 的容器，导航时会替换这里面的内容
6
    │   ├── <slot>                       ← 每个页面的具体内容
7
    │   └── <WelcomeToast />             ← 放在内容后面
8
    ├── Footer（页脚）
9
    └── FloatingControls（浮动控制按钮）

几个值得注意的点#

没传任何 props：组件完全是自包含的，不需要从外面传参数。
靠 sessionStorage 去重：每次 Swup 导航都会重建组件，但因为有 blog_visit_flag 标记，所以不会重复弹出。
兼容 Swup 的 astro 事件：客户端路由切换后也能正常触发。
构建时没有 HTML 输出：组件只有 <script> 和 <style>，不产生静态 HTML，全靠 JS 在浏览器里创建。

总结#

WelcomeToast 说白了就是一个浏览器端的欢迎弹窗，用 sessionStorage 保证每个会话只弹一次，用 IP API 拿位置做个性化问候，5 秒自动消失。放在 Firefly 主题的 MainGridLayout 里，和 Swup 的 SPA 导航机制配合得很好。

为 Firefly 添加 Umami 访问统计卡片

Fri, 29 May 2026 00:00:00 GMT

Note

这篇文章是基于 THW’s Blog 的教程改造的，感谢大佬的分享。

为什么要加统计#

搞个博客总想知道有没有人看吧。Umami 是个轻量级的统计工具，部署简单，也不会像 Google Analytics 那样隐私问题一堆。

但问题来了：Umami 自带的分享链接打开就是一个独立页面，跟博客风格完全不搭。所以我把它做成了一个侧边栏组件，嵌进博客里，打开就能看到访问数据，顺眼多了。

准备工作#

前提是你已经部署好了 Umami，然后拿到一个分享链接。后面填进代码里就行。

添加组件#

在 src/components/widget/ 目录下新建一个 UmamiStats.astro 文件，把下面的代码贴进去：

1
---
2
import WidgetLayout from "../common/WidgetLayout.astro";
3

4
interface Props {
5
  class?: string;
6
  style?: string;
7
}
8
const { class: className, style } = Astro.props;
9
---
10

11
<WidgetLayout name="统计" class:list={["umami-stats-container", className, "cursor-pointer transition-opacity active:scale-95"]} {style}>
12
    <a target="_blank" rel="noopener noreferrer" class="block umami-link">
13
        <div class="text-center py-2">
14
            <div class="text-3xl font-bold text-neutral-900 dark:text-neutral-100 umami-total-pageviews">-</div>
15
            <div class="text-sm text-neutral-500 dark:text-neutral-400">总浏览量</div>
16
        </div>
17
        <div class="grid grid-cols-2 divide-x divide-neutral-200 dark:divide-neutral-700 text-center pt-2">
18
            <div class="px-2">
19
                <div class="text-xl font-bold text-neutral-900 dark:text-neutral-100 umami-total-visits">-</div>
20
                <div class="text-sm text-neutral-500 dark:text-neutral-400">访问数</div>
21
            </div>
22
            <div class="px-2">
23
                <div class="text-xl font-bold text-neutral-900 dark:text-neutral-100 umami-total-visitors">-</div>
24
                <div class="text-sm text-neutral-500 dark:text-neutral-400">游客数</div>
25
            </div>
26
        </div>
27
    </a>
28
</WidgetLayout>
29

30
<script>
31
const UMAMI_CONFIG = {
32
    shareUrl: '你的分享链接',
33
};
34

35
let __UMAMI_INTERNAL = {
36
    baseUrl: '',
37
    websiteId: '',
38
    shareToken: '',
39
    shareId: '',
40
    isReady: false
41
};
42

43
const FALLBACK_STATS = {
44
    pageviews: 1000,
45
    visits: 1000,
46
    visitors: 1000,
47
};
48

49
async function initUmamiConfig() {
50
    try {
51
        const sharePath = UMAMI_CONFIG.shareUrl.split('/share/')[1];
52
        if (!sharePath) throw new Error('Invalid Umami Share URL');
53

54
        let apiBase = '';
55
        if (UMAMI_CONFIG.shareUrl.includes('cloud.umami.is') || UMAMI_CONFIG.shareUrl.includes('analytics.umami.is')) {
56
            const region = UMAMI_CONFIG.shareUrl.includes('/analytics/eu/') ? 'eu' : 'us';
57
            apiBase = `https://cloud.umami.is/analytics/${region}/api`;
58
        } else {
59
            const urlObj = new URL(UMAMI_CONFIG.shareUrl);
60
            apiBase = `${urlObj.origin}/api`;
61
        }
62

63
        const res = await fetch(`${apiBase}/share/${sharePath}`);
64
        if (!res.ok) throw new Error(`Failed to fetch share config: ${res.status}`);
65
        const data = await res.json();
66

67
        __UMAMI_INTERNAL = {
68
            baseUrl: apiBase,
69
            websiteId: data.websiteId,
70
            shareToken: data.token,
71
            shareId: data.shareId,
72
            isReady: true
73
        };
74

75
        const links = document.querySelectorAll('.umami-link');
76
        links.forEach(link => link.setAttribute('href', UMAMI_CONFIG.shareUrl));
77

78
    } catch (e) {
79
        console.error('Umami Config Init Failed:', e);
80
    }
81
}
82

83
function formatNumber(num: number): string {
84
    if (num >= 1000000) {
85
        return (num / 1000000).toFixed(1) + 'M';
86
    } else if (num >= 1000) {
87
        return (num / 1000).toFixed(1) + 'K';
88
    }
89
    return Math.round(num).toString();
90
}
91

92
function setStats(values: { pageviews: number; visits: number; visitors: number }) {
93
    const pageviewsElements = document.querySelectorAll('.umami-total-pageviews');
94
    const visitsElements = document.querySelectorAll('.umami-total-visits');
95
    const visitorsElements = document.querySelectorAll('.umami-total-visitors');
96

97
    const easeOutCubic = (t: number) => 1 - Math.pow(1 - t, 3);
98
    const animHandles = new Map<HTMLElement, number>();
99

100
    const animateStat = (el: HTMLElement | null, to: number, duration = 2000) => {
101
        if (!el) return;
102

103
        const prev = animHandles.get(el);
104
        if (prev) cancelAnimationFrame(prev);
105

106
        const from = 0;
107
        const startTime = performance.now();
108

109
        const tick = (now: number) => {
110
            const elapsed = now - startTime;
111
            const progress = Math.min(1, elapsed / duration);
112
            const easedProgress = easeOutCubic(progress);
113

114
            const current = from + (to - from) * easedProgress;
115
            el.textContent = formatNumber(current);
116

117
            if (progress < 1) {
118
                animHandles.set(el, requestAnimationFrame(tick));
119
            }
120
        };
121
        animHandles.set(el, requestAnimationFrame(tick));
122
    };
123

124
    pageviewsElements.forEach(el => animateStat(el as HTMLElement, values.pageviews));
125
    visitsElements.forEach(el => animateStat(el as HTMLElement, values.visits));
126
    visitorsElements.forEach(el => animateStat(el as HTMLElement, values.visitors));
127
}
128

129
async function fetchUmamiStats() {
130
    if (!__UMAMI_INTERNAL.isReady) {
131
        await initUmamiConfig();
132
    }
133

134
    if (!__UMAMI_INTERNAL.isReady) {
135
        setStats(FALLBACK_STATS);
136
        return;
137
    }
138

139
    try {
140
        const endAt = Date.now();
141
        const startAt = 0;
142
        const url = `${__UMAMI_INTERNAL.baseUrl}/websites/${__UMAMI_INTERNAL.websiteId}/stats?startAt=${startAt}&endAt=${endAt}&unit=hour&timezone=Asia%2FShanghai`;
143

144
        const response = await fetch(url, {
145
            headers: {
146
                'x-umami-share-context': '1',
147
                'x-umami-share-token': __UMAMI_INTERNAL.shareToken
148
            }
149
        });
150

151
        if (!response.ok) throw new Error(`HTTP ${response.status}`);
152
        const data = await response.json();
153
        const getValue = (field: any) => (typeof field === 'object' ? field?.value : field) || 0;
154

155
        setStats({
156
            pageviews: getValue(data.pageviews),
157
            visits: getValue(data.visits),
158
            visitors: getValue(data.visitors),
159
        });
160

161
    } catch (error) {
162
        console.error('Umami Fetch Failed:', error);
163
        setStats(FALLBACK_STATS);
164
    }
165
}
166

167
let __umamiStatsStarted = false;
168
function startUmamiStats() {
169
    if (__umamiStatsStarted) return;
170
    __umamiStatsStarted = true;
171
    fetchUmamiStats();
172
}
173

174
function initUmamiStatsVisibility() {
175
    const containers = document.querySelectorAll('.umami-stats-container');
176
    const io = new IntersectionObserver((entries) => {
177
        let isAnyVisible = false;
178
        entries.forEach(entry => {
179
            if (entry.isIntersecting) isAnyVisible = true;
180
        });
181

182
        if (isAnyVisible) {
183
            startUmamiStats();
184
            io.disconnect();
185
        }
186
    }, { threshold: 0.1 });
187

188
    containers.forEach(container => io.observe(container));
189
}
190

191
initUmamiStatsVisibility();
192

193
if (window.swup) {
194
    window.swup.hooks.on('page:view', () => {
195
        __umamiStatsStarted = false;
196
        initUmamiStatsVisibility();
197
    });
198
}
199
</script>

展开收起

配置#

代码里有个 UMAMI_CONFIG，把你的分享链接填进去就行：

1
<script>
2
const UMAMI_CONFIG = {
3
    shareUrl: '你的分享链接',  // ← 这里改成你自己的
4
};

挂到侧边栏上#

组件写好了，接下来得让它出现在页面上。打开 src/components/layout/SideBar.astro，把 UmamiStats import 进来，然后在合适的位置放上 <UmamiStats />。

下面是改完之后的完整代码，可以对照着改：

1
---
2
import type { MarkdownHeading } from "astro";
3
import Advertisement from "@/components/widget/Advertisement.astro";
4
import Announcement from "@/components/widget/Announcement.astro";
5
import Calendar from "@/components/widget/Calendar.astro";
6
import Categories from "@/components/widget/Categories.astro";
7
import Music from "@/components/widget/Music.astro";
8
import Profile from "@/components/widget/Profile.astro";
9
import SidebarTOC from "@/components/widget/SidebarTOC.astro";
10
import SiteStats from "@/components/widget/SiteStats.astro";
11
import Tags from "@/components/widget/Tags.astro";
12
import { sidebarLayoutConfig } from "@/config";
13
import type {
14
  MobileBottomComponentConfig,
15
  WidgetComponentConfig,
16
  WidgetComponentType,
17
} from "@/types/config";
18
import UmamiStats from "../widget/UmamiStats.astro";
19

20
interface Props {
21
  class?: string;
22
  headings?: MarkdownHeading[];
23
  side?: "left" | "right" | "bottom";
24
}
25

26
const SIDEBAR_SIDE = {
27
  LEFT: "left",
28
  RIGHT: "right",
29
  BOTTOM: "bottom",
30
} as const;
31

32
const COMPONENT_POSITION = {
33
  TOP: "top",
34
  STICKY: "sticky",
35
} as const;
36

37
const ANIMATION_DELAY_UNIT = 50;
38

39
const componentMap = {
40
  profile: Profile,
41
  announcement: Announcement,
42
  categories: Categories,
43
  tags: Tags,
44
  sidebarToc: SidebarTOC,
45
  advertisement: Advertisement,
46
  stats: SiteStats,
47
  calendar: Calendar,
48
  music: Music,
49
} satisfies Record<WidgetComponentType, typeof Profile>;
50

51
const side = (Astro.props.side ||
52
  SIDEBAR_SIDE.LEFT) as (typeof SIDEBAR_SIDE)[keyof typeof SIDEBAR_SIDE];
53
const className = Astro.props.class;
54

55
const getComponents = (): (
56
  | WidgetComponentConfig
57
  | MobileBottomComponentConfig
58
)[] => {
59
  if (side === SIDEBAR_SIDE.LEFT) {
60
    return sidebarLayoutConfig.leftComponents;
61
  }
62
  if (side === SIDEBAR_SIDE.RIGHT) {
63
    return sidebarLayoutConfig.rightComponents;
64
  }
65
  if (side === SIDEBAR_SIDE.BOTTOM) {
66
    return sidebarLayoutConfig.mobileBottomComponents;
67
  }
68
  return [];
69
};
70

71
const filterAndSortComponents = (
72
  components: (WidgetComponentConfig | MobileBottomComponentConfig)[],
73
) => {
74
  return components.filter((comp) => comp.enable);
75
};
76

77
const getComponentsByPosition = (
78
  components: (WidgetComponentConfig | MobileBottomComponentConfig)[],
79
) => {
80
  const topComponents = components.filter(
81
    (c) => "position" in c && c.position === COMPONENT_POSITION.TOP,
82
  ) as WidgetComponentConfig[];
83
  const stickyComponents = components.filter(
84
    (c) => "position" in c && c.position === COMPONENT_POSITION.STICKY,
85
  ) as WidgetComponentConfig[];
86
  return { topComponents, stickyComponents };
87
};
88

89
const getAnimationDelay = (index: number): string => {
90
  return `${index * ANIMATION_DELAY_UNIT}ms`;
91
};
92

93
const isPostPage = Astro.url.pathname.includes("/posts/");
94

95
const isComponentInitiallyVisible = (
96
  config: WidgetComponentConfig | MobileBottomComponentConfig,
97
): boolean => {
98
  if (
99
    "showOnPostPage" in config &&
100
    config.showOnPostPage === false &&
101
    isPostPage
102
  ) {
103
    return false;
104
  }
105
  if (
106
    "showOnNonPostPage" in config &&
107
    config.showOnNonPostPage === false &&
108
    !isPostPage
109
  ) {
110
    return false;
111
  }
112
  return true;
113
};
114

115
const getComponentProps = (
116
  config: WidgetComponentConfig | MobileBottomComponentConfig,
117
  index: number,
118
): Record<string, unknown> => {
119
  const baseProps: Record<string, unknown> = {
120
    class: "onload-animation",
121
    style: `animation-delay: ${getAnimationDelay(index)}`,
122
  };
123

124
  if ("showOnPostPage" in config && config.showOnPostPage === false) {
125
    baseProps.class = `${baseProps.class} widget-hide-on-post`;
126
    if (isPostPage) {
127
      baseProps.class = `${baseProps.class} hidden`;
128
    }
129
  }
130
  if ("showOnNonPostPage" in config && config.showOnNonPostPage === false) {
131
    baseProps.class = `${baseProps.class} widget-hide-on-non-post`;
132
    if (!isPostPage) {
133
      baseProps.class = `${baseProps.class} hidden`;
134
    }
135
  }
136

137
  if (config.type === "sidebarToc") {
138
    return { ...baseProps, headings: Astro.props.headings || [] };
139
  }
140

141
  if (
142
    config.type === "advertisement" &&
143
    "configId" in config &&
144
    config.configId
145
  ) {
146
    return { ...baseProps, configId: config.configId };
147
  }
148

149
  return baseProps;
150
};
151

152
const allComponents = getComponents();
153
const filteredComponents = filterAndSortComponents(allComponents);
154

155
const isMobileBottom = side === SIDEBAR_SIDE.BOTTOM;
156
const { topComponents, stickyComponents } = !isMobileBottom
157
  ? getComponentsByPosition(filteredComponents)
158
  : { topComponents: [], stickyComponents: [] };
159
const bottomComponents = isMobileBottom ? filteredComponents : [];
160
const hasInitiallyVisibleTopComponents = topComponents.some(
161
  isComponentInitiallyVisible,
162
);
163

164
let mobileProfileComp: MobileBottomComponentConfig | undefined;
165
let mobileOtherComponents: MobileBottomComponentConfig[] = [];
166

167
if (isMobileBottom) {
168
  mobileProfileComp = bottomComponents.find((comp) => comp.type === "profile");
169
  mobileOtherComponents = bottomComponents.filter(
170
    (comp) => comp.type !== "profile",
171
  );
172
}
173

174
const hasStickyContent =
175
  stickyComponents.length > 0 || side === SIDEBAR_SIDE.LEFT;
176
---
177

178
{
179
  (topComponents.length > 0 || stickyComponents.length > 0 || bottomComponents.length > 0 || hasStickyContent) && (
180
    <div id={`${side}-sidebar`} class:list={[className, "flex flex-col w-full pt-0"]}>
181
      {isMobileBottom ? (
182
        <div class="flex flex-col w-full gap-4">
183
          {mobileProfileComp && (() => {
184
            const Component = componentMap[mobileProfileComp.type];
185
            if (!Component) return null;
186
            const props = getComponentProps(mobileProfileComp, 0) as any;
187
            return <Component {...props} />;
188
          })()}
189

190
          <UmamiStats class="onload-animation" style="animation-delay: 50ms" />
191

192
          {mobileOtherComponents.map((comp, index) => {
193
            const Component = componentMap[comp.type];
194
            if (!Component) return null;
195
            const props = getComponentProps(comp, index + 2) as any;
196
            return <Component {...props} />;
197
          })}
198
        </div>
199
      ) : (
200
        <>
201
          {topComponents.length > 0 && (
202
            <div
203
              class:list={[
204
                "flex flex-col w-full gap-4",
205
                hasInitiallyVisibleTopComponents && "mb-4",
206
              ]}
207
            >
208
              {topComponents.map((comp, index) => {
209
                const Component = componentMap[comp.type];
210
                if (!Component) return null;
211
                const props = getComponentProps(comp, index) as any;
212
                return <Component {...props} />;
213
              })}
214
            </div>
215
          )}
216

217
          {hasStickyContent && !isMobileBottom && (
218
            <div
219
              id={`${side}-sidebar-sticky`}
220
              class:list={[
221
                "flex flex-col w-full mt-0 gap-4",
222
                "sticky",
223
                hasInitiallyVisibleTopComponents ? "top-4" : "top-0",
224
              ]}
225
            >
226
              {side === SIDEBAR_SIDE.LEFT && (
227
                <UmamiStats class="onload-animation" style="animation-delay: 200ms" />
228
              )}
229

230
              {stickyComponents.map((comp, index) => {
231
                const Component = componentMap[comp.type];
232
                if (!Component) return null;
233
                const props = getComponentProps(
234
                  comp,
235
                  topComponents.length + index
236
                ) as any;
237
                return <Component {...props} />;
238
              })}
239
            </div>
240
          )}
241
        </>
242
      )}
243
    </div>
244
  )
245
}

展开收起

结尾#

搞定了。现在每次打开博客，侧边栏就会自动加载 Umami 的访问数据，还有个数字滚动的动画效果，看着还挺舒服的。如果数据拉不到（比如 API 挂了），会自动显示 fallback 的数字，不至于空空的。

NVIDIA Build：免费 AI API

Fri, 29 May 2026 00:00:00 GMT

免费 API#

NVIDIA Build 的免费额度挺大方的，每分钟 40 次请求，日常开发完全够用。

模型也挺丰富，DeepSeek V4 Pro、DeepSeek V4 Flash 这些都有，还有云端 GPU 实例可以免费试用。

如果你想体验一下最新的 AI 模型又不想花钱，这个平台目前是最值得薅的。

一个非常NB的IP优选

Sun, 24 May 2026 00:00:00 GMT

在 MIFENG の主页上发现了一个 IP 优选项目，用起来挺顺手的。

开源免费，不需要折腾太多配置，直接上手就能用。

网址：NB优选

论二模试卷上的错误

Sat, 23 May 2026 00:00:00 GMT

众所周知我是一名初二学生，在5月21日这么浪漫的一天，我考玩了地理和生物的二模。发现试卷上有些低级错误。

地理#

赤道周长写错了成了赤道昼长。

地理

生物#

肺泡写成了胚泡。

生物

所以，试卷是不需要审核的吗。错别字都能出现。果然世界就是一个巨大的草台班子。

转载止战之殇

Wed, 13 May 2026 00:00:00 GMT

止战之殇#

雷德王还有3个小时降临地球，世界各大媒体平台将这条消息传唤的沸沸扬扬，他的到来，是救赎还是毁灭，我无从得知，众说纷纭，我只想先吃个汉堡吧。

宇宙无穷，人生微渺，我从一无所有中来，自当归于虚无。唯独让我牵挂难以放下执念的，便是学校的汉堡了，汉堡不大，面包很干，初相识于三年前，我年少，它缥纱，浅尝一口：“哇”很好吃。可惜后来吃饭时间越来越晚，与曾经的挚爱想重逢却要隔着人山人海，我等了一次又一次。

可惜不悔梦归处，只恨太匆匆，不知什么时候起，汉堡的肉饼变成了自制小牛肉，陈然多了一份人情味，少了一份预制感，但干燥的触感与同样燥干的面饼相结合，让我失去了对其往日的热爱，或者它也不能称之为那个它了。

学校门口的餐车最近上了汉堡，用的和学校同样的佐料，不过是曾经的面饼一样的干，早上考试我又饿又渴，买了个汉堡，更渴了。

可字宙苍茫，谁又能主宰学校的汉堡呢?其实世间一切自有定数，我不信奉佛陀，自我信仰上帝，也许那全知全能的主会将仁爱的汉堡撒下大地，在我活着，或在我死后。

雷德王降临了，在维多利亚港。

没有谈判，硝烟中，炮火轰鸣中，世界想去了色彩。

我到了，因为我必须来，作为新时代新青年，肩负历史使命与伟大复兴重担，拯救世界，舍我其谁?

可站在雷德王脚下那一刻，我才意识到自己有多弱小，他比自由女神像还要大，尽管我没去过美国，但我刷过视频。

雷德王停下进攻的脚步，低头看我，示意我把手给他，我不敢拒绝却也止不住的颤抖，原来他是要我手中的汉堡啊，看来无论何等高级的生命都无法抵御汉堡的诱惑。

一颗子弹贯穿我的胸膛，临死前耳畔传来的话语，在说我通敌。

哈哈哈，这就是人性吗?雷德王，我开始理解你了，不过，突然……好想吃个汉堡····

原文图,请以倒观方式观看

Linux（Debian 系）上搭建 C++ 开发环境

Sat, 02 May 2026 00:00:00 GMT

介绍#

Linux 做 C++ 开发确实舒服，工具链齐全，编译速度也快。这篇文章手把手教你在 Debian 系的 Linux 上，用 VS Code + Clang + CMake + Ninja + vcpkg 搭一套现代化的开发环境，最后还会用 C++20 模块跑一个示例项目。

需要装的东西#

编译器：Clang
项目构建器：CMake
本地构建器：Ninja
依赖包管理：vcpkg

安装和配置#

1. 安装 Clang 编译器#

Clang 的错误提示比 GCC 友好很多，而且对新标准的支持一直很积极。截至 2026 年 4 月，最新稳定版是 Clang 22.1.3。Clang 23 已经有预发布版了，但建议还是用稳定的。

用 LLVM 官方脚本装最省事：

Terminal window

1
wget https://apt.llvm.org/llvm.sh
2
chmod +x llvm.sh
3
sudo ./llvm.sh 22

脚本跑完会自动添加 LLVM 的 APT 仓库，然后装好 clang-22 和相关工具。

装完之后设一下默认版本，这样终端里直接输 clang 就能用：

Terminal window

1
sudo update-alternatives --install /usr/bin/clang clang /usr/bin/clang-22 100
2
sudo update-alternatives --install /usr/bin/clang++ clang++ /usr/bin/clang++-22 100
3
sudo update-alternatives --install /usr/bin/clangd clangd /usr/bin/clangd-22 100
4
sudo update-alternatives --install /usr/bin/lldb lldb /usr/bin/lldb-22 100
5
sudo update-alternatives --install /usr/bin/lld lld /usr/bin/lld-22 100
6
sudo update-alternatives --install /usr/bin/clang-tidy clang-tidy /usr/bin/clang-tidy-22 100
7
sudo update-alternatives --install /usr/bin/clang-format clang-format /usr/bin/clang-format-22 100

跑完 clang --version 看一下，输出里有 “clang version 22.1.3” 就说明装好了。

2. 安装 CMake 构建系统#

CMake 是 C++ 项目构建的标配，能生成各种构建系统需要的文件。当前最新稳定版是 CMake 4.3.1。

从官方下载安装脚本：

Terminal window

1
wget https://github.com/Kitware/CMake/releases/download/v4.3.1/cmake-4.3.1-linux-x86_64.sh

Terminal window

1
chmod +x cmake-4.3.1-linux-x86_64.sh
2
sudo ./cmake-4.3.1-linux-x86_64.sh --prefix=/opt/cmake-4.3.1 --skip-license

然后配一下默认版本：

Terminal window

1
sudo update-alternatives --install /usr/bin/cmake cmake /opt/cmake-4.3.1/bin/cmake 100
2
sudo update-alternatives --install /usr/bin/ctest ctest /opt/cmake-4.3.1/bin/ctest 100
3
sudo update-alternatives --install /usr/bin/cpack cpack /opt/cmake-4.3.1/bin/cpack 100

cmake --version 能看到 4.3.1 就 OK 了。

3. 安装 Ninja 构建工具#

Ninja 专注速度，配合 CMake 用编译特别快。目前最新稳定版是 1.13.2。

从 GitHub 下载预编译的二进制文件，解压放到系统路径里就行：

Terminal window

1
wget https://github.com/ninja-build/ninja/releases/download/v1.13.2/ninja-linux.zip
2
unzip ninja-linux.zip
3
sudo mv ninja /usr/bin/ninja
4
sudo chmod +x /usr/bin/ninja
5
ninja --version

4. 安装 vcpkg 包管理器#

vcpkg 是微软出的 C++ 库管理器，装第三方库特别方便，不用手动折腾依赖。最新稳定版是 2026.04.08。

Terminal window

1
cd ~
2
git clone https://github.com/microsoft/vcpkg.git
3
cd vcpkg
4
# Linux 下用 .sh 结尾的引导脚本
5
./bootstrap-vcpkg.sh

装好后把路径加到环境变量里，编辑 ~/.bashrc 或 ~/.zshrc：

Terminal window

1
export PATH=/opt/cmake-4.3.1/bin:$PATH
2
export VCPKG_ROOT=~/vcpkg
3
export PATH=$VCPKG_ROOT:$PATH

改完重启终端或者 source ~/.bashrc，然后 vcpkg --version 看看版本就对了。

5. Visual Studio Code#

VS Code 做 C++ 开发挺好用的（当然你也可以用 CLion 之类的）。装好之后去扩展市场搜这几个插件：

Clangd（作者: LLVM）：代码补全、跳转、实时诊断，比微软的 C/C++ 插件好用。
CodeLLDB（作者: Vadim Chugunov）：本地调试器，跟 VS Code 集成得很好。
CMake Tools（作者: Microsoft）：直接在 VS Code 里配置、构建、运行 CMake 项目。
CMake（作者: Microsoft）：给 CMakeLists.txt 提供语法高亮。

构建和运行你的第一个程序#

用 C++20 的模块特性来写第一个项目。

项目结构#

建一个项目文件夹，结构长这样：

1
CppProject/
2
├── .vscode/
3
│   └── launch.json      # 调试配置（后面会创建）
4
├── CMakeLists.txt       # CMake 项目配置
5
├── CMakePresets.json    # CMake 预设
6
├── main.cpp             # 主程序
7
├── utilities.ixx        # 一个简单的 C++20 模块
8
└── vcpkg.json           # vcpkg 依赖描述

不知道这些文件里写什么的话，把这篇文章丢给 AI 让它帮你生成。

配置代码和调试器#

utilities.ixx 模块文件：

1
module;
2
#include <string>
3
export module utilities;
4
export auto get_greeting() {
5
    return "Hello from a C++20 Module!";
6
}

主程序 main.cpp：

1
import utilities;
2
#include <fmt/core.h>
3
int main() {
4
    fmt::print("{}\n", get_greeting());
5
    return 0;
6
}

调试配置文件 .vscode/launch.json，注意 program 的路径要跟你的构建输出目录对上：

1
{
2
    "version": "0.2.0",
3
    "configurations": [
4
        {
5
            "type": "lldb",
6
            "request": "launch",
7
            "name": "Debug (LLDB)",
8
            "program": "${workspaceFolder}/build/linux_clang/Debug/Rocket",
9
            "args": [],
10
            "cwd": "${workspaceFolder}"
11
        }
12
    ]
13
}

配置、构建与运行#

1. 选择预设#

在 VS Code 里打开项目文件夹，Ctrl+Shift+P 打开命令面板，输入 CMake: Select Configure Preset，根据你的系统和编译器选一个合适的预设。

2. 开始构建#

再打开命令面板，输入 CMake: Build，或者直接按 F7。CMake 会调用 Clang 和 Ninja 来编译和链接。

3. 运行与调试#

构建成功后，点 VS Code 底部的 ▶️ 按钮就能运行。设好断点按 F5 启动调试，F10 单步执行，变量值也能实时看到。

总结#

搞定了，你现在有了一套完整的现代化 C++ 开发环境。不管是自己学习还是团队协作都能用。

有两个要注意的地方：

装完所有工具后，记得用 --version 一个个验证版本，确保环境变量没配错。
launch.json 是项目的调试启动配置，新建项目的时候记得把这个文件复制过去，然后把 program 字段改成新项目的可执行文件路径。
CMakeLists.txt 和 CMakePresets.json 不知道怎么写的话，直接问 AI 就行。

Linux 上安装和使用 AstrBot

Sat, 25 Apr 2026 00:00:00 GMT

AstrBot 是什么#

AstrBot 是一个开源的聊天机器人框架，轻量好用，能对接 QQ、微信、飞书这些平台。自带插件系统和可视化面板，社区里已经有上千款插件了，做自动回复、群管理、定时任务什么的都挺方便的。

安装#

在 Linux 终端里跑这个脚本就行：

Terminal window

1
bash <(curl -sSL https://raw.githubusercontent.com/zhende1113/Antlia/refs/heads/main/Script/AstrBot/Antlia.sh)

如果你的系统没装 curl，用 wget 也行：

Terminal window

1
wget -qO- https://raw.githubusercontent.com/zhende1113/Antlia/refs/heads/main/Script/AstrBot/Antlia.sh | bash

Tip

如果 uv sync 报错，可以试试设置环境变量：

Terminal window

1
echo 'export UV_LINK_MODE=copy' >> ~/.bashrc
2
source ~/.bashrc

然后正常启动：

Terminal window

1
cd AstrBot
2
uv run main.py

如果下载依赖时遇到网络问题，可以换成国内镜像源：

Terminal window

1
echo 'export UV_DEFAULT_INDEX="https://pypi.tuna.tsinghua.edu.cn/simple"' >> ~/.bashrc
2
source ~/.bashrc

AstrBot 仓库

AstrBot 官方文档

脚本仓库

Cloudflare Worker 优选

Sat, 25 Apr 2026 00:00:00 GMT

什么是优选#

说白了就是挑一个国内访问更快的 Cloudflare 节点。

Cloudflare 默认分配给你的 IP，国内访问延迟可能很高，甚至直接打不开。通过优选，我们可以手动把域名解析到那些国内访问快的 Cloudflare IP 上，速度会明显提升。

要实现优选，核心就两件事：自己控制路由规则 + 自己控制 DNS 解析。

寻找优选域名#

可以用社区大佬做的这个网站来获取优选域名。

Worker 优选方法#

打开你的 Worker 项目，添加一条路由，路由格式填 你的域名/*：

路由示例

然后去域名 DNS 设置里加一条记录，类型选 CNAME。名称根据你路由里填的内容来定：比如你路由填的是 blog.example.com，这里名称就填 blog（前提是域名 example.com 托管在 Cloudflare 上）。如果路由填的域名跟你托管的域名一样，直接填 @。最后目标填从社区网站复制下来的优选域名就行。

DNS记录示例

Tip

优选的前提是你有一个域名托管在 Cloudflare 上。路由里记得在域名后面加 /*，不然优选只对根域名生效。

年华

GitHub Actions 自动构建并部署 Cloudflare Workers 实现思路

为什么要搞这个#

整体流程#

实现思路#

1. 触发条件#

2. 环境准备#

3. 构建项目#

4. 推送到 build 分支#

5. 部署到 Cloudflare Workers#

完整源码#

需要配置的 Secrets#

注意事项#

Firefly 主题 添加WelcomeToast 组件

Firefly 主题 WelcomeToast 组件分析#

涉及的文件#

组件是怎么实现的#

页面上长什么样#

几个关键函数#

执行顺序#

怎么适配 SPA 导航的#

样式部分#

在 MainGridLayout 里怎么放的#

几个值得注意的点#

总结#

为 Firefly 添加 Umami 访问统计卡片

为什么要加统计#

准备工作#

添加组件#

配置#

挂到侧边栏上#

结尾#

NVIDIA Build：免费 AI API

免费 API#

一个非常NB的IP优选

论二模试卷上的错误

地理#

生物#

转载止战之殇

止战之殇#

Linux（Debian 系）上搭建 C++ 开发环境

介绍#

需要装的东西#

安装和配置#

1. 安装 Clang 编译器#

2. 安装 CMake 构建系统#

3. 安装 Ninja 构建工具#

4. 安装 vcpkg 包管理器#

5. Visual Studio Code#

构建和运行你的第一个程序#

项目结构#

配置代码和调试器#

配置、构建与运行#

1. 选择预设#

2. 开始构建#

3. 运行与调试#

总结#

Linux 上安装和使用 AstrBot

AstrBot 是什么#

安装#

Cloudflare Worker 优选

什么是优选#

寻找优选域名#

Worker 优选方法#

Firefly 主题添加WelcomeToast 组件