2.1 环境配置#

项目使用 pnpm 作为包管理器，在 Windows 下如果遇到安装失败，记得在 .npmrc 中添加：

1
node-linker=hoisted

2.2 站点配置#

所有配置集中在 src/config.ts：

1
export const siteConfig = {
2
  title: 'BG4JTS 的博客',
3
  subtitle: '记录与思考',
4
  lang: 'zh-CN',
5
  themeColor: { hue: 220, fixed: false },
6
  banner: { enable: true, src: '/images/banner.jpg', position: 'center' },
7
  favicon: [...],
8
};
9

10
export const profileConfig = {
11
  name: 'BG4JTS',
12
  bio: '开发者 · 创作者',
13
  avatar: '/avatar.jpg',
14
  links: [...],
15
};

3.1 文章置顶#

功能：在文章 Frontmatter 中添加 sticky: true，即可将文章固定在列表最前面。

实现：修改 src/utils/content-utils.ts 中的排序逻辑，先按 sticky 排序，再按日期排序。

1
const sorted = posts.sort((a, b) => {
2
  if (a.data.sticky && !b.data.sticky) return -1;
3
  if (!a.data.sticky && b.data.sticky) return 1;
4
  return b.data.published.getTime() - a.data.published.getTime();
5
});

使用：

1
---
2
title: 置顶文章
3
sticky: true
4
---

（难绷写完才发现官方有这个功能）

3.2 文章更新提醒#

功能：在文章顶部显示「本文最后更新于 X 天前」，超过阈值天数时显示提醒。

文件：src/components/widget/UpdateNotice.astro

使用：在 src/pages/posts/[...slug].astro 中，标题下方添加：

1
<UpdateNotice published={entry.data.published} updated={entry.data.updated} thresholdDays={7} />

3.3 相关文章推荐#

功能：基于文章标签，自动推荐共享标签最多的 4 篇文章。

文件：src/components/widget/RelatedPosts.astro

使用：在文章底部添加：

1
<RelatedPosts currentSlug={entry.slug} tags={entry.data.tags || []} limit={4} />

4.1 阅读进度条#

功能：页面顶部显示细长的阅读进度条，跟随滚动实时更新。

文件：src/components/widget/ReadingProgress.astro

使用：在 src/layouts/Layout.astro 的 <body> 开始处添加：

1
<ReadingProgress />

4.2 文章目录高亮#

功能：滚动文章时，右侧目录自动高亮当前阅读章节。

文件：src/components/widget/TocHighlight.astro

使用：在 src/pages/posts/[...slug].astro 的 </MainGridLayout> 后添加：

1
<TocHighlight />

4.3 键盘快捷键#

功能：支持 j/k 上下翻页、h 回到首页、t 回到顶部、? 显示帮助。

按键映射：

文件：src/components/widget/KeyboardShortcuts.astro

使用：在 src/layouts/Layout.astro 的 </body> 前添加：

1
<KeyboardShortcuts />

5.1 Giscus 评论系统#

功能：基于 GitHub Discussions 的评论系统，评论数据存储在 GitHub 仓库中。

配置步骤：

1. 创建公开仓库并启用 Discussions
2. 安装 Giscus GitHub App
3. 在 giscus.app 获取配置参数
4. 创建 src/components/widget/GiscusComment.astro
5. 在文章页面中引入

文件：src/components/widget/GiscusComment.astro

5.2 Umami 访问统计#

功能：轻量、隐私友好的网站分析。

配置：在 src/config.ts 中填写：

1
umamiConfig: {
2
  enable: true,
3
  baseUrl: 'https://cloud.umami.is',
4
  shareId: '你的ShareID',
5
  timezone: 'Asia/Shanghai',
6
},

5.3 分享组件#

功能：支持复制链接、复制标题+链接、QQ分享、二维码生成及 PNG/SVG 下载。

文件：src/components/misc/ShareButtons.astro

使用：在文章底部添加：

1
<ShareButtons url={Astro.url} title={entry.data.title} />

6.1 友情链接页面#

功能：展示友链卡片，支持通过 JSON 数据管理，申请流程通过 GitHub PR 完成。

数据结构 src/data/links.json：

1
[
2
  {
3
    "name": "站点名",
4
    "avatar": "头像URL",
5
    "description": "一句话简介",
6
    "url": "https://你的站点/"
7
  }
8
]

文件：src/pages/links.astro

访问路径：/links/（配置了 trailingSlash: 'always'，会自动重定向）

6.2 工具聚合框架#

功能：将多个独立工具部署在单独的 Vercel 项目中，通过 Cloudflare Worker 转发到 /tools/* 路径。

项目结构：

1
tools-hub/
2
├── public/
3
│   ├── hyw/          # 何意为
4
│   │   └── index.html
5
│   └── 工具名/
6
│       └── index.html
7
├── vercel.json       # 路由重写配置
8
└── package.json

vercel.json：

1
{
2
  "rewrites": [
3
    { "source": "/tools/:path*", "destination": "/:path*" }
4
  ]
5
}

7.1 Vercel 部署#

项目托管在 Vercel，每次 git push 自动构建部署。

7.2 Cloudflare Workers 国内加速#

通过 Cloudflare Worker 做路径转发，实现国内访问加速。

Worker 代码：

1
export default {
2
  async fetch(request) {
3
    const url = new URL(request.url);
4
    const path = url.pathname;
5

6
    if (path.startsWith('/tools/')) {
7
      const targetUrl = `https://tools-hub.vercel.app${path}`;
8
      return fetch(new Request(targetUrl, request));
9
    }
10

11
    const targetUrl = `https://bg4jts.vercel.app${path}`;
12
    return fetch(new Request(targetUrl, request));
13
  }
14
};

关键配置：

• DNS 记录开启 Cloudflare 代理（橙色云朵）
• Worker 路由：*bg4jts.cn/*
• 转发时保留 Host 头

关于功能选择#

不是所有功能都适合每个博客。我的原则是：

• 读者能看到的功能（进度条、TOC、分享）优先做
• 后台能省力的功能（置顶、友链 JSON 管理）值得做
• 炫技但无用的功能（动态背景、音乐播放器）暂时不做

关于维护成本#

友链用 JSON + PR 流程管理，比在页面里硬编码好维护得多。数据与视图分离，更新友链不需要动代码。

关于性能#

Astro 本身已经足够快。新增的功能基本都是客户端 JavaScript，不会影响首屏加载速度。唯一要注意的是不要引入过大的第三方库。