Fishのblog

1. 安装 Node.js#

前往 Node.js 官网 下载 LTS 版本并安装。

2. 安装 pnpm#

1
npm install -g pnpm

踩坑提醒：如果之前通过 Scoop 等包管理器安装了 pnpm，升级后可能出现路径冲突。建议统一使用 npm install -g pnpm 安装。

3. 克隆 Twilight 模板#

1
git clone https://github.com/Spr-Aachen/Twilight.git
2
cd Twilight
3
pnpm install

4. 启动开发服务器#

1
pnpm dev

访问 http://localhost:4321 即可预览。

Front Matter 格式转换#

Hexo 和 Twilight 的 Front Matter 格式有所不同：

Hexo 格式：

1
---
2
title: 文章标题
3
date: 2026-01-15 10:30:00
4
tags:
5
  - 标签1
6
  - 标签2
7
categories:
8
  - 分类名
9
---

Twilight 格式：

1
---
2
title: 文章标题
3
published: 2026-01-15 10:30
4
tags:
5
  - 标签1
6
  - 标签2
7
category: 分类名
8
description: 文章描述
9
---

主要变化：

• date → published
• categories（数组）→ category（字符串）
• 新增 description 字段

迁移步骤#

1. 将 Hexo 的 source/_posts/ 下的 .md 文件复制到 Twilight 的 src/content/posts/
2. 批量修改 Front Matter 格式
3. 检查图片路径，确保图片正确引用

迁移关于页面和友链页面#

Twilight 的 about.md 和 friends.md 放在 src/content/ 目录下。

踩坑：Frontmatter 必须存在

即使是空的 Frontmatter，也必须用 --- 包裹，否则 Astro 的 YAML 解析器会把正文内容当作 YAML 解析，导致构建失败：

1
[ERROR] end of the stream or a document separator is expected

正确写法（空 Frontmatter）：

1
---
2
---
3

4
正文内容...

迁移友链数据#

Hexo 的友链通常在 link.yml 中，Twilight 使用 JSON 文件：

Hexo 格式（link.yml）：

1
- class_name: 友链
2
  flink_style: flexcard
3
  link_list:
4
    - name: Linuxdo
5
      link: https://linux.do/
6
      avatar: https://linux.do/logo-128.svg
7
      descr: 没有Linux

Twilight 格式（src/content/friends/linuxdo.json）：

1
{
2
    "title": "Linuxdo",
3
    "imgurl": "https://linux.do/logo-128.svg",
4
    "desc": "没有Linux",
5
    "siteurl": "https://linux.do/",
6
    "tags": ["社区"]
7
}

每个友链一个 JSON 文件，放在 src/content/friends/ 目录下。记得删除默认的示例友链文件。

基本信息#

1
site:
2
    siteURL: "https://your-username.github.io/blog/"
3
    title: "博客标题"
4
    subtitle: "博客副标题"
5
    lang: "zh-CN"
6

7
profile:
8
    avatar: "/assets/images/avatar.png"
9
    name: "你的名字"
10
    bio: "个人简介"

字体配置#

默认字体对中文覆盖不全，会导致部分字符 fallback 到系统字体，看起来不统一。推荐使用霞鹜文楷——中文博客圈超人气的开源字体：

1
site:
2
    font:
3
        "LXGW-WenKai":
4
            src: "https://cdn.jsdelivr.net/npm/lxgw-wenkai-webfont@1.7.0/style.css"
5
            family: "LXGW WenKai"

霞鹜文楷完整覆盖简体中文 + 繁体中文 + 日文，是手写楷体风格，温暖文艺，非常适合个人博客。通过 jsDelivr CDN 加载，国内访问速度也不错。

壁纸配置#

1
site:
2
    wallpaper:
3
        mode: "banner"  # banner | fullscreen | none
4
        src:
5
            desktop:
6
                - "/assets/images/wallpaper.png"
7
            mobile:
8
                - "/assets/images/wallpaper.png"
9
        carousel:
10
            enable: true
11
            interval: 3.6

踩坑：中文文件名

静态资源文件名请使用英文，避免中文或特殊字符。中文文件名在构建/部署时可能导致路径编码问题。例如把”卡通插画-可爱小狗.png”重命名为 cute-dogs-camping.png。

音乐播放器#

1
musicPlayer:
2
    enable: true
3
    mode: "local"  # local | meting
4
    local:
5
        playlist:
6
            - id: 1
7
              title: "歌曲名"
8
              artist: "歌手"
9
              url: "/blog/assets/music/song.flac"
10
              duration: 228
11
    autoplay: true

踩坑：音乐路径需要 base 前缀

如果部署在子目录（如 /blog/），音乐文件的 url 需要加上 base 路径前缀。例如文件放在 public/assets/music/song.flac，配置中应写 /blog/assets/music/song.flac。

踩坑：FLAC 格式

如果使用 FLAC 格式的音乐文件，git 默认可能不识别为二进制文件。建议在 .gitattributes 中添加：

1
*.flac binary

公告栏链接#

1
announcement:
2
    link:
3
        enable: true
4
        text: "Learn More"
5
        url: "/blog/about/"

踩坑：子目录部署时 URL 要加 base

url 要写完整路径 /blog/about/ 而不是 /about/，否则会跳到错误的页面。

Umami 统计#

1
umami:
2
    enabled: false  # 需要正确配置才能启用
3
    baseUrl: "https://api.umami.is"
4
    apiKey: ""
5
    scripts: ""

踩坑：Umami 未配置就启用会导致浏览量异常

如果启用了 Umami 但 apiKey 和 scripts 为空，可能出现浏览量每次刷新 +10 的异常情况。如果还没配置好 Umami，请先设为 enabled: false。

1. 创建 GitHub 仓库#

在 GitHub 创建一个新仓库，例如 blog。

2. 配置 base 路径#

由于部署在子目录 /blog/，需要修改 astro.config.mjs：

1
export default defineConfig({
2
    site: 'https://your-username.github.io',
3
    base: '/blog/',
4
    // ...
5
});

同时更新 twilight.config.yaml 中的 siteURL 和音乐路径等。

3. 推送代码#

1
git init
2
git remote add origin https://github.com/your-username/blog.git
3
git add .
4
git commit -m "Initial commit"
5
git push -u origin main

4. 启用 GitHub Pages#

1. 进入仓库 Settings → Pages
2. Source 选择 “GitHub Actions”
3. 等待 Actions 构建完成
4. 访问 https://your-username.github.io/blog/

踩坑：首次访问 404

如果构建成功但访问 404，检查：

1. Pages 的 Source 是否选的是 “GitHub Actions”（不是 “Deploy from a branch”）
2. astro.config.mjs 中的 base 和 twilight.config.yaml 中的 siteURL 是否一致
3. 等待几分钟，GitHub Pages 生效需要一点时间

1. 调整页面宽度#

文件：src/constants/constants.ts

1
// 默认 90rem，觉得太窄可以改大
2
export const PAGE_WIDTH = 100;

2. 音乐播放器 - 页面可见性暂停#

切换标签页或最小化窗口时自动暂停，回来后恢复播放。

文件：src/components/musicPlayer.svelte

添加状态变量（在 let showError = $state(false); 后）：

1
let wasPlayingBeforeHidden = false;

添加处理函数（在 STORAGE_KEYS 常量后）：

1
function handleVisibilityChange() {
2
    if (typeof document === 'undefined' || !audio) return;
3
    if (document.hidden) {
4
        wasPlayingBeforeHidden = isPlaying;
5
        if (isPlaying) { audio.pause(); }
6
    } else {
7
        if (wasPlayingBeforeHidden && !isPlaying) {
8
            audio.play().catch(() => {});
9
        }
10
    }
11
}

注册/注销事件监听：

• onMount 中 handleAudioEvents(); 后添加：document.addEventListener('visibilitychange', handleVisibilityChange);
• onDestroy 中添加：document.removeEventListener('visibilitychange', handleVisibilityChange);

3. 今日诗词（每日诗句）#

类似 Hexo 的今日诗词插件，在 Banner 副标题中轮播显示来自今日诗词 API 的随机诗句。

文件 1：src/components/common/typewriterText.astro

• Props 新增 jinrishici?: boolean
• span 元素新增 data-jinrishici 属性
• TypewriterEffect 构造函数中检测该属性，异步 fetch https://v2.jinrishici.com/one.json
• 将获取到的诗句添加到打字文本列表中轮播显示
• 即使 API 请求失败也不影响原有功能

文件 2：src/components/banner.astro

1
<TypewriterText
2
    text={config.banner.homeText.subtitle}
3
    speed={config.banner.homeText.typewriter.speed}
4
    deleteSpeed={config.banner.homeText.typewriter.deleteSpeed}
5
    pauseTime={config.banner.homeText.typewriter.pauseTime}
6
    jinrishici={true}
7
/>

4. 子目录部署路径修复（重要！）#

Twilight 模板部分组件硬编码了根路径 /，在 /blog/ 等子目录部署时会导致资源 404。需要逐一修复为 import.meta.env.BASE_URL。

核心原则：凡是硬编码的 /xxx/... 路径（指向 public 目录的静态资源），都需要替换为 `${import.meta.env.BASE_URL}xxx/...` 格式。在 dev server 日志中看到的 [ERROR] [router] Request URLs for public/ assets must also include your base 错误就是这个问题。

插件配置#

在 Typora 插件配置文件 custom_plugin.user.toml 中添加：

1
[twilightFrontMatter]
2
name = "插入 Twilight Front Matter"
3
enable = true
4
hide = false
5
order = 2
6
hotkey = "ctrl+alt+t"
7
template = "---\ntitle: \npublished: {{datetime}}\ntags:\n  - \ncategory: \ndescription: \n---"

插件代码#

创建 twilightFrontMatter.js：

1
class TwilightFrontMatter extends BaseCustomPlugin {
2
    hint = () => "在文件开头插入 Twilight Front Matter 模板"
3
    hotkey = () => [this.config.hotkey]
4
    callback = async anchorNode => {
5
        // 检测是否已有 Front Matter
6
        // 生成模板并插入
7
        // 定位光标到 title 后
8
    }
9
}
10
module.exports = { plugin: TwilightFrontMatter }

使用快捷键 Ctrl+Alt+T 即可快速插入模板。

需要备份的内容#

源码修改备忘#

升级模板后需要重新应用的修改（详见 CUSTOM_CHANGES.md）：

1. astro.config.mjs → base: "/blog/"
2. src/constants/constants.ts → PAGE_WIDTH = 100
3. src/components/musicPlayer.svelte → 页面可见性暂停 + 默认封面路径
4. src/components/common/typewriterText.astro + banner.astro → 今日诗词
5. 子目录部署路径修复（base.astro、pio.svelte、particle.ts）

一键备份脚本#

创建 backup.bat：

1
@echo off
2
chcp 65001 >nul
3
set BACKUP_DIR=..\Twilight-backup
4

5
echo 正在备份到 %BACKUP_DIR% ...
6
if not exist "%BACKUP_DIR%" mkdir "%BACKUP_DIR%"
7

8
:: 备份配置文件
9
copy /Y "twilight.config.yaml" "%BACKUP_DIR%\"
10
copy /Y "astro.config.mjs" "%BACKUP_DIR%\"
11

12
:: 备份内容和静态资源
13
xcopy /E /I /Y "public" "%BACKUP_DIR%\public"
14
xcopy /E /I /Y "src\content" "%BACKUP_DIR%\src\content"
15

16
echo 备份完成！
17
pause

构建相关#

部署相关#

功能相关#