千灵

Back
/ Update
20 min
开发 /
博客

Astro Pure 主题修改记录

详述博客主题的修改过程，包含：BUG修复、性能优化、功能增加、链接层级简化、DNS 加速，并附带面向 AI Agent 的修改 Prompts。
views | comments

📌 本文重点讲述各项修改的原因及效果，提供面向 AI Agent 的修改 Prompt，以便提高跨主题修改的兼容性并给予 AI 更多技术改进空间。

1. 文章链接层级简化#

为了让文章链接①看起来更精简、②更利于 SEO、③兼容 Hexo 历史文章的链接格式，我将博客文章的 URL 路由由 /blog/{id} 修改为了 /{id}。

  • Astro 默认链接示例：https://astro-pure.js.org/blog/improve-concentration
  • 层级简化后链接示例：https://astro-pure.js.org/improve-concentration

以下是修改 Prompt：

2. 链接末尾增加斜杠/（Cloudflare Pages 可选）#

修改背景说明：

  1. Astro 生成的链接末尾无斜杠 /，而 Cloudflare Pages 有强制 URL 规范化机制，如果用户访问了末尾无斜杠的链接，Cloudflare Pages 为了防止相对路径资源加载出错、搜索引擎生成重复页面，会自动发送一个 301 永久重定向，将用户引导至带斜杠的标准的目录地址：/posts/my-blog/，会略微降低网站速度。
  2. Waline 评论系统对 URL 敏感，链接末尾有无 / 会视为不同链接，导致同一篇文章的数据被分离到两个不同链接。

因此我在 Astro 配置文件 astro.config.ts 中设置了 trailingSlash: 'always'，开启强制尾部加斜杠功能。

但开启后，本地预览时，跨页面跳转会因链接尾部不带斜杠而报错。为此，我给博客整体的内部跳转链接追加了尾部 /。

以下是修改 Prompt：

3. Pagefind 搜索噪音过滤（BUG修复）#

原主题未遵守 Pagefind 规范，没有标记正文内容区域，导致 Pagefind 索引了整个 <body>，搜索结果出现页眉导航和页脚版权信息，我已提交 Issue：Pagefind integration missing data-pagefind-body attribute, causing full indexing #164 ↗，当前未修复。

以下是修改 Prompt：

# Pagefind Search Scope Fix

- **Goal**: Fix Pagefind indexing all `<body>` content instead of only article body, causing search noise from header/footer/sidebar
- **Reason**: Pagefind logs `Did not find a data-pagefind-body element on the site` and falls back to indexing entire `<body>`, including navigation, footer, and sidebar text

## Changes

1. **Added** **`data-pagefind-body`** **to ContentLayout**
   - File: `src/layouts/ContentLayout.astro`
   - Change: `<article class='min-w-0 grow'>` → `<article data-pagefind-body class='min-w-0 grow'>`
   - Detail: Pagefind will now only index article content (title + body) on Markdown blog post pages
2. **Added** **`data-pagefind-body`** **to IndividualPage**
   - File: `src/layouts/IndividualPage.astro`
   - Change: `<article class='min-w-0 grow'>` → `<article data-pagefind-body class='min-w-0 grow'>`
   - Detail: Pagefind will now only index article content on standalone pages (e.g., links, about)
plaintext

4. 文章时间逻辑修改#

我经常更新历史文章，而主题的文章排序函数取值更新日期，导致旧文章一更新：

  • 在首页中会排至最前，但缩略卡片中显示发布日期（如 2026 年更新的文章却显示 2017 年的创建日期），让读者困惑，误以为博客很久未更新。
  • 在归档页中，文章按更新日期所属年份归类，而非按发布日期，不合常理。

以下是修改 Prompt：

4.1 首页文章展示日期修改#

# Homepage Article Date Shows Updated Date

- **File**: `src/pages/index.astro`
- **Goal**: Show the last modified date (updatedDate) instead of publish date for articles in the homepage list
- **Change**: Updated time display logic (line 95)
- **Detail**:
  - Before: `{p.data.publishDate.toISOString().split('T')[0].replace(/-/g, '/')}`
  - After: `{(p.data.updatedDate ?? p.data.publishDate).toISOString().split('T')[0].replace(/-/g, '/')}`
  - Uses `updatedDate` when available, falls back to `publishDate` if not set
  - Consistent with `BlogPost.astro` which uses `updatedDate?.toISOString() ?? publishDate.toISOString()` for article metadata
plaintext

4.2 归档页文章排序逻辑修改#

5. 文章置顶#

文章置顶效果图

我有一篇长期维护文章「iOS 旧版 APP 推荐与降级方法（持续更新）」，为了避免其被新发布内容降低排序位置，让读者快速找到，需增加置顶功能，参考了该 Issue：新增文章置顶功能？ #122 ↗。

以下是修改 Prompt：

6. 赞助（Sponsorship）模块移动至 About 页#

赞助模块默认放置在 Project 页，因我关闭了该分页，便将赞助模块转移至 About 页底部。

以下是修改 Prompt：

7. Waline 修改#

7.1 Waline 错误换行修复（BUG修复）#

因 Astro Pure CSS 错误，Waline 中被回复人的 @用户名 名称标签与回复内容不同行，我已提交 Issue：[bug] Waline reply “@username” wraps onto a new line instead of staying inline #165 ↗，当前未修复。

站点统计卡片

以下是修改 Prompt：

7.2 Waline 自定义 Emoji 支持第三方 CDN#

Astro Pure 主题的评论组件不支持自定义表情包链接的写法 emoji: ['tw-emoji', 'https://cdn.jsdelivr.net/gh/Druadach/bili-emoji@v1.0.1']，因此修改。

以下是修改 Prompt：

# Waline Emoji CDN Support

- **File**: `src/components/waline/Comment.astro`
- **Goal**: Support both preset names and full CDN URLs for emoji packs
- **Change**: Updated emoji processing logic (line 41-45)
- **Detail**:
  - Added URL detection: if preset starts with `http`, use it directly
  - Otherwise, prepend `${npmCDN}/@waline/emojis@1.2.0/` as before
  - Enables using third-party emoji packs like `https://cdn.jsdelivr.net/gh/Druadach/bili-emoji@v1.0.1`
  - Fixed TypeScript type error: moved `as WalineEmojiPresets` cast to wrap entire ternary expression
plaintext

7.3 去除文章反应的暗色滤镜#

Astro Pure 主题默认给文章反应的图片加了层变暗 25% 的滤镜，因此若自定义了文章反应图片，显示效果将不符预期。

若使用主题默认的 ♡ 符号则无需修改。

以下是修改 Prompt：

# Remove Waline Reaction Image Invert Filter

- **File**: `src/components/waline/Comment.astro`
- **Goal**: Remove CSS `filter: invert()` on reaction images that caused them to appear black
- **Change**: Deleted two CSS rules (light mode `invert(25%)` and dark mode `invert(75%)`)
- **Detail**:
  - Removed `#waline :global(.wl-reaction img) { filter: invert(25%); }`
  - Removed `:global(.dark) #waline :global(.wl-reaction img) { filter: invert(75%); }`
  - Reaction images now display their original colors
plaintext

8. 移动端表格横向滚动修复（BUG修复）#

因 UnoCSS 的预设属性错误，当表格内容溢出手机屏幕后，无法左右滑动表格查看，我已提交 Issue：[bug] Tables in blog posts do not scroll horizontally on mobile devices #166 ↗，当前未修复。

以下是修改 Prompt：

9. 移除外部英文字体#

Astro 从外部加载 Satoshi 作为默认的英文字体，对于中文内容为主的博客来说可精简，以提高网站性能。

以下是修改 Prompt：

10. 增加 Vercount 站点计数#

为了统计网站访问量，我本想使用 busuanzi ↗，但在 Astro 中存在重复统计数据问题：载入一次网页记录多次 PV。

故改用 Vercount ↗ 并在首页配置了站点统计卡片以展示数据。

站点统计卡片

BUG：Vercount 在较老浏览器中，如 iOS 15.4 的 Safari 上无法加载数据，我特别做了兜底修复。

以下是修改 Prompt：

11. Google Analytics 轻量版#

为了分析流量数据，博客引入了 Google Analytics，但官方脚本非常臃肿，高达 275.7 KB 且无法精简，脚本的大部分功能在个人博客上并未使用，拖慢页面加载速度。

Lighthouse 分析结果

为此，改用极其轻量、大小仅 8.8 KB 的第三方脚本 GA4MP ↗。

以下是修改 Prompt：

12. 本地预览防数据污染#

为防止 Waline 文章浏览量统计、vercount 访问量统计、Google Analytics 流量统计在本地调试时因频繁刷新页面导致数据虚高，我增加了本地开发环境过滤。

以下是修改 Prompt：

# Localhost exclusion
   - **Files**: `src/layouts/BaseLayout.astro`, `src/components/waline/Pageview.astro`, `src/components/waline/Comment.astro`
   - **Change**:
     - `BaseLayout.astro`: Added `if (location.hostname === 'localhost' || location.hostname === '127.0.0.1') return;` guard before loading Vercount and Google Analytics
     - `Pageview.astro`: Added same guard before loading Waline pageview count
     - `Comment.astro`: Added `pageview: location.hostname !== 'localhost' && location.hostname !== '127.0.0.1'` after `...walineConfig.additionalConfigs` spread to override `pageview: true` from config
   - **Detail**: Waline pageview has two entry points — standalone `Pageview.astro` script and `walineInit` in `Comment.astro` (which reads `pageview: true` from `additionalConfigs`). The `pageview` key must be placed **after** the spread to avoid being overridden by `additionalConfigs.pageview: true`
plaintext

13. 国内 DNS 加速（仅 Cloudflare Pages 需要）#

因博客访问量太大，我选择托管在不限流量的 Cloudflare Pages 上，但域名解析也被迫转交给了 Cloudflare，国内访客被分配到延迟高的美国节点。

我参考了这篇教程的 Worker 路由反代方案（日请求量需＜10万），成功把延迟从 180ms 降低到了 90ms 左右：试试Cloudflare IP优选！让Cloudflare在国内再也不是减速器！ ↗。

ITdog 测速结果

14. 修复旧版浏览器丢失文章样式问题（可选）#

因 UnoCSS 的这个问题：CSS Nesting syntax introduced in unocss@66.5 preset-typography breaks compatibility with older browsers #4971 ↗。

在不支持 CSS 原生嵌套的较老浏览器上，无法解析 UnoCSS 生成的嵌套 CSS 导致文章丢失样式。

ITdog 测速结果

以下是修改 Prompt：

# Fix Safari 15.4 Prose Styles (LightningCSS)

- **Goal**: Fix article content losing all typography styles on Safari 15.4 (mobile)
- **Reason**: UnoCSS v66.5+ `preset-typography` generates native CSS nesting syntax, which Safari 15.4 does not support. This causes all `.prose` rules (headings, paragraphs, lists, blockquotes, etc.) to be silently ignored. See [unocss/unocss#4971](https://github.com/unocss/unocss/issues/4971)
- **TODO**: Once UnoCSS merges [#5062](https://github.com/unocss/unocss/pull/5062) (adds `compatibility.nestable: false` option) or releases a fix, consider removing this workaround and using the upstream solution instead

## Changes

1. **Added LightningCSS transformer**
   - File: `astro.config.ts`
   - Change: Added `vite: { css: { transformer: 'lightningcss' } }` to `defineConfig`
   - Effect: Vite uses LightningCSS to flatten nested CSS output from UnoCSS into flat selectors, compatible with older browsers
2. **Installed `lightningcss` dependency**
   - Command: `npm install lightningcss --legacy-peer-deps`
plaintext
Astro Pure 主题修改记录
https://qianling.pw/astro-pure-theme-optimization/
Author 千灵
Published at May 30, 2026
Copyright CC BY-NC-SA 4.0
赞赏支持 ☕

自用免费 AI 模型渠道

博客更新志
Comment seems to stuck. Try to refresh?✨