Twilight (Astro) 主题深度定制与 Bug 修复指南

本文档记录了对基于 Astro 框架的 Twilight 博客主题进行的一系列深度定制操作，包括功能拓展、UI 优化以及底层时区 Bug 的彻底修复。

1. 开启 Twikoo 评论系统

目标： 在文章底部显示 Twikoo 评论区。 修改文件： twilight.config.yaml（根目录）

操作步骤： 找到 comment 配置块，将 enable 设置为 true，并填入自己的 Twikoo 环境地址。

1
# 评论配置
2
comment:
3
  # 启用评论功能
4
  enable: true
5
  # Twikoo 评论系统配置
6
  twikoo:
7
    # 环境ID
8
    envId: "[https://你的twikoo环境地址.vercel.app](https://你的twikoo环境地址.vercel.app)"
9
    lang: "zh-CN"

2. 侧边栏个人资料 (Profile) 定制

目标： 将默认的方形头像改为纯圆形，并精简底部统计信息（仅保留访问量，去除访客数）。 修改文件： src/components/widget/Profile.astro（或对应侧栏文件）

2.1 头像改为圆形

找到包含头像 <ImageWrapper> 的 <a> 标签，修改其 Tailwind 类名：将 rounded-xl 改为 **rounded-full**。

1
<a aria-label="Go to About Page" href={url('/about/')}
2
   class="group block relative mx-auto mt-1 lg:mx-0 lg:mt-0 mb-3
3
   max-w-48 lg:max-w-none overflow-hidden rounded-full active:scale-95">

2.2 精简站点统计信息

在文件底部的 <script> 标签内，找到 generateStatsText 函数，修改返回值。

1
// 修改前：返回 views 和 visitors
2
// function generateStatsText(pageViews, visitors, i18n_views, i18n_visitors) {
3
//     return `${i18n_views} ${pageViews} · ${i18n_visitors} ${visitors}`;
4
// }
5

6
// 修改后：仅返回 views
7
function generateStatsText(pageViews, visitors, i18n_views, i18n_visitors) {
8
    return `${i18n_views} ${pageViews}`;
9
}

3. 彻底修复“最后编辑 8 小时时差”Bug

背景： 由于 Markdown 文件时间缺乏时区标识，Astro 默认将其转为 UTC（零时区）时间。浏览器读取时产生 8 小时偏差，导致“距离上次编辑”凭空多出 8 小时。 修改文件： src/pages/posts/[...slug].astro

解决方案（釜底抽薪法）： 在后端生成数据时，使用 .toISOString() 强制输出带 Z（标准时区标记）的字符串，让浏览器原生处理本地时区，无需在前端“打补丁”减去时间。

3.1 修改时间解析逻辑 (约第 38 行)

1
// 修改前：会丢失时区信息
2
// const lastModified = dayjs(entry.data.updated || entry.data.published)
3
//     .utc()
4
//     .format("YYYY-MM-DDTHH:mm:ss");
5

6
// 修改后：输出标准 ISO 字符串
7
dayjs.extend(utc);
8
const lastModified = dayjs(entry.data.updated || entry.data.published).toISOString();

3.2 还原底部倒计时脚本 (文件最底部的 `<script>`)

由于源头时区已正确，客户端直接相减即可，无需修改为 let 或手动减去毫秒数。

1
function runtime() {
2
    const lastModifiedElement = document.getElementById('last-modified');
3
    if (!lastModifiedElement) return;
4

5
    const startDate = new Date(lastModifiedElement.dataset.lastModified);
6
    const currentDate = new Date();
7

8
    // 直接相减，浏览器会自动对齐时区
9
    const diff = currentDate - startDate;
10
    const validDiff = diff < 0 ? 0 : diff; // 保底机制
11

12
    const seconds = Math.floor(validDiff / 1000);
13
    // ...后续计算逻辑保持不变
14
}

4. 版权卡片 (License) 融入“最后编辑时间”

目标： 在文章底部的版权协议卡片中，新增一列显示具体的“最后编辑”日期和时间。

4.1 传递数据给组件

修改文件： src/pages/posts/[...slug].astro 找到 <License /> 组件的调用位置（约 66 行），新增传入 upDate 属性。

1
{
2
    postConfig.license.enable && (
3
        <License
4
            title={entry.data.title}
5
            id={entry.id}
6
            pubDate={entry.data.published}
7
            upDate={entry.data.updated}
8
            author={entry.data.author}
9
            sourceLink={entry.data.sourceLink}
10
            // ...其他属性保持不变
11
        />
12
    )
13
}

4.2 渲染卡片 UI

修改文件： src/components/post/license.astro

第一步：接收变量 (文件顶部)

1
---
2
interface Props {
3
    title: string;
4
    id: string;
5
    pubDate: Date;
6
    upDate?: Date;    // 新增类型声明
7
    // ...其他声明
8
}
9

10
// 在解构赋值中加入 upDate
11
const { title, id, pubDate, upDate, author, sourceLink, licenseName, licenseUrl, postUrl: propPostUrl } = Astro.props;
12
---

第二步：修改 HTML 结构 加入 flex-wrap 优化移动端排版，并新增区块渲染 upDate（若无则退化显示 pubDate）。

1
<div class="flex flex-wrap gap-6 mt-2">
2
    <div>
3
        <div class="transition text-black/30 dark:text-white/30 text-sm">{i18n(I18nKey.author)}</div>
4
        <div class="transition text-black/75 dark:text-white/75 line-clamp-2">{author || profileConf.name}</div>
5
    </div>
6
    <div>
7
        <div class="transition text-black/30 dark:text-white/30 text-sm">{i18n(I18nKey.publishedAt)}</div>
8
        <div class="transition text-black/75 dark:text-white/75 line-clamp-2">{formatDateToYYYYMMDD(pubDate)}</div>
9
    </div>
10

11
    <div>
12
        <div class="transition text-black/30 dark:text-white/30 text-sm">最后编辑</div>
13
        <div class="transition text-black/75 dark:text-white/75 line-clamp-2">
14
            {formatDateToYYYYMMDD(upDate || pubDate)}
15
        </div>
16
    </div>
17

18
    <div>
19
        <div class="transition text-black/30 dark:text-white/30 text-sm">{i18n(I18nKey.license)}</div>
20
        <a href={licenseName ? (licenseUrl || undefined) : licenseConf.url} target="_blank" class="link text-(--primary) line-clamp-2">{licenseName || licenseConf.name}</a>
21
    </div>
22
</div>

Ezorin