こんにちは、Astro - 澄沨的漫游茶记

澄沨

简中赛博养老人

站点统计

文章

85

分类

4

标签

54

字数

221,902

运行天数

0 天

最后活动

0 天前

澄沨

简中赛博养老人

澄沨

简中赛博养老人

2505 字

7 分钟

こんにちは、Astro

2026-07-25

人生再開記録課

维护记录

/

Hexo

/

Astro

NOTE
newskin | 养病中低浮上

迁移背景#

自把敝站从 WordPress 迁到 Hexo，已三年有余。彼时 Astro 才刚刚发布第一个 Beta 版本不久，尚不为在下所知。直到 2023 年底，在下才终于了解到这个推行「群岛架构」的框架，不过当时的 Astro 社区生态还处于起步阶段，对于低技术力的在下来说，将其作为博客框架来用还为时尚早。况且，Volantis 主题的优化做得还不错，在下也没有在博客里塞进大量的 JavaScript 资源，因而 Lighthouse 评分还是看得过去的。另外，敝站的部署早就扔到了 Serverless 服务上运行，对部署时间的长短并不敏感，对服务器渲染更是没有要求，因此，没有必要追求那一点点性能提升而放弃现有成熟的解决方案。

虽然如此，在下依旧对 Astro 的 View Transitions API 印象深刻，无论是切换页面时的体验还是平滑的原生动画，都是老旧的 Hexo 打补丁所不能及的。因此，在下还是在心中暗自决定了下一代的敝站将会由 Astro 驱动，并为此持续关注着社区当中的新主题。

在下最早关注的主题是 fuwari，基于 MD3 风格的设计一下子抓住了在下的眼睛。不过 fuwari 依旧缺乏一些基本的博客功能，例如文章目录（现在已经支持）、评论模块和友链页面，虽然可以自己手搓，不过对于在下来说还是有些费时费力，仅仅只是将其拉到了本地略微研究了一番，便就此作罢。

随着时间的推移，更多有趣的主题开始涌现，其中基于 Hexo 主题 Shoka 设计的 koharu 吸引了在下的注意。Hexo 的 Shoka 本就是在下比较喜欢的主题，但在下同时也注意到更多基于 fuwari 修改的主题开始出现，例如 Twilight、Mizuki 等，都是在下比较中意的。最终，在下在左挑右拣中选定了 MD3 设计的 Mizuki。

迁移备忘#

比起上次从 WordPress 迁移出来，这次的迁移就要方便的多了。首先，由于文章都是以 MD 文档的形式储存，只需要简单的复制粘贴，改一下 Frontmatter，就可以直接用了，唯一需要注意的是 Volantis 主题的特色功能代码需要适配新主题，不过这充其量只是字符串替换，无论是手动 Ctrl + F 之后批量替换还是直接让 AI 修改都不算费事。

而在上次迁移花费最多精力的评论方面，由于之前使用的是 twikoo 评论系统，只需要引入前端 JS 并连接到之前的数据库，就可以像模块一样方便地在不同的博客之中插拔。

值得一提的是，Mizuki 给 twikoo 写的样式还是基于 1.7.6 的，而在在下部署博客的时候，发现其对当时 twikoo 最新的 1.7.13 的适配有问题，为此拷打了一番 AI，提交了 PR 把这个问题给解决了。

最终，在迁移过程中最花时间的项目落到了对主题的微调上，由于这是在下首次接触到 Astro 项目，花了一点时间才搞明白文件结构，特此把一些重要的修改项目列出来备忘。

字体#

Mizuki 之前的字体配置在 src/config/siteConfig.ts 中调整，不过后来由于一些问题，转而直接使用 Astro 原生的字体 API 配置，需要到 astro.config.mjs 中修改。

Astro 的字体 API 可以非常方便地引用敝站使用的谷歌字体：

1
export default defineConfig({
2
  fonts: [
3
      {
4
        provider: fontProviders.google(),
5
        name: "Noto Sans",
6
        cssVariable: "--font-body",
7
        weights: [400, 600],
8
      },
9
    {
10
        provider: fontProviders.google(),
11
        name: "Noto Sans SC",
12
        cssVariable: "--font-cjk",
13
        weights: [400, 600],
14
      },
15
    {
16
          provider: fontProviders.google(),
17
          name: "Lobster",
18
          cssVariable: "--font-lobster",
19
      },
20
  ]
21
});

需要注意的是 Mizuki 必须要有 --font-body 和 --font-cjk 这两个 CSS 变量，修改的时候要确保这两个变量被正确配置，不然会报错。

在 astro.config.mjs 中引入之后，就可以在 src/styles/main.css 中进一步自定义了，例如敝站：

1
@theme {
2
  --font-sans: var(--font-body), var(--font-cjk), ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
3
  --font-display: var(--font-lobster), var(--font-body), ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
4
  --font-title: var(--font-rampart-one), var(--font-body), ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
5
}

如果在 astro.config.mjs 定义了新的字体变量，不要忘记在 src/layouts/Layout.astro 中引入，否则不会有效果，例如敝站引入了 --font-lobster ：

1
<!doctype html>
2
<html
3
  lang={siteLang}
4
  class="bg-(--page-bg) text-[14px] md:text-[16px]"
5
  data-overlayscrollbars-initialize
6
  data-waves-config-enabled={siteConfig.banner?.waves?.enable ? "true" : "false"}
7
  data-banner-title-config-enabled={siteConfig.banner?.homeText?.enable ? "true" : "false"}
8
  data-post-list-layout-enabled={siteConfig.postListLayout?.enable ? "true" : "false"}
9
>
10
  <head>
11
    <meta charset="UTF-8" />
12
    <Font cssVariable="--font-body" preload />
13
    <Font cssVariable="--font-cjk" />
14
    <Font cssVariable="--font-jetbrains-mono" />
15
    <Font cssVariable="--font-lobster" />
16
    <Font cssVariable="--font-rampart-one" />
17

18
...

顶栏菜单#

Mizuki 使用 Tailwind CSS，只需找到位置，调整起来还是很方便的。

调小元素之间的间距：在 src/components/organisms/navigation/DropdownMenu.astro 的第 44 行及 106 行处分别调小 lg:px-5 的值
防止左侧 LOGO 被挤压后整体下移：在 src/components/organisms/navigation/Navbar.astro 的第 103 行处删除 shrink-0
二级菜单取消右侧保留空白：在 src/components/organisms/navigation/DropdownMenu.astro 的第 153 行处把 min-w-[12rem] 改为 min-w-max

永久链接#

Mizuki 的文章链接默认存在 src/contest/posts 下，使用默认的文件名作链接，默认链接路径为 /posts/文件名/ ，如果不想要前面的 /posts/ ，则需要开启 src/config/permalinkConfig.ts 中的 PermalinkConfig 功能。不过，即便开启永久链接之后，旧有的带 /posts/ 的链接依旧能访问到文章。

这里一些值得注意的问题，一是使用永久链接访问的文章，底部的上下文按钮依旧会导航到带 /posts/ 的链接；二是最底部的主题相关文章和随机文章模块不显示，排查后发现，主要原因出在组件内部的硬编码以及永久链接的路由组件缺失。

首先来到 src/utils/content-utils.ts，让模块和上下文按钮在生成数据时，就携带计算好的文章路径，先将第 45 行 getSortedPosts 处改为：

1
export async function getSortedPosts() {
2
  const sorted = await getRawSortedPosts();
3

4
  for (let i = 1; i < sorted.length; i++) {
5
    sorted[i].data.nextSlug = getPostUrl(sorted[i - 1]);
6
    sorted[i].data.nextTitle = sorted[i - 1].data.title;
7
  }
8
  for (let i = 0; i < sorted.length - 1; i++) {
9
    sorted[i].data.prevSlug = getPostUrl(sorted[i + 1]);
10
    sorted[i].data.prevTitle = sorted[i + 1].data.title;
11
  }
12

13
  return sorted;
14
}

再将第 382 行处开始的两个循环改为：

1
  for (const s of withTagMatch) {
2
    if (result.length >= maxCount) break;
3
    result.push({
4
        id: s.post.id,
5
        data: s.post.data,
6
        url: getPostUrl(s.post)
7
    });
8
  }
9

10
  for (const s of withoutTagMatch) {
11
    if (result.length >= maxCount) break;
12
      result.push({
13
      id: s.post.id,
14
      data: s.post.data,
15
      url: getPostUrl(s.post)
16
    });
17
  }

搞定了数据部分，再修改组件逻辑，使其能够读取传入的永久链接。先是上下文按钮的，来到 src/components/PostNavigation.astro 第 33 行处，将 <a> 标签作如下修改，这个链接对应「上一页」：

1
      <a
2
        href={prevSlug.startsWith('/') || prevSlug.startsWith('http') ? prevSlug : getPostUrlBySlug(prevSlug)}
3
        class="w-full font-bold overflow-hidden active:scale-95"
4
      >

第 52 行处的 <a> 标签也是同理，这个链接对应「下一页」：

1
      <a
2
        href={nextSlug.startsWith('/') || nextSlug.startsWith('http') ? nextSlug : getPostUrlBySlug(nextSlug)}
3
        class="w-full font-bold overflow-hidden active:scale-95"
4
      >

这样上下文按钮就改好了，接下来是相关文章和随机文章模块中携带的路径，来到 src/components/widget/PostListItem.astro 的第 34 行处，将 <a> 标签作如下修改：

1
<a
2
  href={post.url || getPostUrl(post as any)}
3
  class="group flex items-center gap-3 px-3 py-3 -mx-1 rounded-lg transition-all hover:bg-black/5 dark:hover:bg-white/5 active:scale-[0.98]"
4
>

最后，补全永久链接的页面路由中的相关文章和随机文章模块，来到 src/pages/[…permalink].astro，找到：

1
import {
2
  LastModified,
3
  PostMeta,
4
  PostNavigation,
5
} from "@components/features/posts";

部分，在 PostNavigation, 后面补上 RandomPosts, 和 RelatedPosts,，接着找到：

1
import { getSortedPosts } from "@utils/content-utils";

把 getSortedPosts 这个变量加到 getSortedPosts 后面，再找到 import { licenseConfig } from "src/config"; ，将其改为：

1
import {
2
  licenseConfig,
3
  randomPostsConfig,
4
  relatedPostsConfig,
5
 } from "src/config";

随后在 Frontmatter 结束前（--- 前）补充：

1
const relatedPosts = relatedPostsConfig.enable
2
  ? await getRelatedPosts(entry, relatedPostsConfig.maxCount)
3
  : [];

最后，在最后（</MainGridLayout> 前）补上：

1
  {
2
    (relatedPostsConfig.enable || randomPostsConfig.enable) && (
3
      <div class="grid grid-cols-1 md:grid-cols-2 gap-4 mb-4">
4
        {relatedPostsConfig.enable && relatedPosts.length > 0 && (
5
          <RelatedPosts relatedPosts={relatedPosts} />
6
        )}
7
        {randomPostsConfig.enable && (
8
          <RandomPosts
9
            excludeIds={[entry.id]}
10
            maxCount={randomPostsConfig.maxCount}
11
          />
12
        )}
13
      </div>
14
    )
15
  }

到这里，问题就算全部解决。不过在下还建议顺便带 /posts/ 的链接加个重定向，来到 src/pages/posts/[…slug].astro，在第 22 行引入 getPostUrl ：

1
import { getFileDirFromPath, removeFileExtension, getPostUrl } from "@utils/url-utils";

再于第 97 行 const { entry } = Astro.props; 后加入判断就好了：

1
if (permalinkConfig.enable) {
2
  const targetUrl = entry.url || getPostUrl(entry);
3

4
  if (targetUrl && !targetUrl.startsWith("/posts/")) {
5
    return Astro.redirect(targetUrl, 301);
6
  }
7
}

另外，出于对 SEO 的考虑，建议修改 src/pages/robots.txt.ts，因为 Mizuki 的默认配置只允许首页和 /posts/ 下的地址被爬取：

1
import type { APIRoute } from "astro";
2

3
const robotsTxt = `
4
User-agent: *
5
Disallow:
6

7
Sitemap: ${new URL("sitemap-index.xml", import.meta.env.SITE).href}
8
`.trim();
9

10
/* 至少也要保证站点地图能被正常爬取
11
Disallow: /
12
Allow: /$
13
Allow: /posts/
14
Allow: /sitemap-index.xml
15
Allow: /sitemap-0.xml
16
Allow: /sitemap-1.xml（如果有）*/
17

18
export const GET: APIRoute = () => {
19
  return new Response(robotsTxt, {
20
    headers: {
21
      "Content-Type": "text/plain; charset=utf-8",
22
    },
23
  });
24
};

更新 Twikoo 前端#

Mizuki 自带的源在 /assets/js/twikoo.all.min.js，可以选择下载最新版本将其替换，后端不使用腾讯云云函数的只需要 twikoo.min.js 即可。

也可以直接引用官方 CDN：https://unpkg.com/twikoo/dist/twikoo.min.js，需要在 src/components/comment/Twikoo.astro 中替换 TWIKOO_SCRIPT_URL。

鼠标指针#

也算是敝站为数不多的自 WordPress 时代以来一直传承下来的特性。直接在 src/layouts/Layout.astro 添加：

1
<style>
2
  /* 1. 默认状态 */
3
  html, body {
4
    cursor: url('https://PATH_TO_YOUR_DOMAIN/normal.cur'), auto;
5
  }
6

7
  /* 2. 悬停与点击状态 */
8
  a, button, [role="button"], summary, select, option {
9
    cursor: url('https://PATH_TO_YOUR_DOMAIN/selecting.cur'), pointer;
10
  }
11
  a:active, button:active {
12
    cursor: url('https://PATH_TO_YOUR_DOMAIN/selected.cur'), pointer;
13
  }
14

15
  /* 3. 文本输入与选择状态 */
16
  input[type="text"], input[type="search"], textarea, [contenteditable="true"] {
17
    cursor: url('https://PATH_TO_YOUR_DOMAIN/text.cur') 16 16, text;
18
  }
19

20
  /* 4. 等待/后台加载状态 */
21
  .is-loading, .loading-state {
22
    cursor: url('https://PATH_TO_YOUR_DOMAIN/waiting.cur'), wait;
23
  }
24
</style>

适配动态页#

敝站的动态页基于 Mastodon embed timeline widget 制作，用于展示自己在 Mastondon 发表的内容，本质上是直接引用 JS。不过需要注意的是，Astro 需要把 JS 内容单独拿出来，用 script is:inline 放到 UI 孤岛中，否则将不会被加载。

另外，似乎必须完全刷新一次页面才能正确加载出页面内容，因此加入了强制刷新代码：

1
<script>
2
    initMastodon();
3
    document.addEventListener('astro:page-load', initMastodon);
4
</script>

最后是对主题颜色的适配：

1
<style is:global>
2
    .mt-container,.mt-container[data-theme],.mt-dialog,.mt-dialog[data-theme] {
3
        --mt-txt-max-lines: none;
4
        --mt-preview-max-lines: none;
5
        --mt-color-bg: rgba(255, 255, 255, 0);
6
        --mt-color-bg-hover: rgba(233, 238, 241, 0);
7
        --mt-color-line-gray: var(--line-color);
8
        --mt-color-contrast-gray: var(--content-meta);
9
        --mt-color-content-txt: var(--color-neutral-700);
10
        --mt-color-hashtag: var(--primary);
11
        --mt-color-link: var(--btn-content);
12
        --mt-color-error-txt: var(--admonitions-color-caution);
13
        --mt-color-btn-bg: var(--btn-regular-bg);
14
        --mt-color-btn-bg-hover: var(--btn-regular-hover);
15
        --mt-color-btn-txt: var(--btn-content);
16
        --mt-color-backdrop: #00000090;
17
        --mt-color-placeholder: #60698425
18
    }
19
    .dark .mt-container,.dark .mt-container[data-theme],.dark .mt-dialog,.dark .mt-dialog[data-theme] {
20
        --mt-color-bg: rgba(255, 255, 255, 0);
21
        --mt-color-bg-hover: rgba(233, 238, 241, 0);
22
        --mt-color-content-txt: var(--color-neutral-300);
23
        --mt-color-backdrop: #00000090;
24
        --mt-color-placeholder: #60698425
25
    }
26
</style>

迁移小结#

这次的迁移，在下大约花了一个周末的时间完成。除了上述必要的一些适配之外，在下还删掉了一部分文章封面，虽然封面确实能提高页面美观程度，但是给每一篇文章都加上封面反而让网站显得过于花哨，删掉一部分与文章相关不大的封面之后，看起来有了呼吸的空间，错落交致之间反而提升了整体的美观度；另一方面，也能变相加快网页的加载速度。

对于既往文章的修订当然也是必不可少的，不过对于这些琐碎的部分，就不再一一赘述。此外，由于架构迁移，旧有的一些功能，例如剧集页无法继续提供，不过有动态页的 NeoDB 消息补足，可以等之后再慢慢打磨上线。

在迁移的过程中，在下总是能迸发出最初搭建博客时的，发自内心的快乐，在电脑前一坐就是好几个小时，心无旁骛，无视外界的打扰，把食欲和困意也暂时放在一边，脑子里只考虑自己想要考虑的东西，进入全神贯注的心流状态。哪怕是结束之后只想瘫在床上被睡意裹挟，那种带给在下的充实感与满足感，也依然会从骨子里蔓延开来，告诉在下：博客在迁移，时代在变，但那份对折腾发自内心的热爱与专注，从未改变。

こんにちは、Astro

https://champhoon.xyz/log/hello-astro/

作者

澄沨

发布于

2026-07-25

许可协议

CC BY-NC-SA 4.0

岁暮杂记

ChaM&log.

迁移背景#

迁移备忘#

字体#

顶栏菜单#

永久链接#

更新 Twikoo 前端#

鼠标指针#

适配动态页#

迁移小结#

目录