小哇牛博客

deepseek-v4.1-flash论文阅读笔记

Wed, 28 Oct 2026 10:43:11 GMT

本文展示如何设置文章关键词。

frontmatter 关键词设置

在文章的 frontmatter 中添加 keywords 字段即可设置关键词：

---
title: 我的文章
date: 2026-01-01
keywords:
  - 示例关键词一
  - 示例关键词二
---

这是篇带有关键词的文章。

然后生成的页面会包含以下 meta 标签：

<meta name="keywords" content="示例关键词一, 示例关键词二, ... site.keywords">

摘要

随着长周期智能体（Long-horizon Agents）的广泛应用，模型工作负载正变得越来越依赖输入处理。尽管此前的研究已经大幅降低了长上下文计算的成本，但 Prefill（预填充）阶段仍然具有较高的计算开销，而庞大的 KV Cache（键值缓存）则持续给 HBM（高带宽内存）和 SSD 的存储容量及数据传输带宽带来巨大压力。计算、存储和带宽方面的综合需求，已成为进一步降低模型部署成本的主要瓶颈。为解决这一挑战，我们推出了 DeepSeek-V4.1-Flash，这是一款多模态混合专家模型（Mixture-of-Experts，MoE），拥有 5520 亿（552B）骨干网络参数，支持最长 100 万 Token 的上下文窗口。通过采用因果编码器—解码器（Causal Encoder-Decoder，CED）架构，该模型在 Decode（解码）阶段每个 Token 激活 160 亿（16B）参数，而在 Prefill（预填充）阶段每个 Token 仅激活 80 亿（8B）参数，从而显著提升了面向智能体工作负载的成本效率。为了进一步突破 KV Cache 压缩的极限，DeepSeek-V4.1-Flash 将压缩稀疏注意力机制 2（Compressed Sparse Attention 2，CSA2）中的跨层 KV Cache 复用技术与 FP4 KV Cache 相结合。这些设计将其全局 KV Cache 占用量（始终存储在 HBM 中）降低至每个 Token 890 字节，约为 DeepSeek-V4-Flash 对应占用量的四分之一。此外，通过一项专门的部署优化技术——SWA Bounded Replay（滑动窗口注意力有界重放），DeepSeek-V4.1-Flash 将其持久化 KV Cache 的占用量（始终存储在 SSD 或主机内存中）降低至 DeepSeek-V4-Flash 的约八分之一。尽管 KV Cache 占用量大幅减少，该模型的性能仍然显著优于基线模型。此外，我们对 DeepSeek-V4 架构进行了精简，并引入了多项高效的架构扩展。在预训练阶段，DeepSeek-V4.1-Flash 使用了包含 45 万亿（45T）Token 的多模态语料库。随后，我们开展了全面的后训练，使模型在多种基于文本和多模态的智能体应用场景中均表现出色。模型文件（Model Checkpoints）现已开放获取：https://huggingface.co/deepseek-ai/DeepSeek-V4.1-Flash.

The widespread adoption of long-horizon agents has made model workloads increasingly inputheavy. Although prior work has substantially reduced the cost of long-context computation, prefill remains computationally expensive, and large KV caches continue to strain HBM and SSD capacity and data-transfer bandwidth. Together, these compute, storage, and bandwidth demands constitute the primary bottleneck to further lowering deployment costs. To address this challenge, we introduce DeepSeek-V4.1-Flash, a multimodal Mixture-of-Experts (MoE) model with 552B backbone parameters and support for contexts of up to one million tokens. With its Causal Encoder-Decoder (CED) architecture, the model activates 16B parameters per token during decode but only 8B parameters during prefill, substantially improving cost efficiency for agentic workloads. To push the limits of KV cache compression, DeepSeek-V4.1- Flash combines cross-layer KV cache reuse in Compressed Sparse Attention 2 (CSA2) with FP4 KV caching. These designs reduce its global KV cache footprint (always in HBM) to 890 bytes per token, roughly 1/4 of the corresponding footprint of DeepSeek-V4-Flash. Further, through a dedicated deployment optimization known as SWA Bounded Replay, DeepSeek-V4.1-Flash reduces its persistent KV cache footprint (always on SSD or in host memory) to roughly 1/8 of that of DeepSeek-V4-Flash. Despite its much smaller KV cache footprint, the model delivers substantially better performance than the baseline. In addition, we streamline the DeepSeek-V4 architecture and introduce several efficient architectural extensions. We pretrain DeepSeek-V4.1- Flash on a multimodal corpus comprising 45T tokens and conduct comprehensive post-training, yielding strong performance across diverse text-based and multimodal agentic scenarios. Model checkpoints are available at https://huggingface.co/deepseek-ai/DeepSeek-V4.1-Flash.

Introduction

Applications of long-horizon agents have expanded rapidly in recent years, making ultra-longcontext processing an increasingly important model workload. Supporting such workloads requires not only efficient long-sequence processing, but also the persistent storage, reuse, and transfer of large KV caches. KV cache management has therefore become a foundational capability for model deployment, while introducing substantial challenges across computation, storage, and communication. Prior advances in sparse attention (DeepSeek-AI, 2025, 2026b) have significantly reduced the computational cost of long-sequence processing, making persistent storage and data movement increasingly prominent bottlenecks.

Specifically, DeepSeek-V4 (DeepSeek-AI, 2026b) combines a global attention branch spanning the full context with local Sliding-Window Attention (SWA). The global branch maintains global KV, comprising main KV and indexer K, while SWA maintains local KV states. For a fixed window size, SWA KV storage is bounded independently of sequence length. For sufficiently long sequences, global KV therefore dominates the runtime KV footprint, which is constrained by HBM capacity. In addition, certain KV are persisted for prefix reuse, referred to as persistent KV caches, which are constrained by SSD and host memory capacity. I/O and interconnect bandwidth also limit cache migration and loading. Together, these constraints limit serving throughput, increase deployment costs, and ultimately hinder the deployment and adoption of agents over longer task horizons and across broader application scenarios.

基于开源的model.py生成的模型结构

Transformer(
  (embed): ParallelEmbedding()
  (layers): ModuleList(
    (0): Block(
      (attn): Attention(
        (wq_a): Linear()
        (q_norm): RMSNorm()
        (wq_b): ColumnParallelLinear()
        (wkv): Linear()
        (kv_norm): RMSNorm()
        (wo_a): ColumnParallelLinear()
        (wo_b): RowParallelLinear()
      )
      (ffn): MoE(
        (gate): Gate()
        (experts): ModuleList(
          (0-7): 8 x Expert(
            (w1): Linear()
            (w2): Linear()
            (w3): Linear()
          )
        )
        (shared_experts): Expert(
          (w1): Linear()
          (w2): Linear()
          (w3): Linear()
        )
      )
      (attn_norm): RMSNorm()
      (ffn_norm): RMSNorm()
    )
    (1): Block(
      (attn): Attention(
        (wq_a): Linear()
        (q_norm): RMSNorm()
        (wq_b): ColumnParallelLinear()
        (wkv): Linear()
        (kv_norm): RMSNorm()
        (wo_a): ColumnParallelLinear()
        (wo_b): RowParallelLinear()
        (compressor): Compressor(
          (norm): RMSNorm()
          (wkv): Linear()
          (wgate): Linear()
        )
        (indexer): Indexer(
          (wq_b): ColumnParallelLinear()
          (weights_proj): ColumnParallelLinear()
          (wk): Linear()
          (k_norm): RMSNorm()
        )
      )
      (ffn): MoE(
        (gate): Gate()
        (experts): ModuleList(
          (0-7): 8 x Expert(
            (w1): Linear()
            (w2): Linear()
            (w3): Linear()
          )
        )
        (shared_experts): Expert(
          (w1): Linear()
          (w2): Linear()
          (w3): Linear()
        )
      )
      (attn_norm): RMSNorm()
      (ffn_norm): RMSNorm()
    )
    (2): Block(
      (attn): Attention(
        (wq_a): Linear()
        (q_norm): RMSNorm()
        (wq_b): ColumnParallelLinear()
        (wkv): Linear()
        (kv_norm): RMSNorm()
        (wo_a): ColumnParallelLinear()
        (wo_b): RowParallelLinear()
      )
      (ffn): MoE(
        (gate): Gate()
        (experts): ModuleList(
          (0-7): 8 x Expert(
            (w1): Linear()
            (w2): Linear()
            (w3): Linear()
          )
        )
        (shared_experts): Expert(
          (w1): Linear()
          (w2): Linear()
          (w3): Linear()
        )
      )
      (attn_norm): RMSNorm()
      (ffn_norm): RMSNorm()
    )
    (3): Block(
      (attn): Attention(
        (wq_a): Linear()
        (q_norm): RMSNorm()
        (wq_b): ColumnParallelLinear()
        (wkv): Linear()
        (kv_norm): RMSNorm()
        (wo_a): ColumnParallelLinear()
        (wo_b): RowParallelLinear()
        (compressor): Compressor(
          (norm): RMSNorm()
          (wkv): Linear()
        )
        (indexer): Indexer(
          (wq_b): ColumnParallelLinear()
          (weights_proj): ColumnParallelLinear()
          (wk): Linear()
          (k_norm): RMSNorm()
        )
      )
      (ffn): MoE(
        (gate): Gate()
        (experts): ModuleList(
          (0-7): 8 x Expert(
            (w1): Linear()
            (w2): Linear()
            (w3): Linear()
          )
        )
        (shared_experts): Expert(
          (w1): Linear()
          (w2): Linear()
          (w3): Linear()
        )
      )
      (attn_norm): RMSNorm()
      (ffn_norm): RMSNorm()
    )
    (4-19): 16 x Block(
      (attn): Attention(
        (wq_a): Linear()
        (q_norm): RMSNorm()
        (wq_b): ColumnParallelLinear()
        (wkv): Linear()
        (kv_norm): RMSNorm()
        (wo_a): ColumnParallelLinear()
        (wo_b): RowParallelLinear()
      )
      (ffn): MoE(
        (gate): Gate()
        (experts): ModuleList(
          (0-7): 8 x Expert(
            (w1): Linear()
            (w2): Linear()
            (w3): Linear()
          )
        )
        (shared_experts): Expert(
          (w1): Linear()
          (w2): Linear()
          (w3): Linear()
        )
      )
      (attn_norm): RMSNorm()
      (ffn_norm): RMSNorm()
    )
  )
  (norm): RMSNorm()
  (head): ParallelHead()
  (mtp): ModuleList(
    (0): DSparkBlock(
      (attn): DSparkAttention(
        (wq_a): Linear()
        (q_norm): RMSNorm()
        (wq_b): ColumnParallelLinear()
        (wkv): Linear()
        (kv_norm): RMSNorm()
        (wo_a): ColumnParallelLinear()
        (wo_b): RowParallelLinear()
      )
      (ffn): MoE(
        (gate): Gate()
        (experts): ModuleList(
          (0-7): 8 x Expert(
            (w1): Linear()
            (w2): Linear()
            (w3): Linear()
          )
        )
        (shared_experts): Expert(
          (w1): Linear()
          (w2): Linear()
          (w3): Linear()
        )
      )
      (attn_norm): RMSNorm()
      (ffn_norm): RMSNorm()
      (main_proj): Linear()
      (main_norm): RMSNorm()
      (norm): RMSNorm()
      (markov_head): DSparkMarkovHead(
        (embed): ParallelEmbedding()
        (head): ParallelHead()
      )
      (confidence_head): DSparkConfidenceHead(
        (proj): Linear()
      )
      (embed): ParallelEmbedding()
      (head): ParallelHead()
    )
  )
)

从 Astro 5 到 Astro 6：astro-koharu 的一次完整迁移实录

Sun, 19 Jul 2026 19:50:03 GMT

这次升级看起来只是把 astro 从 5.16.6 改成 6.x，实际却穿过了内容身份、Markdown 编译、Vite 预渲染、RSS 和第三方 integration 五条链路。更麻烦的是，astro-koharu 不是只有一个模板仓库：每位用户都有自己的文章、永久链接、历史备份和生成资产。模板能构建，不等于用户升级后不会丢 URL，也不等于恢复一份旧备份后仍能构建。

因此，真正困难的不是让 pnpm build 变绿，而是同时证明两件事：升级前后的 URL、多语言 fallback、搜索索引和文章 HTML 没有悄悄改变；一份长期使用的下游仓库也能通过同一套工具安全迁移，而不需要用户逐篇修改 frontmatter。

本文记录的是 astro-koharu 的真实迁移结果。最终版本为 Astro 6.4.8，没有启用 Content Collections legacy 兼容开关，也没有把实验特性留在生产配置中。迁移最终还补上了一条可 dry-run、自动备份且幂等的内容迁移命令，并用 376 篇真实历史文章的完整备份恢复验证了这条路径。

先定义成功，而不是先改版本号

Astro 6 升级指南要求 Node.js 22.12+，并伴随 Zod 4、 Shiki 4 及 Vite 7 构建管线的变化。迁移时 npm 的 astro@latest 已经进入 7.x，因此不能无版本约束地运行升级命令。本次把 Astro 精确锁定在 6.4.8，同时把 Node 边界和 pnpm 版本落到 package.json：

{
  "packageManager": "pnpm@10.28.2",
  "engines": {
    "node": ">=22.12.0"
  },
  "dependencies": {
    "astro": "6.4.8"
  }
}

精确版本不只是为了重现本次构建。Koharu 的新版更新流程也会读取 packageManager，并用声明的 pnpm 精确版本安装依赖，避免更新到新 lockfile 后又意外回落到调用者机器上的旧 pnpm。

迁移前先保存了一组可比较的基线：

指标	Astro 5.16.6 基线
`astro check`	347 个文件，0 error / warning / hint
Astro 静态页面	130
Pagefind 索引页面	134
`dist/` 路由产物	141
Astro 报告的构建耗时	约 21.62 秒

成功标准不只是页面数相等，还包括四类不变式：

默认语言 URL 不带前缀，英文和日文继续使用 /en/、/ja/；
frontmatter 的 link 仍然可以覆盖公开 slug，未翻译页面的 canonical 仍指向默认语言；
GFM、Shiki、KaTeX、Mermaid、Pagefind、RSS、sitemap 和 robots 继续生成。
历史文章迁移前后保留相同公开 URL，旧备份恢复后不会混入新版模板自带的示例内容。

Fonts API、CSP、Live Content Collections、Rust compiler 和 queued rendering 都不在兼容迁移范围内。把新功能与 major upgrade 混在一起，会让故障定位和回滚都变得困难。

依赖升级不是全部追最新

核心依赖最终落在以下版本：

依赖	迁移前	迁移后
`astro`	5.16.6	6.4.8
`@astrojs/react`	4.4.2	5.0.7
`@astrojs/sitemap`	3.7.0	3.7.3
`@astrojs/rss`	4.0.14	4.0.19
`shiki`	3.22.0	4.3.1
`astro-mermaid`	1.2.0	2.1.0
`astro-pagefind`	1.8.5	1.8.6
`astro-loading-indicator`	0.7.1	0.9.0

这里最反直觉的是 astro-pagefind。2.x 的确支持 Astro 6，但它同时把原来的搜索组件改成了 Web Component API。直接升级会迫使现有搜索样式、键盘导航和本地化一起重写。1.8.6 已补上 Astro 6 peer 支持，又保留旧 UI，所以它才是这次兼容迁移的合理目标。

迁移的原则由此变得很明确：优先选择支持新框架且不扩大产品行为变化的最小版本，而不是把所有包机械地升到最新 major。

最核心的变化：Content Layer 身份模型

Astro 5 的旧内容配置位于 src/content/config.ts，业务代码还在读取 post.slug 并调用 post.render()。 Astro Content Collections 文档给出的新模型则要求显式 loader，内容配置移到 src/content.config.ts，Zod 从 astro/zod 导入：

import { defineCollection } from 'astro:content';
import { glob } from 'astro/loaders';
import { z } from 'astro/zod';

const blogCollection = defineCollection({
  loader: glob({
    pattern: '**/[^_]*.{md,mdx}',
    base: './src/content/blog',
  }),
  schema: z.object({
    title: z.string(),
    // Other frontmatter fields...
  }),
});

真正需要保护的是“内部 ID”和“公开 slug”之间的边界：

flowchart LR
  F[Markdown 相对路径] --> I[Content entry ID]
  I --> L[语言识别]
  I --> S[派生公开 slug]
  O[frontmatter link] --> S
  S --> U[公开文章 URL]

例如 en/tools/getting-started.md 的内容 ID 是 en/tools/getting-started，但公开 URL 还要先移除 locale，再考虑 link override 和字符转写。项目里其他 DTO 也有名为 slug 的字段，却表达公开路径；如果全仓替换 slug 为 id，搜索、相似文章和系列导航都会被破坏。

所以迁移只替换 CollectionEntry<'blog'> 的身份读取：

export function getPostLocale(post: BlogPost): string {
  return getSlugLocaleInfo(post.id).locale;
}

export function getPostSlug(post: BlogPost): string {
  return post.data.link ?? transliterateSlug(getSlugLocaleInfo(post.id).localeFreeSlug);
}

路由也不再把整个 entry 当成旧式可渲染对象，而是传递内部 ID，再使用新的顶层 render()：

import { render } from 'astro:content';

return posts.map((post) => ({
  params: { slug: getPostSlug(post) },
  props: { postId: post.id },
}));

const post = await getPostById(postId, locale);
if (!post) throw new Error(`Post not found: ${postId}`);
const { Content } = await render(post);

Astro 6 的 body 类型允许为 undefined，因此摘要和纯文本提取还需要显式兜底：

extractTextFromMarkdown(post.body ?? '', maxLength);

这不是为了掩盖缺失内容，而是因为集合还可能包含没有 Markdown body 的 entry；调用纯文本工具时应把该状态转换成空输入。

为什么旧文章里的 `slug` 不能原样留下

glob() loader 会用文件路径建立稳定的 entry ID，而旧内容里的顶层 slug 又承载过自定义永久链接语义。继续让同一个字段横跨两套身份模型，最危险的结果不是立刻报错，而是文章仍能生成、公开 URL 却变了。

因此，新 schema 只把 link 视为显式的公开 URL override。旧 slug 不能简单删除，因为它可能是用户长期对外分享的地址；也不能继续当成普通 frontmatter 原样保留。正确迁移必须先确定它过去代表的公开 URL，再把这层语义转移到 link。

历史文章不能靠用户手工迁移

模板仓库里的示例文章很整齐，真实用户仓库却可能跨过多个版本：有些文章只有 link，有些还保留 slug，有些从未显式写过永久链接，多语言对应文章也未必在同一时间创建。让用户做一次全局替换，既无法处理这些分支，也无法发现两篇文章即将撞到同一个 URL。

为此，Koharu CLI 增加了专门的迁移入口：

# 只扫描并展示计划，不写文件
pnpm koharu migrate --dry-run

# 确认计划后，自动备份并执行
pnpm koharu migrate

对从旧版 astro-koharu 升级的用户，实际入口仍然是更新前已经存在的旧 CLI。完整顺序是：

# 先由旧 CLI 完成备份、拉取、合并和依赖安装
pnpm koharu update

# 等上面的进程完全退出，再使用更新后的 CLI
pnpm koharu migrate --dry-run
pnpm koharu migrate

这个边界很重要：正在运行的 update 进程加载的仍是升级前的代码，不能假设它已经拥有更新后才出现的 migrate 子命令。等旧进程退出后重新调用 CLI，才能确保执行的是新版迁移逻辑。

迁移策略不是“所有文章都加一个新字段”，而是按已有数据选择最小改动：

文章现状	迁移动作	URL 结果
只有 `link`	不修改	完全保持现状
同时有 `link` 和 `slug`	保留 `link`，移除冗余 `slug`	继续以原 `link` 为准
只有 `slug`	原位把字段名改为 `link`	精确保留旧 permalink
两者都没有	默认语言使用路径；非默认语言优先跟随默认语言链接，缺少默认语言对应文章时才复用其他译文的唯一 `link`，否则使用路径	默认语言 URL 保持不变，译文尽量保持配对
同语言链接重复，或缺少默认语言对应文章且其他译文给出多个候选 `link`	报错并阻止整批写入	不猜测、不产生半套 URL

这里有几个容易忽略的安全细节：

扫描覆盖所有 .md 与 .mdx，不是只处理模板当前使用的目录层级；
修改是针对顶层字段的局部编辑，不重新序列化整份 YAML，避免无意义地重排用户 frontmatter；
任何解析错误、空链接或同语言 URL 冲突都会在写入前让整批迁移停止；
博客内容只接受普通文件，遇到符号链接会直接阻止，避免跟随到内容目录外部；
正式写入前会再次确认全部源文件、站点配置和文件集合与扫描时完全相同，避免用户并行编辑导致计划过期；
单文件通过同目录临时文件和原子 rename 写入，保留原权限；后续写入失败时，已安装的变更会按逆序回滚；
执行前自动创建基础备份；再次运行 dry-run 应得到 0 项变更，幂等性本身也是验收条件。

为了防止用户跳过这一步，pnpm dev 和 pnpm build 现在都会先运行 pnpm koharu migrate --check。这个模式只读扫描，不会自动改文章；发现待迁移项或无法安全处理的 frontmatter 时会以非零状态退出，在 Astro 启动或构建前给出 dry-run 和正式迁移指引。

多语言配对尤其不能只看文件名。假设默认语言文章已经把 note/old-name 定制为 my-stable-url，而英文对应文章没有 link。如果英文文章机械地使用自身路径，它会与默认语言失去同一公开 slug。因此，非默认语言文章会优先跟随默认语言文章的稳定链接；只有缺少默认语言对应文章时，才会复用其他译文的唯一候选，候选互相矛盾时宁可让用户决定。反过来，默认语言文章没有显式链接时，路径本身就是已有的公开 URL，不能被译文的自定义链接覆盖，其他缺少链接的译文也应继续跟随这条路径。

旧的 pnpm save-slugs 仍保留为兼容入口，但新用户只需要记住 pnpm koharu migrate。这样迁移规则、备份流程和 CLI 反馈位于同一个入口，后续再增加数据版本也不必继续堆一次性脚本。

恢复旧备份不能只是 `cp -r`

内容字段迁完之后，还有一个更隐蔽的问题：旧恢复逻辑是把备份目录复制进新版本目录。如果新模板增加了一篇示例文章，而用户的旧备份里没有它，普通目录合并会把这篇文章留下。对文件系统来说这是“合并成功”，对用户来说却是恢复后凭空多出了一篇文章。

这说明备份恢复需要区分“用户快照”和“可向前合并的配置”，不能对所有目录使用同一种复制语义：

恢复对象	恢复语义	原因
`src/content/blog`	先清理目标，再恢复快照	文章集合必须与备份时完全一致
`public/img`	先清理目标，再恢复快照	避免已删除的用户图片残留
`src/pages/*.md`	只替换根目录下的独立 Markdown 页面	删除旧自定义页面，同时保留新版 `.astro` 路由
`config/`	合并恢复	还原用户配置，但保留新版新增的主题配置文件
summaries、similarities、LQIP	完整备份恢复；基础备份不包含	这些资产必须与文章快照配套

新备份 manifest 增加 schemaVersion: 2，但缺少该字段的历史归档仍按 v1 读取。对“独立 Markdown 页面为空”的情况，备份也会保留空目录标记，让恢复器能区分“用户当时确实没有独立页面”和“这类数据根本不在旧归档中”。前者应该清掉现有 Markdown 页面，后者则不应贸然删除任何东西。

恢复前不只检查扩展名和 manifest.json。CLI 会校验备份路径、manifest schema、声明的恢复项与归档实际内容，拒绝符号链接、未声明条目和文件/目录类型不匹配。校验和解压使用同一份只读私有快照，避免原归档在两步之间被替换。解压后也不会立即覆盖用户目录：恢复器会先在项目内准备候选快照、运行内容迁移，全部通过后再事务性切换；中途提交失败则回滚已切换的目标。

只要恢复项包含博客内容，恢复器就会紧接着执行同一套内容迁移。升级流程若发现无法自动处理的冲突，会中止 clean update 并进入原有回滚路径，而不是带着半迁移内容继续构建。基础备份恢复后，CLI 还会明确提示运行：

pnpm koharu generate all

这是因为基础备份只保护源数据与配置，不包含 AI 摘要、相似文章和 LQIP 等派生资产；完整备份才会携带与该内容快照配套的生成结果。

四个只在真实构建里暴露的问题

1. Markdown 插件配置开始弃用

原配置把 gfm、remarkPlugins 和 rehypePlugins 直接挂在 markdown 下。Astro 6.4 会对此发出弃用提示。项目的 Markdown 管线包含 Shoka 语法、链接嵌入、Mermaid、KaTeX 和代码块 transformer，不能简单删除，于是改为显式创建 unified processor：

import { unified } from '@astrojs/markdown-remark';

markdown: {
  processor: unified({
    gfm: true,
    remarkPlugins,
    rehypePlugins,
  }),
  syntaxHighlight: {
    type: 'shiki',
    excludeLangs: ['mermaid'],
  },
}

这样既消除了弃用路径，又保留 Astro 对 Shiki 4 的处理。

2. `react-tweet` 在预渲染环境里无法加载 CSS

升级后的首次生产构建报错：

Unknown file extension ".css"
Hint: add the package to vite.resolve.noExternal

旧配置中的 vite.ssr.noExternal 没有覆盖 Astro 6 的预渲染 environment。按照错误提示改成顶层 vite.resolve.noExternal 后，react-tweet 的 CSS 才重新进入 Vite 转换链：

vite: {
  resolve: {
    noExternal: ['react-tweet'],
  },
}

3. RSS 的旧 patch 版本不兼容 Zod 4

@astrojs/rss 4.0.14 在 Astro 6 下抛出：

z.function(...).returns is not a function

问题不是 RSS 数据，而是该版本仍调用 Zod 4 已移除的 API。升级到 4.0.19 后，默认、英文和日文三份 feed 都恢复生成。

4. i18n 配置描述了一个实际不存在的重定向

项目原来同时配置 prefixDefaultLocale: false 和 redirectToDefaultLocale: true。Astro 6 不再接受这个组合；更重要的是， Astro 5 基线里 /zh/ 和 /zh/post/* 本来就是 404，并没有真实重定向行为可以保留。

最终删除无效选项，同时更新代码注释。规范 feed URL 仍是 /rss.xml、/en/rss.xml 和 /ja/rss.xml；即使 preview 目前还能访问 /rss.xml/，也不再把尾斜杠版本当作兼容契约。

怎样证明公开行为没有漂移

先验证模板公开行为

最终普通构建的结果如下。路由产物集合比较发生在加入本文之前，避免新文章本身干扰迁移前后对比。

指标	Astro 5	Astro 6	结论
静态页面	130	130	一致
Pagefind 索引页面	134	134	一致
`dist/` 路由产物	141	141	无新增、无丢失
Astro 构建耗时	21.62s	21.76s	接近基线

除了 pnpm lint、pnpm check、pnpm build 和 git diff --check，还做了这些输出级验证：

/、/en/、/ja/，以及默认语言和本地化文章均返回 200；/zh/ 保持 404；
未翻译文章的英文 fallback 页面仍显示默认语言正文，canonical 指回默认语言 URL；
代表性文章产物同时包含 Pagefind body、Shiki、KaTeX 和 Mermaid 标记；
Pagefind 对 Astro 的实际查询返回 8 条结果，首条仍是 /post/getting-started/；
三份 RSS 都返回 text/xml，sitemap 和 robots 正常生成；
pnpm 10.28.2 使用 frozen lockfile 的干净依赖层安装成功，Astro 补丁确认生效，宿主机生产构建成功；验证环境的 Docker daemon 不可用，因此没有把完整镜像构建写成已验证项。

浏览器自动化环境当时没有可用的浏览器实例，因此没有把 ClientRouter 点击、搜索键盘操作写成“已自动化通过”。这里宁可明确验证边界，也不要把 HTML 和 HTTP 检查冒充完整的浏览器交互测试。

构建仍会出现 infographic 语言回退、一个外部知乎链接 403 和大 chunk 提示；它们在 Astro 5 基线中已经存在，不属于本次升级回归。

当前分支加入本文及迁移配套内容后，最终 Astro 6 构建生成 151 个静态页面，Pagefind 索引 155 个页面；这个数字用于确认最终交付状态能完整构建，不应拿来与加入新内容前的 130 / 134 基线直接比较。相似度资产覆盖全部 12 个默认语言条目，每项保留 5 个引用，且没有指向不存在文章的悬空引用。

再验证迁移脚本，而不只验证 happy path

模板当前有 21 篇 Markdown / MDX 内容。首次正式迁移处理了其中 2 篇没有 link 的旧示例文章；随后再次执行 pnpm koharu migrate --dry-run，结果是扫描 21 篇、待迁移 0 篇、错误 0 个。

自动化测试则刻意覆盖更危险的分支：

测试场景	关键断言
混合 `link` / `slug` / 空字段及多语言对应文章	URL 保留，译文复用稳定链接，第二次运行无变更
重复链接、危险 frontmatter、符号链接和并发改动	整批不写入，已开始的原子写入可回滚
缺失或不一致的 manifest、恶意归档条目和恢复提交失败	预览前拒绝非法归档，事务提交失败时恢复旧目标
把旧归档恢复到已有新模板内容的目录	旧快照精确替换、恢复后自动迁移，同时保留新版 Astro 路由与配置
跨版本更新、新版 `--check` 与 pnpm 版本锁定	命令行参数不串命令，依赖安装只使用明确的 pnpm 版本

这些分支由 Node 内置 test runner 执行，统一放在 pnpm test:migrate 中；当前共 42 个测试。它们验证的是数据不变式、归档边界和进程退出契约，而不是 CLI 文案，因此即使以后替换终端 UI，迁移的核心行为仍然有保护。

最后用真实下游仓库做完整恢复

只拿几篇 fixture 证明脚本可用仍然不够。实际验证选了一份从 astro-koharu v4.2.1 长期演进而来的个人仓库，在不修改源仓库的前提下读取它的完整备份，并恢复到一个临时 Astro 6 副本：

检查项	结果
历史 Markdown / MDX	376 篇
已有稳定 `link`	375 篇
需要自动补齐	1 篇
同语言 URL 冲突	0
恢复后的内容数量	376 篇
`astro check`	0 error / warning / hint
Astro 6 静态页面	797
Pagefind 索引页面	801

这个测试同时验证了两个容易漏掉的点。第一，临时副本中由新版模板自带、但不在旧快照里的示例文章没有残留，证明博客目录执行的确实是快照替换，而不是目录合并。第二，恢复后只有 1 篇文章被自动补齐 link，另外 375 篇的 metadata 和正文不需要重写。迁移前后的源仓库 Git 状态保持干净，验证产物和临时归档也在结束后删除。

历史内容构建仍出现少量 KaTeX Unicode、未知 Shiki 语言别名和外部链接抓取失败提示。这些 warning 来自旧文章本身，既没有造成 Astro 6 类型诊断，也没有阻止 797 个页面完成生产构建，因此应该记录和后续治理，但不能误判成数据迁移失败。

哪些 Astro 6 能力值得顺手开启

答案比预想中保守：只接受 Astro 6 默认带来的新 dev/build pipeline。

Fonts API：稳定且值得单独研究，但项目已有约 20 MB 中日文字体分片、按 locale 加载和阅读器字体设置，不是零成本替换；
CSP：当前与 ClientRouter、Shiki 以及多种 inline/第三方资源冲突，本轮不启用；
Live Content Collections / route caching：面向按需渲染，与 static + nginx 架构不匹配；
Sonda：继续保留 ANALYZE=true pnpm build 的按需模式，不增加日常构建成本。

Rust compiler 和 queued rendering 看似只需要一行配置，所以额外做了同机单次构建实验。它不是严格性能测试，但足以决定是否值得把实验配置留在主干：

模式	real time	Astro time	最大 RSS	相对默认
默认	25.29s	22.89s	2.30 GB	基线
queued rendering	26.60s	24.48s	2.36 GB	约慢 5.2%
Rust compiler 0.3.1	26.24s	23.66s	2.47 GB	约慢 3.8%

两项实验在这套内容和机器上都没有收益，相关配置与 @astrojs/compiler-rs 依赖随后全部移除。

一份可复用的迁移顺序

如果你的 Astro 项目也有复杂内容层，可以按下面的顺序降低排障噪声：

固定迁移前 Node、check、build、路由和代表性 HTML 基线；
显式锁定目标 major，不使用会跨 major 的 latest；
先升级 Astro 和官方 integrations，记录第一批真实错误；
单独迁移 content.config.ts、loader、entry.id 和 render(entry)；
区分内部内容 ID、公开 slug 与 frontmatter override，避免机械替换；
先对下游历史文章 dry-run，发现冲突时整批停止，不让用户手工批量改 frontmatter；
把正式迁移放在自动备份之后，并用第二次 dry-run 证明它是幂等的；
明确旧备份中哪些目录是快照替换、哪些配置需要向前合并，恢复内容后自动执行同一迁移；
逐个验证 Markdown、搜索、RSS、sitemap 和第三方 integrations；
比较路由集合，再检查 fallback canonical 和生成 HTML；
用至少一份真实下游备份做临时恢复、check 和生产构建；
最后才评估实验能力，并保证实验依赖不进入生产 lockfile。

astro-koharu 用户从旧版升级时，先运行 pnpm koharu update 并等进程完全退出，再用 pnpm koharu migrate --dry-run 查看计划，最后运行 pnpm koharu migrate 自动备份并执行。已有 link 会保留，旧 slug 会转换为 link，旧备份通过 Koharu CLI 恢复后也会自动执行同一迁移。如果忘记手动迁移， pnpm dev 和 pnpm build 的只读检查会阻止旧内容进入 Astro 6 管线，但不会替用户改写文章。

总结

这次迁移最后没有留下兼容 flag，也没有改变静态部署架构。最大的收获不是版本号从 5 变成 6，而是把内容身份和数据升级的边界写清楚：entry.id 负责内部查找，公开 slug 负责 URL，link 只覆盖后者；备份中的文章和图片是用户快照，配置则需要在恢复用户值的同时接住新版本能力。这个模型一旦明确，多语言 fallback、搜索、RSS 和旧备份恢复就有了共同依据。

major upgrade 最可靠的完成标准也不是“模板构建成功”，而是能回答三个问题：哪些行为必须保持、历史数据如何安全过桥、哪些结论有可重复的证据。版本升级只是代码改动；当一份真实的 376 篇文章备份也能无损恢复并完成生产构建，这次迁移才真正覆盖到了用户。

容器查询实战：让卡片自己决定布局

Mon, 08 Jun 2026 14:15:00 GMT

做博客首页时遇到一个很常见的问题：同一张文章卡片，放在主栏里宽，放在侧栏里窄。用媒体查询只能根据视口宽度判断，可卡片关心的其实是「我自己有多宽」。

容器查询（container queries）解决的正是这个问题。这篇记录我把一张卡片从媒体查询改成容器查询的过程。

问题：视口宽度不等于组件宽度

媒体查询的写法

最初的卡片是这样写的：

card.css

@media (min-width: 768px) {
  .post-card {
    display: grid;
    grid-template-columns: 200px 1fr;
  }
}

在主栏里没问题。但把同一张卡片放进 280px 宽的侧栏后，只要视口超过 768px，它依然会切成左右两栏，封面被挤成一条。

为什么不给侧栏单独写一套

最直接的办法是加一个修饰类，比如 .post-card--compact。这能用，但意味着每个使用卡片的地方都要知道卡片的内部布局。放进新的位置，就得再加一个变体。组件应该自己处理这件事。

基本用法

声明容器

先在卡片的父元素上声明它是一个容器：

card.css

.post-card-wrapper {
  container-type: inline-size;
  container-name: card;
}

也可以用简写：

.post-card-wrapper {
  container: card / inline-size;
}

container-type 的取值

取值	含义
`inline-size`	只按行内方向（横排文字时就是宽度）查询，最常用
`size`	同时按宽高查询，要求元素有确定的高度
`normal`	默认值，不作为尺寸容器

container-type: size 会让元素的高度不再由内容撑开，大多数情况下你需要的是 inline-size。

编写查询

然后把原来的媒体查询换成容器查询：

card.css

@container card (min-width: 480px) {
  .post-card {
    display: grid;
    grid-template-columns: 200px 1fr;
  }
}

现在卡片只看包裹它的容器有多宽，和视口无关。

容器查询单位

cqi 与 cqw

容器查询还带来了一组相对单位，其中最实用的是 cqi：容器行内尺寸的 1%。

card.css

.post-card h3 {
  font-size: clamp(1rem, 4cqi, 1.5rem);
}

标题字号会随卡片宽度平滑变化，而不是在断点处突然跳一下。

什么时候用 cqw

cqw 指容器宽度的 1%，在横排文字下和 cqi 等价。我习惯统一用 cqi，这样以后支持竖排时不用改。

没有容器时会怎样

如果元素的祖先里没有任何容器，这些单位会退回到相对视口计算，不会报错，但效果可能不是你想要的。

在 Tailwind 里使用

Tailwind CSS v4 内置了容器查询，不需要插件：

PostCard.astro

<div class="@container">
  <article class="flex flex-col gap-4 @md:flex-row">
    <img class="aspect-video w-full rounded-lg object-cover @md:w-48" src="/img/cover/12.webp" alt="" />
    <div>...</div>
  </article>
</div>

@container 声明容器，@md: 这类前缀表示「容器宽度达到这个断点时」。命名容器写成 @container/card，查询时写 @md/card:flex-row。

踩过的坑

容器不能查询自己

@container 里的规则只能作用于容器的后代。我一开始把 container-type 和网格布局写在同一个元素上，结果怎么也不生效。解决方法就是多包一层。

和 overflow 的配合

声明为 inline-size 容器的元素会建立尺寸约束（size containment）。如果它的宽度原本依赖子元素撑开，比如在 inline-block 或 flex 子项里，宽度可能会塌成 0。给容器一个明确的宽度，或者让它在块级上下文里自然填满。

调试

Chrome 开发者工具的 Elements 面板会在容器元素旁标出 container 徽标，点一下可以高亮这个容器。排查不生效的问题时，先确认这里有没有标记。

小结

容器查询把「布局随空间变化」这件事交还给了组件本身。改完之后，卡片放到哪里都不用额外写变体。

原生 CSS Tailwind v4

.wrapper { container: card / inline-size; }
@container card (min-width: 480px) {
  .post-card { display: grid; grid-template-columns: 200px 1fr; }
}

<div class="@container">
  <article class="flex flex-col @md:flex-row">...</article>
</div>

更完整的说明可以看 MDN 的容器查询指南。

一篇 Markdown 在构建时经过了什么

Mon, 11 May 2026 12:05:00 GMT

写主题文档时经常被问到：「为什么这个语法在加密块里也能用？」「链接卡片的数据是什么时候抓的？」答案都藏在构建顺序里。这篇用几张图把一篇 Markdown 文章从源文件到 HTML 的路径画出来。

本文由 AI 根据 astro.config.mjs 的插件注册顺序起草，我核对过顺序并删改了措辞。插件的增减以仓库当前代码为准。

总览

flowchart TD
    A[Markdown 源文件] --> B[frontmatter 校验<br/>content.config.ts]
    B --> C[remark 阶段<br/>处理 Markdown 语法树]
    C --> D[rehype 阶段<br/>处理 HTML 语法树]
    D --> E[Shiki 代码高亮]
    E --> F[页面模板渲染]
    F --> G[Pagefind 建立搜索索引]

frontmatter 先经过 Zod schema 校验。字段写错类型（比如把 tags 写成字符串）会在这一步直接报错，而不是渲染出奇怪的页面。

remark 阶段

remark 处理的是 Markdown 语法树（mdast），这里的顺序有讲究：

flowchart LR
    P[Shoka 预处理] --> M[数学公式]
    M --> S[隐藏文字]
    S --> R[注音 Ruby]
    R --> E[下划线与高亮]
    E --> D[加密块指令]
    D --> L[链接卡片]

Shoka 预处理必须第一个跑。它会重新解析原始文本，修正 GFM 和 Shoka 语法之间的冲突。
数学公式要在注音、隐藏文字之前，否则 $a^b$ 里的 ^ 可能被当成注音语法。
链接卡片在最后，这时段落结构已经稳定，只需要找出「单独成段的链接」。

链接卡片的数据从哪来

sequenceDiagram
    participant B as 构建进程
    participant C as .cache/og-data.json
    participant W as 目标网站
    B->>C: 查询 URL
    alt 缓存有效
        C-->>B: 返回标题、描述、图片
    else 缓存缺失或过期
        B->>W: 请求页面并解析 Open Graph
        W-->>B: OG 信息或错误
        B->>C: 写回缓存
    end
    B->>B: 渲染卡片，失败则保留普通链接

成功的结果默认缓存 30 天（content.previewCacheTime），失败的结果只缓存一天，方便下次构建重试。这个缓存文件是特意提交到 Git 的，CI 上构建时就不必重新抓取。

rehype 阶段

rehype 处理 HTML 语法树（hast）：

给标题生成 id，并附上锚点链接
处理 Shoka 的花括号属性语法（给元素追加 class）
给图片加上低质量占位图（LQIP）
用 KaTeX 渲染公式
最后才是加密：整篇加密和 :::encrypted 块

加密放在最后，是因为它要加密的是已经完全渲染好的 HTML。这也回答了开头的问题：加密块里的代码高亮、公式、链接，在加密之前就已经处理完了。

代码块

代码块由 Shiki 在构建时高亮，所以页面上不需要加载任何高亮脚本。title、mark、command 这些元信息由一个 Shiki transformer 解析：

example.js

const site = 'astro-koharu';
console.log(`Hello from ${site}`);

Mermaid 代码块被排除在 Shiki 之外，交给 Mermaid 单独渲染，本文的几张图就是这样来的。

小结

pie title 一篇文章的处理阶段（按插件数量粗略划分）
    "remark" : 9
    "rehype" : 7
    "Shiki transformer" : 2

记住两条就够用：remark 管语法，rehype 管结构；加密永远在最后。

下雨的周六下午

Sat, 18 Apr 2026 09:40:00 GMT

本来打算出门，下午两点开始下雨，就没去成。

泡了一壶茶，把阳台的椅子挪到窗边，翻完了一本搁了很久的短篇集。书不厚，十来个故事，每篇讲的都是很小的事：一个人搬家，一个人等车，一个人在超市里找不到想买的东西。读的时候没什么感觉，合上书以后，反而想起好几个细节。

雨一直没停。楼下有人撑着伞遛狗，狗不太情愿，走两步就停下来甩毛。

傍晚收拾桌子，发现草稿箱里还有三篇没写完的文章。挑了一篇改到能发的程度，剩下两篇先放着。

今天就这样，挺好的。

自定义关键词示例

Sun, 05 Apr 2026 10:43:11 GMT

本文展示如何设置文章关键词。

frontmatter 关键词设置

在文章的 frontmatter 中添加 keywords 字段即可设置关键词：

---
title: 我的文章
date: 2026-01-01
keywords:
  - 示例关键词一
  - 示例关键词二
---

这是篇带有关键词的文章。

然后生成的页面会包含以下 meta 标签：

<meta name="keywords" content="示例关键词一, 示例关键词二, ... site.keywords">

🔒 加密文章演示

Mon, 16 Feb 2026 16:00:00 GMT

此文章已加密，请在网页中查看

Shoka 主题 Markdown 语法演示

Sat, 07 Feb 2026 04:00:00 GMT

本文展示了从 Hexo Shoka 主题迁移的所有特殊 Markdown 语法。

文字特效

下划线 (ins)

++这是下划线文字++

++波浪下划线++{.wavy}

++着重点标记++{.dot}

这是下划线文字

波浪下划线

着重点标记

下划线颜色

++主色调++{.primary} ++成功++{.success} ++警告++{.warning} ++危险++{.danger} ++信息++{.info}

主色调成功警告危险信息

高亮 (mark)

==这是高亮文字==

这是高亮文字

上下标

H~2~O 是水的化学式
E = mc^2^ 是质能方程

H₂O 是水的化学式

E = mc² 是质能方程

颜色文字

[红色]{.red} [粉色]{.pink} [橙色]{.orange} [黄色]{.yellow} [绿色]{.green} [水色]{.aqua} [蓝色]{.blue} [紫色]{.purple} [灰色]{.grey}

红色粉色橙色黄色绿色水色蓝色紫色灰色

彩虹文字

[这段文字会有彩虹渐变效果]{.rainbow}

这段文字会有彩虹渐变效果

键盘键

[Ctrl]{.kbd} + [C]{.kbd} 复制，[Ctrl]{.kbd} + [V]{.kbd} 粘贴

Ctrl + C 复制，Ctrl + V 粘贴

隐藏文字 (Spoiler)

这里有一段!!隐藏文字，鼠标点击显示!!

这里有一段!!模糊文字，鼠标悬停显示!!{.blur}

这里有一段隐藏文字，鼠标点击显示

这里有一段模糊文字，鼠标悬停显示

标签块 (Labels)

[默认]{.label .default} [主要]{.label .primary} [信息]{.label .info} [成功]{.label .success} [警告]{.label .warning} [危险]{.label .danger}

默认主要信息成功警告危险

提醒块 (Note Blocks)

:::default
这是默认提醒块
:::

:::primary
这是主要提醒块，用于重要提示
:::

:::info
这是信息提醒块，用于提供额外信息
:::

:::success
这是成功提醒块，用于正面反馈
:::

:::warning
这是警告提醒块，请注意
:::

:::danger
这是危险提醒块，务必谨慎
:::

:::info no-icon
这是没有图标的信息块
:::

这是默认提醒块

这是主要提醒块，用于重要提示

这是信息提醒块，用于提供额外信息

这是成功提醒块，用于正面反馈

这是警告提醒块，请注意

这是危险提醒块，务必谨慎

这是没有图标的信息块

折叠块 (Collapse)

+++primary 点击展开详细内容
这里是折叠的内容，点击标题可以展开或收起。

支持 **Markdown** 格式化。

- 列表项 1
- 列表项 2
+++

+++warning 注意事项
这里列出一些需要注意的问题：

1. 注意事项一
2. 注意事项二
+++

+++danger 危险操作
请确保你知道自己在做什么！

```bash
rm -rf /  # 请勿执行此命令
```
+++

点击展开详细内容

这里是折叠的内容，点击标题可以展开或收起。

支持 Markdown 格式化。

列表项 1
列表项 2

注意事项

这里列出一些需要注意的问题：

注意事项一
注意事项二

危险操作

请确保你知道自己在做什么！

rm -rf /  # 请勿执行此命令

标签卡 (Tabs)

;;;tab1 JavaScript
```js
console.log('Hello, World!');
```
;;;

;;;tab1 Python
```python
print('Hello, World!')
```
;;;

;;;tab1 Rust
```rust
fn main() {
    println!("Hello, World!");
}
```
;;;

JavaScript Python Rust

console.log('Hello, World!');

print('Hello, World!')

fn main() {
    println!("Hello, World!");
}

注音

{取り返す^とりかえす}是日语中"取回"的意思。

{漢字^かんじ}的注音示例。

取り返す(とりかえす)是日语中"取回"的意思。

漢字(かんじ)的注音示例。

代码块增强

```js title="hello.js" url="https://example.com" linkText="查看源码" mark:1,3
const greeting = 'Hello';
const name = 'World';
console.log(`${greeting}, ${name}!`);
```

```bash command:("$":1-3)
npm install astro
npm run dev
npm run build
```

hello.js查看源码

const greeting = 'Hello';
const name = 'World';
console.log(`${greeting}, ${name}!`);

npm install astro
npm run dev
npm run build

数学公式

行内公式：$E = mc^2$

块级公式：

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

$$
\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}
$$

行内公式：E=mc2E = mc^2E=mc2

块级公式：

∫−∞∞e−x2dx=π\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}∫−∞∞e−x2dx=π ∑n=1∞1n2=π26\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}n=1∑∞n21=6π2

友链卡

{% links %}
- site: 余弦の博客
  url: https://blog.cosine.ren
  owner: cos
  desc: FE / ACG / 手工
  image: https://blog.cosine.ren/img/avatar.webp
  color: '#ed788b'
- site: 示例博客
  url: https://example.com
  owner: Alice
  desc: 一个热爱技术的博客
  image: https://api.dicebear.com/7.x/avataaars/svg?seed=Alice
  color: '#BEDCFF'
{% endlinks %}

多媒体

音频

{% media audio %}
- name: 示例音频
  url: https://music.163.com/#/song?id=3339210292
{% endmedia %}

音频歌单

{% media audio %}
- title: 诗岸歌单 山山～全是山山～
  list:
    - https://music.163.com/#/playlist?id=8676645748
- title: 『诗岸』全是山山！
  list:
    - https://music.163.com/#/playlist?id=17606384886
{% endmedia %}

视频

{% media video %}
- name: "测试 1"
  url: https://cdn.kastatic.org/ka-youtube-converted/O_nY1TM2RZM.mp4/O_nY1TM2RZM.mp4#t=0
- name: "测试 2"
  url: https://cdn.kastatic.org/ka-youtube-converted/O_nY1TM2RZM.mp4/O_nY1TM2RZM.mp4#t=0
{% endmedia %}

练习题

支持四种题型：单选题、多选题、判断题、填空题。

单选题

- 下列哪个是 JavaScript 的基本数据类型？{.quiz}
  - Object{.options}
  - Array{.options}
  - Symbol{.correct}
  - Function{.options}

> 解析：Symbol 是 ES6 引入的基本数据类型，而 Object、Array、Function 都是引用类型。

下列哪个是 JavaScript 的基本数据类型？
- Object
- Array
- Symbol
- Function

解析：Symbol 是 ES6 引入的基本数据类型，而 Object、Array、Function 都是引用类型。

多选题

- 以下哪些是 CSS 布局方式？{.quiz .multi}
  - Flexbox{.correct}
  - jQuery{.options}
  - Grid{.correct}
  - Float{.correct}

> 解析：Flexbox、Grid 和 Float 都是 CSS 布局方式。jQuery 是一个 JavaScript 库，不属于 CSS 布局。

以下哪些是 CSS 布局方式？
- Flexbox
- jQuery
- Grid
- Float

解析：Flexbox、Grid 和 Float 都是 CSS 布局方式。jQuery 是一个 JavaScript 库，不属于 CSS 布局。

判断题

- `const` 声明的变量不能重新赋值，但可以修改其属性。{.quiz .true}

> 解析：`const` 只保证变量绑定不可变，如果变量指向一个对象，其属性仍然可以修改。

- HTML 是一种编程语言。{.quiz}

> 解析：HTML（超文本标记语言）是一种标记语言，不是编程语言。它没有逻辑控制能力。

const 声明的变量不能重新赋值，但可以修改其属性。

解析：const 只保证变量绑定不可变，如果变量指向一个对象，其属性仍然可以修改。

HTML 是一种编程语言。

解析：HTML（超文本标记语言）是一种标记语言，不是编程语言。它没有逻辑控制能力。

填空题

- 在 JavaScript 中，`typeof null` 的结果是 [object]{.gap}。{.quiz .fill}

> 解析：这是一个历史遗留 bug。`null` 的类型标签与 object 相同，因此 `typeof null` 返回 `"object"`。常见错误答案是 [null]{.mistake}。

在 JavaScript 中，typeof null 的结果是 object。

解析：这是一个历史遗留 bug。null 的类型标签与 object 相同，因此 typeof null 返回 "object"。常见错误答案是 null。

CSS 中，Flexbox 适合一维布局，Grid 适合二维布局，而 Float 是传统的布局方式。

解析：Flexbox 是一维布局模型（行或列），Grid 是二维布局模型（行和列同时控制），Float 是 CSS2 时代的传统布局方式。

加密内容块 (Encrypted Block)

使用 :::encrypted{password="密码"} 语法可以创建加密区块。区块内的内容在构建时使用 AES-256-GCM 进行真正加密，密码不会出现在最终的 HTML 中。读者需要输入正确密码才能解密查看。

适用场景：防止搜索引擎/爬虫收录敏感内容（如私人资源链接、付费内容片段等）。

前端无法实现真正意义上的加密：密码总需要在客户端输入，密文和算法都对用户可见，安全性完全取决于密码强度。本功能的目的不是对抗有针对性的破解，而是防止搜索引擎和爬虫直接收录明文内容。对于这个场景，AES-256-GCM 已经足够：构建产物中只有密文，不含密码和明文，搜索引擎无法索引加密区块的内容。


:::encrypted{password="test"}
这里是加密的内容，支持完整的 Markdown 语法：

- **粗体**、*斜体*、~~删除线~~
- `行内代码`
- [链接](https://example.com)

```js
console.log('加密内容中的代码也有语法高亮！');
```

行内公式 $E = mc^2$ 也可以正常渲染。
:::

:::encrypted{password="another"}
每个加密块可以设置独立的密码。
:::

Infographic 信息图指南

Sat, 03 Jan 2026 04:00:00 GMT

本文将详细介绍如何在 Markdown 中使用 @antv/infographic 创建各种精美的信息图表。

什么是 Infographic

Infographic（信息图）是一种将数据、信息和知识以视觉化方式呈现的图表形式。相比传统的文字描述，信息图能够更直观、更有吸引力地传达信息。

在本博客中，你可以直接在 Markdown 代码块中使用 infographic 标记来创建各种类型的信息图，支持：

列表展示
流程说明
数据对比
层级结构
统计图表
象限分析
关系展示

基本语法

在代码块中使用 infographic 标记，第一行指定模板名称，然后使用类似 YAML 的语法定义数据：

```infographic
infographic <template-name>
data
  title 标题
  desc 描述
  items
    - label 条目名称
      desc 条目描述
      icon mdi/icon-name
```

列表类模板 (list-*)

适合展示信息列表、特性清单、技术栈等。

网格卡片布局

使用 list-grid-badge-card 模板展示卡片式列表：

infographic list-grid-badge-card
data
  title 前端技术栈
  desc 现代化前端开发常用技术
  items
    - label TypeScript
      desc 类型安全的 JavaScript 超集
      icon mdi/language-typescript
    - label React
      desc 用于构建用户界面的 JavaScript 库
      icon mdi/react
    - label Astro
      desc 现代化静态站点生成器
      icon mdi/rocket-launch
    - label Tailwind CSS
      desc 实用优先的 CSS 框架
      icon mdi/tailwind
    - label Vite
      desc 下一代前端构建工具
      icon mdi/lightning-bolt
    - label Biome
      desc 一体化的 Web 工具链
      icon mdi/cog

糖果风格卡片

使用 list-grid-candy-card-lite 创建更有趣的卡片样式：

infographic list-grid-candy-card-lite
data
  title 博客特色功能
  items
    - label 深色模式
      desc 优雅的主题切换
      icon mdi/theme-light-dark
    - label 全站搜索
      desc 基于 Pagefind 的无后端搜索
      icon mdi/magnify
    - label Markdown 增强
      desc 支持 GFM、Mermaid、Infographic
      icon mdi/markdown
    - label 智能推荐
      desc 基于语义相似度的文章推荐
      icon mdi/brain

水平箭头列表

使用 list-row-horizontal-icon-arrow 展示线性列表：

infographic list-row-horizontal-icon-arrow
data
  title 开发流程
  items
    - label 需求分析
      icon mdi/clipboard-text
    - label 设计方案
      icon mdi/palette
    - label 编码实现
      icon mdi/code-tags
    - label 测试部署
      icon mdi/rocket-launch

流程/顺序类模板 (sequence-*)

适合展示步骤、流程、时间线等有顺序关系的信息。

之字形步骤

使用 sequence-zigzag-steps-underline-text 展示流程步骤：

infographic sequence-zigzag-steps-underline-text
data
  title 博客搭建流程
  items
    - label 选择框架
      desc 选择 Astro 作为静态站点生成器
    - label 设计主题
      desc 参考 Shoka 主题进行设计
    - label 开发功能
      desc 实现文章系统、搜索、评论等功能
    - label 部署上线
      desc 使用 Vercel 进行自动化部署

圆形流程

使用 sequence-circular-simple 展示循环流程：

infographic sequence-circular-simple
data
  title PDCA 循环
  items
    - label Plan
      desc 制定计划
    - label Do
      desc 执行实施
    - label Check
      desc 检查验证
    - label Act
      desc 改进优化

垂直路线图

使用 sequence-roadmap-vertical-simple 展示时间线或路线图：

infographic sequence-roadmap-vertical-simple
data
  title 项目里程碑
  items
    - label 2024 Q1
      desc 项目启动，完成基础架构
    - label 2024 Q2
      desc 实现核心功能，开始内容迁移
    - label 2024 Q3
      desc 优化性能，添加高级功能
    - label 2024 Q4
      desc 正式发布，持续优化

金字塔结构

使用 sequence-pyramid-simple 展示层级递进关系：

infographic sequence-pyramid-simple
data
  title 马斯洛需求层次
  items
    - label 自我实现
    - label 尊重需求
    - label 社交需求
    - label 安全需求
    - label 生理需求
theme
  palette
    - #8b5cf6
    - #3b82f6
    - #06b6d4
    - #10b981
    - #f59e0b

对比类模板 (compare-*)

适合展示二元对比、优缺点分析等。

水平二元对比

使用 compare-binary-horizontal-simple-fold 进行对比：

infographic compare-binary-horizontal-simple-fold
data
  title SSR vs SSG
  items
    - label 服务端渲染 (SSR)
      children
        - label 实时生成
          desc 每次请求时渲染页面
        - label 动态内容
          desc 适合频繁更新的内容
        - label 服务器负载
          desc 需要服务器资源
    - label 静态生成 (SSG)
      children
        - label 构建时生成
          desc 提前生成所有页面
        - label 静态内容
          desc 适合内容相对稳定的场景
        - label CDN 友好
          desc 可以部署到 CDN 边缘节点

SWOT 分析

使用 compare-swot 进行 SWOT 分析：

infographic compare-swot
data
  title 技术博客 SWOT 分析
  items
    - label 优势 (Strengths)
      children
        - label 技术积累
        - label 个人品牌
        - label 知识沉淀
    - label 劣势 (Weaknesses)
      children
        - label 时间投入
        - label 持续更新压力
        - label 初期流量低
    - label 机会 (Opportunities)
      children
        - label 技术社区活跃
        - label 开源生态发展
        - label 个人成长空间
    - label 威胁 (Threats)
      children
        - label 内容同质化
        - label 平台竞争
        - label 技术快速迭代

层级类模板 (hierarchy-*)

适合展示组织结构、分类体系等树形关系。

系统分层结构

使用 hierarchy-structure 展示多层架构，非常适合展示系统架构、模块分层：

infographic hierarchy-structure
data
  title 系统分层结构
  desc 展示不同层级的模块与功能分组
  items
    - label 展现层
      children
        - label 小程序
        - label APP
        - label PAD
        - label 客户端
        - label WEB
    - label 应用层
      children
        - label 核心模块
          children
            - label 功能1
            - label 功能2
            - label 功能3
            - label 功能4
            - label 功能5
            - label 功能6
        - label 基础模块
          children
            - label 功能1
            - label 功能2
            - label 功能3
            - label 功能4
            - label 功能5
            - label 功能6
        - label 其他模块
          children
            - label 功能1
            - label 功能2
            - label 功能3
            - label 功能4
            - label 功能5
            - label 功能6
    - label 平台层
      children
        - label 模块1
          children
            - label 功能1
            - label 功能2
            - label 功能3
            - label 功能4
        - label 模块2
          children
            - label 功能1
            - label 功能2
            - label 功能3
            - label 功能4
        - label 模块3
          children
            - label 功能1
            - label 功能2
            - label 功能3
            - label 功能4

科技风格树形图

使用 hierarchy-tree-tech-style-capsule-item 展示层级结构：

infographic hierarchy-tree-tech-style-capsule-item
data
  title 前端技术体系
  items
    - label 前端开发
      children
        - label 基础技术
          children
            - label HTML
            - label CSS
            - label JavaScript
        - label 框架/库
          children
            - label React
            - label Vue
            - label Astro
        - label 工程化
          children
            - label Vite
            - label Webpack
            - label Rollup

圆角矩形树形图

使用 hierarchy-tree-curved-line-rounded-rect-node 展示层级：

infographic hierarchy-tree-curved-line-rounded-rect-node
data
  title 博客内容分类
  items
    - label 技术文章
      children
        - label 前端
          children
            - label React
            - label TypeScript
        - label 后端
          children
            - label Node.js
            - label 数据库
    - label 生活随笔
      children
        - label 年度总结
        - label 读书笔记

图表类模板 (chart-*)

适合展示统计数据、数值对比等。

柱状图

使用 chart-column-simple 展示数据对比：

infographic chart-column-simple
data
  title 月度文章发布统计
  items
    - label 1月
      value 5
    - label 2月
      value 8
    - label 3月
      value 12
    - label 4月
      value 6
    - label 5月
      value 10
    - label 6月
      value 15

条形图

使用 chart-bar-plain-text 展示横向对比：

infographic chart-bar-plain-text
data
  title 编程语言使用占比
  items
    - label TypeScript
      value 45
    - label JavaScript
      value 25
    - label Python
      value 15
    - label Go
      value 10
    - label Others
      value 5

饼图

使用 chart-pie-plain-text 展示占比分布：

infographic chart-pie-plain-text
data
  title 访问来源分布
  items
    - label 搜索引擎
      value 45
    - label 社交媒体
      value 30
    - label 直接访问
      value 15
    - label 外部链接
      value 10

环形图

使用 chart-pie-donut-pill-badge 创建环形图：

infographic chart-pie-donut-pill-badge
data
  title 技术栈占比
  items
    - label 前端
      value 50
    - label 后端
      value 30
    - label DevOps
      value 20

折线图

使用 chart-line-plain-text 展示趋势：

infographic chart-line-plain-text
data
  title 博客访问量趋势
  items
    - label 第1周
      value 100
    - label 第2周
      value 150
    - label 第3周
      value 200
    - label 第4周
      value 280
    - label 第5周
      value 350
    - label 第6周
      value 420

象限分析 (quadrant-*)

适合展示四象限分析、优先级矩阵等。

简单卡片象限

使用 quadrant-quarter-simple-card 进行象限分析：

infographic quadrant-quarter-simple-card
data
  title 四象限分析
  items
    - label 重要且紧急
      desc 直接规避风险
      illus notify
    - label 重要不紧急
      desc 采取风险控制措施
      illus coffee
    - label 不重要但紧急
      desc 通过保险转移风险
      illus diary
    - label 不重要不紧急
      desc 选择接受风险
      illus invest

关系图 (relation-*)

适合展示元素间的关联关系。

圆形图标关系

使用 relation-circle-icon-badge 展示关系网络：

infographic relation-circle-circular-progress
data
  title 子公司盈利分析
  desc 各子公司财务表现，盈利同比增长
  items
    - label 云计算子公司
      value 25
      desc 年度净利润率达25%，成为集团核心增长引擎
      icon mingcute/cardano-ada-fill
    - label 人工智能子公司
      value 40
      desc AI业务快速扩张，盈利同比增长40%
      icon mingcute/openai-fill
    - label 物联网子公司
      value 1000
      desc IoT设备出货量突破千万，盈利稳步提升
      icon mingcute/medium-fill
    - label 金融科技子公司
      value 18
      desc 数字支付业务增长迅猛，净利润率18%
      icon mingcute/paypal-fill
    - label 新能源子公司
      value 50
      desc 绿色能源项目实现规模化盈利，增长潜力巨大
      icon mingcute/drone-fill

主题定制

可以通过 theme 块自定义颜色方案：

infographic list-grid-badge-card
data
  title 自定义配色示例
  items
    - label 主色调
      desc 品牌主色
    - label 辅助色
      desc 强调色彩
    - label 中性色
      desc 背景文字
theme
  palette
    - #3b82f6
    - #8b5cf6
    - #f97316
    - #06b6d4
    - #10b981

实用技巧

1. 选择合适的模板

根据要展示的信息类型选择对应的模板：

列表信息 → list-*
流程步骤 → sequence-*
数据对比 → compare-* 或 chart-*
层级关系 → hierarchy-*
优先级分析 → quadrant-*
关联关系 → relation-*

2. 合理使用图标

使用 Material Design Icons 让信息图更生动：

icon mdi/rocket-launch
icon mdi/heart
icon mdi/lightbulb
icon mdi/chart-line

3. 控制信息密度

每个信息图不要包含过多条目（建议 3-8 个）
使用简洁的标签和描述
复杂信息可以拆分成多个信息图

4. 注意主题适配

信息图会自动跟随博客的深色/浅色主题切换，无需额外配置。

总结

Infographic 为 Markdown 文档提供了强大的可视化能力，能够让技术博客、文档、笔记更加生动易读。合理使用各种模板，可以显著提升内容的表现力和可读性。

更多模板和详细文档，请访问 Infographic 官方网站。

2025 年终：写得不多，但都写完了

Wed, 31 Dec 2025 15:20:00 GMT

又到年底。今年写的东西不多，翻了一下归档页，每个月零零散散有一两篇，有几个月是空的。

这一年

infographic sequence-roadmap-vertical-simple
data
  title 2025
  items
    - label 年初
      desc 补完了一部拖了很久的番，写了观后感
    - label 春天
      desc 周刊恢复更新，换了更顺手的工具
    - label 夏天
      desc 写周刊第三期，之后停了一阵
    - label 秋天
      desc 研究博客加密和构建流程，写了几篇笔记
    - label 年底
      desc 整理归档，写下这篇

做完的事

博客迁到了新主题，旧文章的链接都保留了下来
周刊从第一期写到了第三期，虽然间隔很长
读完了十几本书，大部分是小说

没做完的事

计划中的系列教程只写了开头
草稿箱里还有好几篇半成品
说好要学的那门语言，课本还是新的

明年

不立太多目标。能保持每个月写一篇，就算达成了。

新年快乐。

astro-koharu 使用指南

Mon, 29 Dec 2025 13:55:00 GMT

一份完整的 astro-koharu 博客系统使用指南，帮助你快速上手并充分利用所有功能特性。

github.com

GitHub - cosZone/astro-koharu: astro-koharu 是一个萌系/二次元/粉蓝配色的 astro 主题博客，灵感来自 Hexo 的 Shoka 主题，加了很多自己的小巧思，性能优越。

astro-koharu 是一个萌系/二次元/粉蓝配色的 astro 主题博客，灵感来自 Hexo 的 Shoka 主题，加了很多自己的小巧思，性能优越。 - cosZone/astro-koharu

https://github.com/cosZone/astro-koharu

快速开始

项目简介

astro-koharu 是一个基于 Astro 7.x 构建的现代化博客系统，从 Hexo 迁移而来，设计灵感和初衷都来自 Shoka 主题。欢迎 fork 出来制作自己的主题。

核心特点：

基于 Astro 7.x，静态站点生成，性能优异
优雅的深色/浅色主题切换
基于 Pagefind 的无后端全站搜索
完整的 Markdown 增强功能（GFM、代码高亮、自动目录）
灵活的多级分类与标签系统（从 Shoka 主题迁移，后续会考虑将其改为可关闭的）
多系列文章支持（周刊、书摘等自定义系列，支持自定义 URL slug）
响应式设计
草稿与置顶功能
阅读进度条与阅读时间估算
移动端文章阅读头部
友链系统与归档页面
多语言支持（i18n）
RSS 订阅支持
LQIP（低质量图片占位符）
圣诞特辑（可开关）

本地开发

# 克隆项目
git clone https://github.com/cosZone/astro-koharu.git
cd astro-koharu

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

# 构建生产版本
pnpm build

# 预览生产构建
pnpm preview

快速部署

使用 Vercel 进行一键部署：

构建缓存说明

项目将 .cache/og-data.json 提交到 Git 仓库。该文件缓存了链接嵌入功能抓取的外部链接 OG 元数据（标题、描述、图片等），提交到 Git 后 Vercel、Netlify 等平台构建时可直接复用，无需每次重新抓取，显著加速构建速度。

.cache/ 目录下的其他文件（如 transformers/ 模型缓存、summaries-cache.json）仍被 .gitignore 忽略，不会提交。

基本配置

站点配置

编辑 config/site.yaml 文件配置站点基本信息：

# =============================================================================
# 站点基础信息
# =============================================================================
site:
  title: 余弦の博客 # 网站标题
  alternate: cosine # 英文短名（用作 logo 文本）
  subtitle: WA 的一声就哭了 # 副标题
  name: cos # 站点作者简称
  description: FE / ACG / 手工 / 深色模式强迫症 / INFP # 站点简介
  avatar: /img/avatar.webp # 头像路径
  showLogo: true # 是否显示 logo
  author: cos # 文章作者
  url: https://blog.cosine.ren/ # 站点域名
  startYear: 2020 # 站点创建年份
  keywords: # SEO 关键词
    - cos
    - cosine
    - 博客
    - 技术
    - 前端

本地轻 CMS 应用

本项目提供独立的 CMS 管理应用，支持文章管理、浏览器内编辑、Markdown 预览等功能。

启动 CMS：

# 首次使用需安装依赖
pnpm cms:install

# 启动 CMS（默认端口 4322）
pnpm cms

CMS 提供以下功能：

📊 文章仪表盘：查看文章统计、分类分布、最近更新
📝 浏览器内编辑器：与公开写作室共用 CodeMirror 源码编辑、Shoka 实时预览及中文语法手册，CMS 可保存完整 Markdown 原文
🔄 草稿/发布切换：一键切换文章状态
📌 置顶管理：快速置顶/取消置顶文章
➕ 新建文章：交互式创建文章，自动生成 frontmatter

本地编辑器跳转

开发环境下，文章页「复制 Markdown」按钮组的下拉菜单支持一键跳转到本地编辑器（VS Code / Cursor / Zed 等）。

配置文件： config/site.yaml 的 dev 部分

dev:
  localProjectPath: "/Users/yourname/path/to/astro-koharu" # 本地项目绝对路径
  contentRelativePath: "src/content/blog" # 博客内容目录
  editors:
    - id: vscode
      name: VS Code
      icon: devicon-plain:vscode # 可从 https://icon-sets.iconify.design/ 搜寻图标
      urlTemplate: "vscode://file/{path}"
    - id: cursor
      name: Cursor
      icon: simple-icons:cursor
      urlTemplate: "cursor://file/{path}"
    - id: zed
      name: Zed
      icon: simple-icons:zedindustries
      urlTemplate: "zed://file/{path}"

配置说明：

localProjectPath 必须是本机的绝对路径，否则无法生成正确的文件路径
urlTemplate 支持占位符，会被替换为文件的完整路径
配置后，开发环境的文章页下拉菜单会列出这些编辑器，点击可直接在本地编辑器中打开文件

特色分类配置：

在首页底部展示的精选分类卡片：

featuredCategories:
  - link: life # 分类链接（对应 category_map）
    label: 随笔 # 显示名称
    image: /img/cover/2.webp # 封面图片
    description: 生活记录、年度总结等 # 描述
  - link: note/front-end
    label: 前端笔记
    image: /img/cover/1.webp
    description: 前端相关的笔记
  # ... 更多分类

多系列文章配置：

配置特色系列（如周刊、书摘等），支持多个系列，每个系列拥有独立页面和自定义 URL：

featuredSeries:
  - slug: weekly # URL 路径: /weekly（必填，作为页面路由）
    categoryName: 周刊 # 分类名称（用于匹配文章）
    label: FE Bits # 显示标签
    fullName: FE Bits 前端周周谈 # 完整名称
    description: | # 描述（支持多行）
      之前在自己的频道进行一些输出，于是有了这个周刊！
      更新时间期望是在每周天
    cover: /img/weekly_header.webp # 封面图
    enabled: true # 是否启用
    icon: ri:newspaper-line # 导航图标（可选）
    highlightOnHome: true # 是否在首页高亮最新文章（可选，默认 true）
    links: # 相关链接
      github: https://github.com/your-username/your-repo
      rss: /rss.xml

  - slug: reading # URL 路径: /reading
    categoryName: 书摘
    label: 读书笔记
    fullName: 我的读书笔记
    description: 读书摘录与感悟
    cover: /img/reading_header.webp
    enabled: true
    highlightOnHome: false # 此系列不在首页高亮

字段说明：

字段	必填	说明
`slug`	✅	URL 路径，如 `weekly` 对应 `/weekly`
`categoryName`	✅	分类名称，用于匹配文章
`label`	❌	显示标签（默认使用 categoryName）
`enabled`	❌	是否启用此系列（默认 true）
`fullName`	❌	完整名称（用于页面标题）
`description`	❌	系列描述
`cover`	❌	封面图片路径
`icon`	❌	导航图标（Iconify 格式）
`highlightOnHome`	❌	是否在首页高亮最新文章（默认 true）
`links`	❌	相关链接（github、rss 等）

社交媒体配置

在 config/site.yaml 中配置社交媒体链接：

social:
  github:
    url: https://github.com/your-username
    icon: ri:github-fill # Iconify 图标名
    color: "#191717" # 主题色
  bilibili:
    url: https://space.bilibili.com/your-uid
    icon: ri:bilibili-fill
    color: "#da708a"
  email:
    url: mailto:your@email.com
    icon: ri:mail-line
    color: "#55acd5"
  rss:
    url: /rss.xml
    icon: ri:rss-line
    color: "#ff6600"
  # ... 更多平台

支持的平台：GitHub, Twitter, Bilibili, 网易云音乐, Email, RSS 等。完整配置请参考 config/site.yaml 文件。

导航配置

在 config/site.yaml 中自定义导航菜单：

navigation:
  - name: 首页
    path: /
    icon: fa6-solid:house-chimney
  - name: 周刊
    path: /weekly # 对应 featuredSeries 中 slug: weekly 的系列
    icon: ri:newspaper-line
  - name: 读书笔记
    path: /reading # 对应 featuredSeries 中 slug: reading 的系列
    icon: ri:book-open-line
  - name: 文章
    icon: ri:quill-pen-ai-fill
    children: # 支持嵌套子菜单
      - name: 分类
        path: /categories
        icon: ri:grid-fill
      - name: 标签
        path: /tags
        icon: fa6-solid:tags
      - name: 归档
        path: /archives
        icon: ri:archive-2-fill
  - name: 友链
    path: /friends
    icon: ri:links-line
  - name: 关于
    path: /about
    icon: fa6-regular:circle-user

注意：系列页面的路径格式为 /{slug}，需要与 featuredSeries 中配置的 slug 字段一致。

分类映射配置

在 config/site.yaml 中配置中文分类名到 URL slug 的映射：

# =============================================================================
# Category Map
# Maps Chinese category names to URL-friendly English slugs
# =============================================================================
categoryMap:
  # Primary categories
  随笔: life
  笔记: note
  工具: tools
  周刊: weekly # 用于分类页面 /categories/weekly
  书摘: reading # 用于分类页面 /categories/reading
  # Secondary categories (for nested paths)
  前端: front-end
  # Add more as needed:
  # 后端: back-end
  # 算法: algorithm

这样，"随笔" 分类的 URL 会是 /categories/life，而不是 /categories/随笔。

注意：categoryMap 仅用于分类页面（/categories/*）的 URL 映射。系列页面的 URL（如 /weekly、/reading）由 featuredSeries 中的 slug 字段单独配置。

文章系统

创建文章

方式一：使用 Koharu CLI（推荐）

使用交互式 CLI 工具快速创建文章：

pnpm koharu new post

CLI 工具会引导你输入标题、分类、标签等信息，自动生成 frontmatter 和 markdown 文件。

方式二：手动创建

在 src/content/blog/ 目录下创建 Markdown 文件。目录结构会影响文章的分类：

src/content/blog/
├── life/              # 随笔分类
│   └── 2024-life-review.md
├── note/
│   ├── front-end/     # 笔记 > 前端
│   │   └── react/
│   │       └── React学习小记.md
│   └── algorithm/     # 笔记 > 算法
│       └── 动态规划学习笔记.md
└── tools/             # 工具分类
    └── vscode插件推荐.md

Frontmatter 字段说明

每篇文章开头需要包含 YAML frontmatter：

必填字段：

---
title: 文章标题 # 必填
date: 2024-12-06 # 必填，发布日期
---

常用可选字段：

---
title: 文章标题
date: 2024-12-06
updated: 2024-12-15 # 最近更新时间（可选，存在时会在文章页显示）
description: 文章摘要描述 # 用于 SEO 和列表展示，如不填写会自动使用 AI 摘要或提取正文前 150 字
link: custom-url-slug # 自定义 URL（默认使用文件名）
cover: /img/cover/1.webp # 封面图片
tags: # 标签列表
  - JavaScript
  - React
categories: # 分类（见下方详细说明）
  - 笔记
subtitle: 副标题 # 文章副标题
catalog: true # 是否计入分类页的分类树与篇数（默认 true）
tocNumbering: true # 是否显示目录编号（默认 true）
draft: false # 是否为草稿（默认 false）
sticky: false # 是否置顶（默认 false）
excludeFromSummary: false # 是否排除 AI 摘要和相似度计算（默认 false，系列文章建议设为 true）
math: false # 是否启用数学公式渲染（默认 false，启用后支持 KaTeX）
quiz: false # 是否启用练习题交互（默认 false，启用后支持四种题型）
password: mySecret # 整篇文章加密密码（可选，设置后整篇文章需输入密码才能阅读）
keywords: # 文章关键词（可选）
colophon: # 文章落款（可选，见下方「文章落款」）
  - handwritten
---

关于 description 字段：

文章描述的优先级：手写 description > AI 自动摘要 > Markdown 正文前 150 字

建议为重要文章手写描述，以获得更好的 SEO 效果
如果省略描述，系统会自动使用 AI 生成的摘要（需运行 pnpm generate:summaries）
如果既没有手写描述也没有 AI 摘要，则自动提取文章正文的前 150 个字符

关于 link 字段（自定义 URL）：

⚠️ 重要：link 字段会被自动转换为小写，以保持 URL 的一致性和规范性。

规范化行为：无论你输入 MyPost、myPost 还是 mypost，最终 URL 都会是 /post/mypost
文件名大小写无关：文章文件名可以使用任意大小写（如 MyPost.md），系统会自动处理
AI 摘要和相似度：生成的 summaries.json 和 similarities.json 中的 key 也会统一为小写
最佳实践：建议直接使用小写和连字符（如 my-awesome-post），避免混淆

# ✅ 推荐写法
link: my-awesome-post  # URL: /post/my-awesome-post

# ⚠️ 会被转为小写
link: MyAwesomePost    # URL: /post/myawesomepost（不是 /post/MyAwesomePost）
link: My-Awesome-Post  # URL: /post/my-awesome-post

如果省略 link 字段，系统会使用文件名（同样会转为小写）：

# 文件: src/content/blog/MyPost.md
# 省略 link 字段 → URL: /post/mypost

分类系统

astro-koharu 支持灵活的分类配置：

单层分类：

categories:
  - 工具 # 或者 ['工具']

对应 URL: /categories/tools（根据 categoryMap 映射）

多层嵌套分类：

categories:
  - [笔记, 前端, React]

这会创建层级关系：笔记 → 前端 → React

对应 URL: /categories/note/front-end/react

标签系统

标签是扁平的，不支持层级：

tags:
  - JavaScript
  - TypeScript
  - 学习笔记

所有标签会在 /tags 页面展示，点击标签可查看该标签下的所有文章。

草稿功能

设置 draft: true 将文章标记为草稿：

---
title: 未完成的文章
draft: true
---

行为：

本地开发 (pnpm dev)：草稿可见，文章卡片右上角显示 "DRAFT" 标识
生产构建 (pnpm build)：草稿自动过滤，不会出现在任何列表中

置顶功能

设置 sticky: true 将文章置顶：

---
title: 重要公告
sticky: true
---

行为：

置顶文章显示在首页 "置顶文章" 区域
置顶文章按日期排序（最新的在前）
不影响其他页面（分类、标签、归档）的排序

系列文章

配置了 featuredSeries 的系列（见基本配置），其分类下的文章会：

拥有专属的系列页面（URL 由 slug 决定，如 /weekly、/reading）
不出现在普通文章列表（/posts）中
如果系列设置了 highlightOnHome: true，最新一篇会在首页高亮显示

示例：

---
title: FE Bits Vol.16
categories:
  - 周刊 # 对应某个 featuredSeries 的 categoryName
excludeFromSummary: true # 可选：排除 AI 摘要生成
---

---
title: 《代码大全》读书笔记
categories:
  - 书摘 # 对应另一个 featuredSeries 的 categoryName
---

提示：文章的 categories 字段需要与 featuredSeries 中某个系列的 categoryName 匹配才会被归入该系列。

独立页面

除了博客文章外，你可以在 src/pages/ 目录下创建 .md 文件来添加独立页面（如"关于"、"歌单"等）。这些页面使用 PageLayout.astro 布局，支持完整的 Markdown 增强语法。

创建独立页面：

在 src/pages/ 目录下新建 .md 文件：

---
layout: ../layouts/PageLayout.astro
title: "歌单"
description: "我喜欢的音乐"
coverTitle: "我的歌单"
comments: false
---

页面内容...

Frontmatter 字段：

字段	必填	说明
`layout`	✅	固定为 `../layouts/PageLayout.astro`
`title`	✅	页面标题（用于浏览器标签页）
`description`	❌	页面描述（用于 SEO）
`coverTitle`	❌	封面显示的标题（默认使用 `title`）
`comments`	❌	是否显示评论区（默认 `true`）

添加导航入口：

在 config/site.yaml 的 navigation 中添加对应菜单项：

navigation:
  # ...
  - name: 歌单
    path: /music
    icon: ri:music-2-fill

提示：src/pages/ 下所有 .md 文件会被 Koharu CLI 的备份功能自动覆盖，无需额外配置。

界面功能

主题切换

点击右上角的太阳/月亮图标切换深色/浅色模式。

代码高亮：

浅色模式：github-light
深色模式：github-dark

全站搜索

基于 Pagefind 的静态站点搜索，无需后端服务器。

打开搜索：

点击导航栏搜索图标
快捷键：Cmd/Ctrl + K

特性：

支持中文分词
实时搜索结果
高亮匹配关键词
显示文章摘要和元信息

文章阅读功能

目录导航 (Table of Contents)：

自动提取文章标题（h2-h6）生成目录
使用 CSS 计数器自动为标题添加层级编号（如 1., 1.1., 1.1.1.）
支持通过 frontmatter 的 tocNumbering: false 字段关闭编号显示
点击目录项跳转到对应章节
滚动时自动高亮当前章节
桌面端显示在右侧边栏，移动端折叠

目录编号控制：

---
title: 我的文章
tocNumbering: false # 关闭目录编号（默认为 true）
---

默认情况下，所有文章的目录都会显示层级编号
设置 tocNumbering: false 可以关闭特定文章的编号显示
编号通过 CSS 计数器实现，零运行时开销
同时适用于桌面端侧边栏和移动端下拉目录

阅读进度条：

页面顶部显示阅读进度
实时更新当前阅读位置

标题锚点链接：

每个标题自动生成 ID
悬停标题时显示 # 链接图标
点击可复制带锚点的 URL

系列文章导航：

基于最深层分类自动分组
按发布日期排序
显示文章标题和封面

阅读时间估算：

文章卡片显示预计阅读时间（基于字数计算）。

移动端文章阅读头部：

在移动端（≤992px）浏览文章时，顶部导航栏会显示专为阅读优化的头部：

圆形阅读进度 - 实时显示当前阅读进度的圆形进度条
当前章节标题 - 显示当前所在的 H2/H3 章节标题，切换时带有平滑动画
可展开目录 - 点击标题区域可展开完整的文章目录，快速跳转到任意章节

特性：

滚动时自动更新当前章节
支持 prefers-reduced-motion 减少动画

文章落款

落款用来告诉读者一篇文章是怎么写出来的、读之前要注意什么，比如「手写」「与 AI 合写」「含剧透」「可能已过时」。标记的字典定义在 config/site.yaml 的 colophon 段，文章在 frontmatter 里按 id 引用：

---
title: 我的文章
colophon:
  - ai-cowrite # 直接引用字典里的标记
  - { id: spoiler, note: 含《我推的孩子》第二季剧透 } # note 是本篇自己的补充说明
  - { icon: 'fa6-solid:mug-hot', label: 两杯咖啡 } # 一次性标记，不进字典
---

字典的结构：

config/site.yaml

colophon:
  enabled: true
  groups:
    authorship:
      label: 执笔
      exclusive: true # 互斥组：一篇文章只能选一个
      placement: [meta, seal, card]
    notice:
      label: 阅读提示
      placement: [meta, banner]
  marks:
    handwritten:
      group: authorship
      icon: ri:quill-pen-line
      label: 手写
      description: 每个字都是我自己敲的。
    spoiler:
      group: notice
      icon: ri:eye-off-line
      label: 含剧透
      tone: warn # muted（默认）| accent | warn

默认标记：handwritten（手写）、ai-cowrite（与 AI 合写）、ai-lead（AI 主笔）属于互斥的「执笔」组；spoiler（含剧透）、outdated（可能已过时）属于「阅读提示」组
显示位置（placement）：meta 封面信息行、banner 正文前的提示条、seal 文末落款、card 文章列表卡片。标记上的设置优先于分组
图标：只能使用 ri、fa6-solid、fa6-regular、gg 四套 Iconify 图标，一次性标记也一样
多语言：在 config/i18n-content.yaml 的 <locale>.colophon 下覆盖分组和标记的文案
默认标记（defaults）：文章没有某一组的标记时自动补上，主题默认 defaults: [handwritten]，没写执笔的文章都显示「手写」。不想显示任何标记的文章写 colophon: []
删掉整个 colophon 配置段即可关闭此功能

站内的示例文章：《我推的孩子》第二季观后感（手写 + 含剧透）、Tailwind CSS v4 升级笔记（可能已过时）、一篇 Markdown 在构建时经过了什么（AI 主笔）、容器查询实战（与 AI 合写 + 一次性标记）。

文章操作：复制 Markdown 与在写作室打开

文章页面包屑右侧有一组操作按钮：

复制 Markdown：复制整篇文章的原始 Markdown，包括 frontmatter
下载：把原文保存为 .md 文件
在写作室打开：在写作室里打开这篇文章继续编辑

config/site.yaml

postActions:
  copyMarkdown: true
  downloadMarkdown: true
  openInEditor: everyone # off | dev | everyone

openInEditor 的三个取值：off 不显示；dev 只在本地开发服务器显示；everyone 对所有访客显示，访客打开的是一份浏览器里的草稿副本，不会改动博客本身。这个按钮还要求 editor.enabled: true，写作室没开启时不会出现。

设置了 password 的整篇加密文章，以及正文里含 :::encrypted 局部加密块的文章，都不提供原文，也不显示这些按钮，避免明文和密码随源文件公开。

响应式设计

桌面端：

双栏布局（主内容 + 侧边栏）
固定导航栏
悬浮目录

平板：

自适应布局调整
简化侧边栏

移动端：

单栏布局
抽屉式导航菜单（汉堡菜单）
折叠式目录
触摸优化的交互
文章页专属阅读头部（进度圈 + 当前标题 + 可展开目录）

特色功能

系列文章系统

featuredSeries 支持配置多个系列，每个系列会自动生成独立页面：

专属系列页面 (/{slug})：

每个启用的系列都有独立页面（如 /weekly、/reading）
显示该系列的所有文章
系列头图和介绍
相关链接（GitHub, RSS 等）

首页展示：

设置 highlightOnHome: true 的系列，其最新文章会在首页高亮显示
设置 highlightOnHome: false 的系列不在首页展示
所有系列文章独立于普通文章列表

💡 设计说明：分离关注点

featuredSeries 的设计初衷是将高产出分类从首页分离，避免首页被单一类型文章刷屏。适用场景：

周刊/日记：更新频繁，数量庞大

读书笔记/书摘：独立成系列，方便按系列浏览

任何文章数量较多的分类：当某分类文章数量远超其他分类时

首页行为：

系列文章从首页主列表排除

设置 highlightOnHome: true 时，最新一篇在首页顶部高亮

其余文章通过系列专属页面（如 /weekly）访问

其他页面正常展示：系列文章在归档、分类、标签、搜索等页面仍与普通文章一起显示，仅首页主列表做了分离。

配置示例：

featuredSeries:
  - slug: weekly
    categoryName: 周刊
    highlightOnHome: true # 首页展示最新周刊
    # ...
  - slug: reading
    categoryName: 书摘
    highlightOnHome: false # 不在首页展示
    # ...

归档页面

访问 /archives 查看所有文章的归档视图：

按年份分组
显示每年的文章数量
时间线式展示
包含文章发布日期、标题、分类

友链系统

访问 /friends 查看友情链接页面：

功能：

友链卡片展示
友链申请表单（可自定义）
支持头像、名称、描述、链接

LQIP（低质量图片占位符）

LQIP（Low Quality Image Placeholder）是一种图片加载优化技术，在高清图片加载完成前，先显示一个低质量的占位符，避免页面出现空白或布局抖动。

特性：

🎨 构建时自动提取图片主色调，生成 CSS 渐变占位符
⚡ 零运行时开销 —— 纯 CSS 实现，无需 JavaScript 解码
📦 极小数据体积 —— 每张图片仅需 18 字符存储
🔄 外部图片自动降级为纯色占位符

支持的组件：

文章卡片封面 (PostItemCard)
页面横幅 (Cover)
分类卡片背景 (CategoryCards)
系列封面 (SeriesCover)
侧边栏头像 (HomeInfo)

使用方式：

# 生成 LQIP 数据（处理 public/img/ 下所有图片）
pnpm generate:lqips

生成效果：

LQIP 数据保存在 src/assets/lqips.json，格式如下：

{
  "cover/1.webp": "87a3c4c2dfefbddae9",
  "cover/2.webp": "6e3b38ae7472af7574"
}

每个值是 18 个十六进制字符（3 个颜色），运行时解码为 CSS 渐变：

linear-gradient(135deg, #87a3c4 0%, #c2dfef 50%, #bddae9 100%)

原理：

使用 sharp 将图片缩放到 2×2 像素
提取四象限的平均色（左上、右上、左下、右下）
选取 3 个颜色生成 135 度斜向渐变
存储为紧凑的十六进制字符串

在组件中使用：

---
import { getLqipStyle, getLqipProps } from '@lib/lqip';

// 方式 1：直接获取样式字符串
const style = getLqipStyle('/img/cover/1.webp');
// 返回: "background-image:linear-gradient(...)"

// 方式 2：获取完整的 props（支持外部图片降级）
const lqipProps = getLqipProps(coverUrl);
// 本地图片返回: { style: "background-image:..." }
// 外部图片返回: { class: "lqip-fallback" }
---

<div style={style}>
  <img src="/img/cover/1.webp" />
</div>

注意事项：

生成的 src/assets/lqips.json 需要提交到 git
添加新图片后需要重新运行 pnpm generate:lqips
外部图片（http/https 开头）会自动使用纯色占位符降级

模型	大小	维度	优势
`Snowflake/snowflake-arctic-embed-m-v2.0`	~90MB	768	质量高，中英文均衡
`sentence-transformers/all-MiniLM-L6-v2`	~23MB	384	轻量快速
`BAAI/bge-small-zh-v1.5`	~95MB	512	中文专用

AI 自动摘要

基于 transformers.js 的智能摘要生成系统，使用先进的 AI 模型为文章自动生成高质量摘要。

与相关文章推荐的关系：

AI 摘要功能与相关文章推荐功能相辅相成：

相似度计算需要读取文章全文，计算成本较高（约 3-5 分钟）
AI 摘要可以在不读取全文的情况下提供优质描述，同时生成的摘要也能帮助改善相似度计算的效果
两者共享相同的模型缓存机制，节省存储空间

特性：

🤖 基于先进的文本生成模型（Xenova/LaMini-Flan-T5-783M）
📝 自动为缺少描述的文章生成摘要
✨ 文章详情页支持打字机动画展示，增强阅读体验
🎯 智能 fallback：优先使用手写 description，无描述时自动使用 AI 摘要
🚀 构建时预生成，运行时零开销
♿ 支持无障碍访问和 prefers-reduced-motion

使用方式：

# 生成 AI 摘要（本地运行，首次会下载模型，约需 5-10 分钟）
pnpm generate:summaries

# 生成的文件要提交到 git，然后可以在 Vercel 等平台直接使用

生成效果：

AI 摘要会保存在 src/assets/summaries.json 文件中，格式如下：

{
  "article-slug": {
    "title": "文章标题",
    "summary": "AI 生成的摘要内容..."
  }
}

在哪里使用：

文章详情页：面包屑导航下方显示可折叠的 AI 摘要卡片
- 默认收起状态，点击"展开"按钮触发
- 展开后以打字机动画逐字显示摘要内容
- 打字机动画仅播放一次，支持 prefers-reduced-motion 用户偏好
文章卡片：作为描述的 fallback
- 优先级：手写 description > AI 摘要 > Markdown 前 150 字
- 在文章列表、首页、分类页等处自动使用

模型选择：

默认使用 Xenova/LaMini-Flan-T5-783M 模型：

模型大小：约 300MB（首次运行会自动下载到 .cache/transformers 目录）
生成质量：高质量的中英文摘要生成
生成时间：约 5-10 分钟（169 篇文章）

如需更换模型，编辑 src/scripts/generateSummaries.ts 中的 MODEL_NAME：

const MODEL_NAME = "Xenova/LaMini-Flan-T5-783M";
// 可选替代方案：
// const MODEL_NAME = 'Xenova/distilbart-cnn-6-6'; // 更快，英文效果好
// const MODEL_NAME = 'facebook/bart-large-cnn';   // 质量更高，但速度较慢

配置提示词：

可以自定义生成摘要的提示词，编辑 src/scripts/generateSummaries.ts 中的 PROMPT_TEMPLATE：

const PROMPT_TEMPLATE = (title: string, content: string) =>
  `请为以下文章生成一段简洁的摘要（100-150字）：\n\n标题：${title}\n\n内容：${content}`;

注意事项：

需要本地运行生成脚本（Vercel 等平台无法运行大模型）
生成的 src/assets/summaries.json 需要提交到 git
如果没有生成摘要文件，会自动 fallback 到 Markdown 文本提取
模型文件会缓存在 .cache/transformers 目录（已添加到 .gitignore）
首次运行需要下载模型，建议在网络良好的环境下进行

最佳实践：

与相似度计算配合使用：

# 先生成摘要
pnpm generate:summaries
# 再计算相似度（可以使用摘要代替全文，提升速度）
pnpm generate:similarities

选择性生成摘要：为了节省时间，脚本会跳过已有 description 的文章
提交到版本控制：将生成的 JSON 文件提交到 git，避免在 CI/CD 环境重复生成

圣诞特辑

节日限定的圣诞氛围特效系统，包含多种可独立开关的视觉效果，为博客增添节日气氛。

特性：

雪花飘落 —— Canvas 实现的雪花动画，分前景和背景两层，支持视差效果
圣诞配色 —— 红绿金主题色替换默认粉蓝配色，支持深色/浅色模式
圣诞帽装饰 —— 侧边栏头像上的圣诞帽
圣诞灯串 —— Header 顶部的装饰灯串动画
圣诞饰品切换 —— 导航栏的装饰饰品
运行时开关 —— 右下角浮动按钮可随时切换特效，设置自动保存

配置方式：

编辑 config/site.yaml 中的 christmas 配置：

christmas:
  enabled: true # 总开关
  features:
    snowfall: true # 雪花飘落
    christmasColorScheme: true # 圣诞配色
    christmasCoverDecoration: true # 灯串装饰
    christmasHat: true # 圣诞帽
    readingTimeSnow: true # 阅读时间雪花特效
  snowfall:
    speed: 0.5 # 飘落速度（默认 0.5）
    intensity: 0.7 # 桌面端雪花密度（0-1）
    mobileIntensity: 0.4 # 移动端雪花密度（0-1）
    maxLayers: 6 # 最大雪花层数
    maxIterations: 8 # 最大迭代次数
    mobileMaxLayers: 4 # 移动端最大层数
    mobileMaxIterations: 6 # 移动端最大迭代次数

用户控制：

页面右下角悬浮按钮（雪花图标）可切换圣诞特效开关
用户偏好自动保存到 localStorage，跨会话保持
支持 prefers-reduced-motion 偏好，自动禁用动画

技术实现：

雪花使用 Canvas 2D 渲染，分层实现视差效果
配色通过 CSS 变量覆盖，零运行时开销
状态管理使用 nanostores，支持跨组件同步
完全响应式，移动端自动降低雪花密度

关闭圣诞特效：

设置 christmasConfig.enabled = false 即可完全关闭所有圣诞特效。

站点公告系统

无后端的站点公告系统，支持在配置文件中管理公告，首次访问自动弹出，关闭后可通过页脚入口再次查看。

特性：

无后端 —— 公告内容写在配置文件，无需数据库
Toast 通知 —— 右下角浮动通知，支持多条堆叠显示
多条公告 —— 支持配置多条公告，按优先级排序
时间控制 —— 支持设置公告的开始/结束日期，自动控制显示
自定义颜色 —— 每条公告可设置独立颜色，覆盖默认类型颜色
时间线弹窗 —— 公告列表采用时间线样式，带渐变连接线
Hover 已读 —— 悬停 Toast 1 秒后自动标记已读
已读追踪 —— localStorage 记录已读状态，返回访问不重复弹出
再次查看 —— 页脚入口可随时查看所有公告，带未读红点提示

配置方式：

编辑 config/site.yaml 添加公告：

announcements:
  - id: welcome-2026 # 唯一标识
    title: 2026 年新年快乐! # 公告标题
    content: 新年快乐! 感谢大家一直以来的支持~ # 公告内容
    type: info # 类型：info | warning | success | important
    priority: 300 # 优先级（越高越先显示）
    color: "#ED788C" # 自定义颜色（可选，覆盖 type 默认色）
    publishDate: "2026-01-01" # 显示日期（可选，用于时间线展示）
    startDate: "2025-12-31T00:00:00+08:00" # 开始日期（可选）
    endDate: "2026-01-15T23:59:59+08:00" # 结束日期（可选）
  - id: site-update-01
    title: 站点更新公告
    content: 新增站点公告系统，现在支持多条公告同时显示！
    type: info
    priority: 500
    color: "#6366F1"
    publishDate: "2025-01-02"

如果需要添加链接（可选）：

announcements:
  - id: example-with-link
    title: 示例公告
    content: 公告内容
    type: info
    link:
      url: https://example.com
      text: 了解更多
      external: true

公告类型样式：

类型	说明	默认颜色
`info`	信息通知	蓝色 (#3b82f6)
`warning`	警告提示	黄色 (#eab308)
`success`	成功消息	绿色 (#22c55e)
`important`	重要公告	红色 (#ef4444)

设置 color 字段可覆盖上述默认颜色

交互流程：

首次访问：0.5 秒后自动弹出未读公告 Toast（多条堆叠显示）
Hover 已读：悬停在 Toast 上 1 秒后自动标记已读
手动关闭：点击 Dismiss 关闭 Toast
点击"View all"：关闭所有 Toast，打开时间线弹窗
时间线弹窗：点击公告卡片标记已读，显示发布日期和渐变连接线
页脚入口：随时可点击查看所有公告，未读时显示红点
返回访问：只显示真正未读的公告

注意事项：

公告 id 必须唯一，用于追踪已读状态
省略 startDate 表示立即生效，省略 endDate 表示永不过期
publishDate 用于时间线弹窗中的日期显示，省略时使用 startDate
过期公告建议从配置中删除，保持配置简洁
已读状态存储在 localStorage，key 为 announcement-read-ids:v1（旧 key 会自动迁移）

Markdown 增强

语法支持：

GitHub Flavored Markdown (GFM)
- 表格
- 任务列表
- 删除线
- 自动链接

Mermaid 图表：

支持在 Markdown 中使用 Mermaid 语法绘制流程图、时序图、架构图等。

```mermaid
flowchart LR
    A[构建时脚本] --> B[JSON 数据文件] --> C[运行时工具函数]
```

flowchart LR
    A[构建时脚本] --> B[JSON 数据文件] --> C[运行时工具函数]

支持的图表类型：

flowchart / graph - 流程图
sequenceDiagram - 时序图
classDiagram - 类图
stateDiagram - 状态图
erDiagram - ER 图
gantt - 甘特图
pie - 饼图
mindmap - 思维导图

图表会自动跟随深色/浅色主题切换。更多语法参考 Mermaid 官方文档。

Infographic 信息图：

支持使用 @antv/infographic 在 Markdown 中绘制精美的信息图表，适合展示流程、对比、层级、统计等数据。

使用方式：在代码块中使用 infographic 标记，第一行指定模板名称，然后使用类似 YAML 的语法定义数据：

```infographic
infographic list-grid-badge-card
data
  title 技术栈
  desc 我的常用技术栈
  items
    - label TypeScript
      desc 类型安全的 JavaScript
      icon mdi/language-typescript
    - label React
      desc 用户界面库
      icon mdi/react
    - label Astro
      desc 现代化静态站点生成器
      icon mdi/rocket-launch
```

infographic list-grid-badge-card
data
  title 技术栈
  desc 我的常用技术栈
  items
    - label TypeScript
      desc 类型安全的 JavaScript
      icon mdi/language-typescript
    - label React
      desc 用户界面库
      icon mdi/react
    - label Astro
      desc 现代化静态站点生成器
      icon mdi/rocket-launch

可用模板类型：

列表类 (list-*)：展示信息列表
- list-grid-badge-card - 卡片网格布局
- list-grid-candy-card-lite - 糖果风格卡片
- list-row-horizontal-icon-arrow - 水平图标箭头列表
流程/顺序类 (sequence-*)：展示步骤、流程或阶段
- sequence-zigzag-steps-underline-text - 之字形步骤
- sequence-circular-simple - 圆形流程
- sequence-roadmap-vertical-simple - 垂直路线图
- sequence-pyramid-simple - 金字塔结构
对比类 (compare-*)：二元或多元对比
- compare-binary-horizontal-simple-fold - 水平二元对比
- compare-swot - SWOT 分析
- compare-hierarchy-left-right-circle-node-pill-badge - 层级左右对比
层级类 (hierarchy-*)：展示树形结构
- hierarchy-tree-tech-style-capsule-item - 科技风格树形图
- hierarchy-tree-curved-line-rounded-rect-node - 曲线连接树形图
图表类 (chart-*)：数据可视化
- chart-column-simple - 柱状图
- chart-bar-plain-text - 条形图
- chart-pie-plain-text - 饼图
- chart-line-plain-text - 折线图
其他
- quadrant-* - 象限分析图
- relation-* - 关系图

数据字段说明：

title - 标题（可选）
desc - 描述文本（可选）
items - 条目数组，每个条目可包含：
- label - 主标签文本
- value - 数值（用于图表类模板）
- desc - 描述文本
- icon - 图标名称（格式：mdi/icon-name）
- children - 子条目（用于层级结构）

主题定制：

可以在数据后添加 theme 块自定义颜色：

```infographic
infographic sequence-pyramid-simple
data
  items
    - label 基础层
    - label 中间层
    - label 顶层
theme
  palette
    - #3b82f6
    - #8b5cf6
    - #f97316
```

信息图会自动跟随深色/浅色主题切换，并使用项目的寒蝉全圆体字体渲染。更多模板和语法参考 Infographic 官方文档。

代码高亮：

基于 Shiki
支持双主题（深色/浅色）
支持语言标注
行号显示

示例：

```javascript
function hello() {
  console.log("Hello, world!");
}
```

function hello() {
  console.log("Hello, world!");
}

标题自动链接：

所有标题自动生成可点击的锚点链接。

链接自动嵌入：

独行的特殊链接会自动转换为嵌入组件：

Twitter/X 链接：自动嵌入 Tweet 组件
CodePen 链接：自动嵌入交互式 CodePen 演示
其他链接：显示 OG 预览卡片（包含标题、描述、图片等）

示例：

<!-- 独行链接会被嵌入 -->

https://x.com/vercel_dev/status/1997059920936775706

https://codepen.io/botteu/pen/YPKBrJX/

https://github.com/vercel/react-tweet

反爬严格，获取不到元信息的链接

https://zhuanlan.zhihu.com/p/1900483903984243480

<!-- 段落中的链接保持不变 -->

这是一个 [普通链接](https://example.com)，不会被嵌入。

See the Pen YPKBrJX by botteu (@botteu) on CodePen.

github.com

GitHub - vercel/react-tweet: Embed tweets in your React application.

Embed tweets in your React application. Contribute to vercel/react-tweet development by creating an account on GitHub.

https://github.com/vercel/react-tweet

反爬严格，获取不到元信息的链接

https://zhuanlan.zhihu.com/p/1900483903984243480

zhuanlan.zhihu.com

这是一个普通链接，不会被嵌入。

Shoka 兼容 Markdown 语法：

astro-koharu 从 Hexo Shoka 主题迁移了一套丰富的 Markdown 扩展语法，所有功能均可通过 config/site.yaml 的 content 配置项独立开关。

文字特效（enableShokaEffects）：

支持多种行内文字装饰效果：

语法	效果	说明
`++文字++`	下划线	`<ins>` 标签
`++文字++{.wavy}`	波浪下划线	支持 `.wavy` 修饰符
`++文字++{.dot}`	着重点	支持 `.dot` 修饰符
`++文字++{.primary}`	彩色下划线	支持 `.primary` `.success` `.warning` `.danger` `.info`
`==文字==`	高亮	`<mark>` 标签
`~文字~`	下标	`<sub>` 标签，如 H₂O
`^文字^`	上标	`<sup>` 标签，如 E=mc²

示例效果：

这是下划线文字波浪下划线着重点标记

主色调成功警告危险信息

这是高亮文字

H₂O 是水的化学式，E = mc² 是质能方程

颜色文字与特殊样式（enableShokaAttrs）：

使用 文字 语法为文字添加颜色和样式：

[红色]{.red} [粉色]{.pink} [橙色]{.orange} [黄色]{.yellow}
[绿色]{.green} [水色]{.aqua} [蓝色]{.blue} [紫色]{.purple} [灰色]{.grey}

[这段文字会有彩虹渐变效果]{.rainbow}

[Ctrl]{.kbd} + [C]{.kbd} 复制，[Ctrl]{.kbd} + [V]{.kbd} 粘贴

[默认]{.label .default} [主要]{.label .primary} [信息]{.label .info}
[成功]{.label .success} [警告]{.label .warning} [危险]{.label .danger}

示例效果：

红色粉色橙色黄色绿色水色蓝色紫色灰色

这段文字会有彩虹渐变效果

Ctrl + C 复制，Ctrl + V 粘贴

默认主要信息成功警告危险

隐藏文字 / Spoiler（enableShokaSpoiler）：

这里有一段!!隐藏文字，点击显示!!

这里有一段!!模糊文字，鼠标悬停显示!!{.blur}

示例效果：

这里有一段隐藏文字，点击显示

这里有一段模糊文字，鼠标悬停显示

默认模式：点击后粒子消散动画揭示文字（基于 spoilerjs Web Component）
.blur 模式：鼠标悬停时模糊消失

注音标注 / Ruby（enableShokaRuby）：

为 CJK 文字添加注音，适用于日语假名、汉语拼音等：

{漢字^かんじ}的注音示例

{取り返す^とりかえす}是日语中"取回"的意思

示例效果：

漢字(かんじ)的注音示例。取り返す(とりかえす)是日语中"取回"的意思。

渲染为 HTML <ruby> 标签，浏览器原生支持。

提醒块 / Note Blocks（enableShokaContainers）：

使用 ::: 语法创建不同样式的提醒块：

:::default
这是默认提醒块
:::

:::primary
这是主要提醒块，用于重要提示
:::

:::info
这是信息提醒块
:::

:::success
这是成功提醒块
:::

:::warning
这是警告提醒块
:::

:::danger
这是危险提醒块
:::

:::info no-icon
这是没有图标的信息块
:::

示例效果：

这是信息提醒块，用于提供额外信息

这是警告提醒块，请注意

这是危险提醒块，务必谨慎

支持的样式：default、primary、info、success、warning、danger。添加 no-icon 可隐藏图标。提醒块内部支持嵌套 Markdown 语法。

折叠块 / Collapse（enableShokaContainers）：

使用 +++ 语法创建可折叠内容（渲染为 <details> + <summary>）：

+++primary 点击展开详细内容
折叠的内容，支持 **Markdown** 格式化。

- 列表项 1
- 列表项 2
+++

+++warning 注意事项
需要注意的内容
+++

+++danger 危险操作
请确保你知道自己在做什么！
+++

示例效果：

点击展开详细内容

折叠的内容，支持 Markdown 格式化。

列表项 1
列表项 2

注意事项

需要注意的内容

支持的样式：primary、info、success、warning、danger。

标签卡 / Tabs（enableShokaContainers）：

使用 ;;; 语法创建标签页切换，同一组 ID 的标签卡会自动组合：

;;;mygroup JavaScript
```js
console.log('Hello, World!');
```
;;;

;;;mygroup Python
```python
print('Hello, World!')
```
;;;

;;;mygroup Rust
```rust
fn main() {
    println!("Hello, World!");
}
```
;;;

示例效果：

JavaScript Python Rust

console.log('Hello, World!');

print('Hello, World!')

fn main() {
    println!("Hello, World!");
}

;;;groupId 标签名 定义一个标签页，同一 groupId 的标签自动组合
第一个标签默认激活
标签内支持任意 Markdown 内容

友链卡片（enableShokaHexoTags）：

使用 {% links %} 标签在文章中插入友链卡片网格：

{% links %}
- site: 博客名称
  url: https://example.com
  owner: 站长昵称
  desc: 站点描述
  image: https://example.com/avatar.png
  color: '#ed788b'
- site: 另一个博客
  url: https://example2.com
  owner: Alice
  desc: 一个热爱技术的博客
  image: https://api.dicebear.com/7.x/avataaars/svg?seed=Alice
  color: '#BEDCFF'
{% endlinks %}

示例效果：

卡片数据使用 YAML 格式，支持 site、url、owner、desc、image、color 字段。

音频播放器（enableShokaHexoTags）：

使用 {% media audio %} 标签嵌入音频播放器，支持网易云音乐、QQ 音乐等平台（通过 Meting API 解析）。

默认使用 https://163.hyc.moe/ 作为 Meting API，可在 config/site.yaml 的 bgm.metingApi 中自定义，推荐自部署以获得更稳定的服务。

{% media audio %}
- name: 歌曲名称
  url: https://music.163.com/#/song?id=3339210292
{% endmedia %}

示例效果：

支持歌单模式，可配置多个分组：

{% media audio %}
- title: 歌单名称 1
  list:
    - https://music.163.com/#/playlist?id=8676645748
- title: 歌单名称 2
  list:
    - https://music.163.com/#/playlist?id=17606384886
{% endmedia %}

视频播放器（enableShokaHexoTags）：

使用 {% media video %} 标签嵌入视频播放器：

{% media video %}
- name: 视频 1
  url: https://example.com/video1.mp4
- name: 视频 2
  url: https://example.com/video2.mp4
{% endmedia %}

多个视频时自动显示播放列表。

练习题系统（enableQuiz）：

支持四种交互式题型，适合教程和学习笔记。需在文章 frontmatter 中设置 quiz: true。

单选题：

- 下列哪个是 JavaScript 的基本数据类型？{.quiz}
  - Object{.options}
  - Array{.options}
  - Symbol{.correct}
  - Function{.options}

> 解析：Symbol 是 ES6 引入的基本数据类型。

示例效果：

下列哪个是 JavaScript 的基本数据类型？
- Object
- Array
- Symbol
- Function

解析：Symbol 是 ES6 引入的基本数据类型，而 Object、Array、Function 都是引用类型。

选项标记为正确答案，{.options} 为干扰项

多选题：

- 以下哪些是 CSS 布局方式？{.quiz .multi}
  - Flexbox{.correct}
  - jQuery{.options}
  - Grid{.correct}
  - Float{.correct}

> 解析：Flexbox、Grid 和 Float 都是 CSS 布局方式。

示例效果：

以下哪些是 CSS 布局方式？
- Flexbox
- jQuery
- Grid
- Float

解析：Flexbox、Grid 和 Float 都是 CSS 布局方式。jQuery 是一个 JavaScript 库。

添加 .multi 标记启用多选模式

判断题：

- `const` 声明的变量不能重新赋值，但可以修改其属性。{.quiz .true}

> 解析：`const` 只保证变量绑定不可变。

- HTML 是一种编程语言。{.quiz}

> 解析：HTML 是标记语言，不是编程语言。

示例效果：

const 声明的变量不能重新赋值，但可以修改其属性。

解析：const 只保证变量绑定不可变，如果变量指向一个对象，其属性仍然可以修改。

HTML 是一种编程语言。

解析：HTML（超文本标记语言）是一种标记语言，不是编程语言。

添加 .true 表示陈述正确，不添加 .true 则表示错误

填空题：

- CSS 中，[Flexbox]{.gap} 适合一维布局，[Grid]{.gap} 适合二维布局。{.quiz .fill}

> 常见错误：[Float]{.mistake}

示例效果：

CSS 中，Flexbox 适合一维布局，Grid 适合二维布局。

常见错误：Float

[答案] 标记正确答案（支持多个空）
[错误答案] 标记常见错误（首次答错时提示）
> 引用块内容为解析说明

数学公式（enableMath）：

基于 KaTeX 渲染数学公式。需在文章 frontmatter 中设置 math: true：

行内公式：$E = mc^2$

块级公式：

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

示例效果：

行内公式：E=mc2E = mc^2E=mc2

块级公式：

∑n=1∞1n2=π26\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}n=1∑∞n21=6π2

代码块增强（enableCodeMeta）：

代码块支持额外的元数据标注：

```js title="hello.js" url="https://example.com" linkText="查看源码" mark:1,3
const greeting = 'Hello';
const name = 'World';
console.log(`${greeting}, ${name}!`);
```

```bash command:("$":1-3)
npm install astro
npm run dev
npm run build
```

元数据	说明
`title="文件名"`	显示代码块标题
`url="链接"`	添加外部源码链接
`linkText="文字"`	自定义链接文字（默认为 URL）
`mark:1,3`	高亮指定行
`command:("$":1-3)`	标记 shell 命令行（显示 `$` 前缀）

示例效果：

hello.js查看源码

const greeting = 'Hello';
const name = 'World';
console.log(`${greeting}, ${name}!`);

npm install astro
npm run dev
npm run build

Shoka 功能配置总览：

所有 Shoka 兼容功能均可在 config/site.yaml 的 content 部分独立开关：

content:
  # Shoka 兼容功能（默认全部启用，设为 false 可关闭）
  enableShokaContainers: true   # :::提醒块 ;;;标签卡 +++折叠块
  enableShokaAttrs: true        # text 属性语法
  enableShokaEffects: true      # ++下划线++ ==高亮== ~下标~ ^上标^
  enableShokaSpoiler: true      # !!隐藏文字!!
  enableShokaRuby: true         # {文字^注音} 注音标注
  enableShokaHexoTags: true     # {% links %} {% media %} Hexo 标签
  enableMath: true              # $数学公式$ KaTeX 渲染
  enableCodeMeta: true          # 代码块增强 (title, mark, command)
  enableQuiz: true              # 练习题交互功能
  enableEncryptedBlock: true    # :::encrypted{password="..."} 加密内容块

提示：完整的语法演示可参考 Shoka 主题 Markdown 语法演示文章。

内容加密（enableEncryptedBlock）：

博客支持两种加密方式，满足不同的内容保护需求：

1. 加密块 —— 文章局部加密

在文章中使用 :::encrypted{password="..."} 语法包裹需要加密的内容：

这部分内容公开可见。

:::encrypted{password="demo"}
这段内容需要输入密码 "demo" 才能查看。

支持完整的 Markdown 语法，包括代码块、列表、图片等。
:::

这部分也是公开的。

加密块适合在一篇文章中部分隐藏敏感内容（如答案、剧透、私密笔记），其余内容正常展示。需要在 config/site.yaml 中启用 enableEncryptedBlock: true。

2. 加密文章 —— 整篇文章加密

在文章的 frontmatter 中添加 password 字段即可加密整篇文章：

---
title: 我的私密文章
date: 2026-01-01
password: mySecretPassword
categories:
  - 笔记
---

这里的所有内容都会被加密...

加密文章会显示一个全屏的解锁界面，输入正确密码后才能查看内容。解锁后代码高亮、目录导航、Mermaid 图表等增强功能会自动重新初始化。

安全模型说明：

加密功能使用 AES-256-GCM 算法，安全模型如下：

构建时加密：密码仅在 pnpm build 时用于加密，生成的 HTML 中不包含密码明文
客户端解密：读者在浏览器中输入密码后，通过 Web Crypto API 在本地解密，密码不会发送到任何服务器
密钥派生：使用 PBKDF2（100,000 次迭代）从密码派生加密密钥，提高暴力破解成本
搜索排除：加密内容自动添加 data-pagefind-ignore，不会被 Pagefind 搜索索引

⚠️ 注意：此加密设计的主要目的是防止搜索引擎和爬虫索引加密内容，而非抵御针对性攻击。密文和盐值嵌入在公开的 HTML 中，理论上可被离线暴力破解。请使用强密码，不要用于保护高度敏感的信息。

加密文章的特殊行为：

方面	行为
RSS 订阅	标题前加 🔒 前缀，内容替换为"此文章已加密"提示
SEO / meta	description 使用 frontmatter 中的 `description`（若未设置则显示通用加密提示）
搜索索引	加密内容不会被 Pagefind 索引
目录导航	解锁前不显示，解锁后自动重建
AI 摘要	基于加密前的原文生成（构建时可访问明文）

其他增强：

自动目录生成
阅读时间计算
外部链接自动添加 target="_blank"

多语言支持（i18n）

博客内置完整的国际化支持，可轻松添加多种语言。

基本配置

在 config/site.yaml 的 i18n 部分配置支持的语言：

i18n:
  defaultLocale: zh        # 默认语言（URL 无前缀）
  locales:
    - code: zh
      label: 中文
    - code: en
      label: English
      # enabled: false     # 设为 false 可暂时禁用（保留内容但不生成路由）

配置多语言后：

默认语言的页面 URL 不带前缀（如 /post/hello）
其他语言自动加前缀（如 /en/post/hello）
导航栏（桌面端）和移动端抽屉中自动显示语言切换器
每个语言各自生成独立的 RSS 订阅源（如 /en/rss.xml）
HTML <head> 中自动输出 hreflang 标签，有利于 SEO

如果只配置了一种语言，i18n 功能不会激活，不会产生额外的路由或 UI 元素。

翻译体系

i18n 系统采用两层翻译架构：

1. UI 字符串（TypeScript）

界面上的按钮文字、提示信息等 UI 文本通过 TypeScript 翻译字典管理，位于 src/i18n/translations/ 目录：

zh.ts：默认语言（中文），包含所有翻译 key（约 170 个），是唯一的 source-of-truth
en.ts：英文翻译，只需提供需要覆盖的 key，未提供的自动回退到中文

翻译字符串支持 {param} 占位符插值：

// zh.ts
'post.totalPosts': '共 {count} 篇文章',

// en.ts
'post.totalPosts': '{count} posts',

2. 内容字符串（YAML）

分类名、系列名、精选分类描述等内容级文本通过 config/i18n-content.yaml 管理。默认语言的值直接读取 config/site.yaml，此文件仅存放非默认语言的翻译：

en:
  categories:
    life: Life
    note: Notes
    tools: Tools
  series:
    weekly:
      label: My Weekly
      fullName: My Tech Weekly
  featuredCategories:
    life:
      label: Life
      description: Life journals and essays

其中 categories 的 key 是分类的 URL slug（对应 config/site.yaml 中 categoryMap 的值），series 的 key 是系列的 slug。

添加翻译文章

将翻译文章放在 src/content/blog/<locale>/ 目录下，保持与默认语言相同的路径结构：

src/content/blog/
├── life/hello-world.md            # 默认语言 (zh)
├── tools/getting-started.md       # 默认语言 (zh)
├── en/life/hello-world.md         # 英文翻译
└── en/tools/getting-started.md    # 英文翻译

回退机制：当用户切换到非默认语言时，系统会显示该语言已有的翻译文章，对于尚未翻译的文章则自动回退显示默认语言内容，并在文章顶部标注提示信息。

添加新语言

以添加日语（ja）为例：

在 config/site.yaml 的 i18n.locales 中添加新语言：

i18n:
  locales:
    - code: zh
      label: 中文
    - code: en
      label: English
    - code: ja
      label: 日本語

创建 UI 翻译文件 src/i18n/translations/ja.ts：

import type { UIStrings } from '../types';

export const uiStrings: UIStrings = {
  'nav.home': 'ホーム',
  'common.search': '検索',
  // ... 按需翻译，未提供的 key 自动回退到中文
};

在 src/i18n/translations/index.ts 中注册：

import { uiStrings as ja } from './ja';

export const translations: Record<string, DefaultUIStrings | UIStrings> = {
  zh,
  en,
  ja, // 新增
};

4.（可选）在 config/i18n-content.yaml 中添加日语的内容翻译。

5.（可选）在 src/content/blog/ja/ 目录下添加日语文章。

在组件中使用翻译

Astro 组件（.astro 文件）中：

---
import { getLocaleFromUrl, t, localizedPath } from '@/i18n';

const locale = getLocaleFromUrl(Astro.url.pathname);
---

<h1>{t(locale, 'post.totalPosts', { count: 10 })}</h1>
<a href={localizedPath('/archives', locale)}>归档</a>

React 组件（.tsx 文件）中：

import { useTranslation } from '@hooks/useTranslation';

function MyComponent() {
  const { t, locale } = useTranslation();
  return <button>{t('common.search')}</button>;
}

RSS 订阅

访问 /rss.xml 获取 RSS feed。启用多语言时，每个语言有独立的 RSS 源（如 /en/rss.xml）。

包含内容：

最新文章列表
文章摘要
发布日期
文章链接

数据统计

集成 Umami 分析（可选）。

在 config/site.yaml 中配置：

analytics:
  umami:
    enabled: true
    id: your-umami-id
    endpoint: https://stats.example.com
    # 页面访问量展示（可选）
    statistics_display:
      token: your-umami-share-token  # Umami 分享链接令牌（只读，可安全暴露到客户端）
      article_page_views: true        # 在文章卡片和详情页显示访问量
      footer_site_stats: true         # 在页脚显示全站访问量

获取 Umami Share Token

statistics_display.token 是 Umami 的分享链接令牌，用于通过公开 API 读取统计数据（只读权限，可安全暴露到前端）。获取步骤：

登录你的 Umami 后台
进入 Settings → Websites，选择你的站点
点击右侧 Share URL 按钮（分享图标）
开启 Enable share URL 开关，此时会生成一个分享链接，形如：https://stats.example.com/share/xxxxxxxx/site-name
链接中 /share/ 后面的那段字符串（如 xxxxxxxx）即为 share token，将其填入 statistics_display.token 即可

注：Share token 仅提供只读权限，无法通过它修改任何数据或配置，因此可以安全地暴露到客户端代码中。

开发指南

目录结构

astro-koharu/
├── src/
│   ├── components/      # 组件
│   │   ├── common/      # 通用组件（错误边界等）
│   │   ├── ui/          # UI 组件（按钮、卡片等）
│   │   ├── layout/      # 布局组件（头部、侧边栏等）
│   │   ├── post/        # 文章相关组件
│   │   ├── category/    # 分类组件
│   │   └── theme/       # 主题切换
│   ├── content/
│   │   └── blog/        # 博客文章（Markdown）
│   │       └── en/      # 英文翻译文章（按 locale 子目录组织）
│   ├── i18n/            # 国际化模块
│   │   ├── config.ts    # locale 配置（读取 site.yaml）
│   │   ├── utils.ts     # 翻译函数、URL 工具
│   │   ├── content.ts   # 内容翻译加载（读取 i18n-content.yaml）
│   │   └── translations/  # UI 翻译字典（zh.ts, en.ts）
│   ├── layouts/         # 页面布局模板
│   ├── pages/           # 页面路由
│   │   └── [lang]/      # 非默认语言的镜像路由
│   ├── lib/             # 工具函数
│   ├── hooks/           # React hooks
│   ├── constants/       # 常量配置
│   ├── store/           # 全局状态（nanostores）
│   ├── scripts/         # 构建脚本
│   ├── styles/          # 全局样式
│   └── types/           # TypeScript 类型定义
├── public/              # 静态资源
│   └── img/             # 图片资源
├── config/
│   ├── site.yaml        # 站点配置（含分类映射、i18n 配置）
│   └── i18n-content.yaml  # 内容级翻译（分类名、系列名等）
├── astro.config.mjs     # Astro 配置
├── tailwind.config.mjs  # Tailwind 配置
└── tsconfig.json        # TypeScript 配置

路径别名

项目配置了以下路径别名（在 tsconfig.json 中）：

import { something } from "@/xxx"; // → src/xxx
import Component from "@components/xxx"; // → src/components/xxx
import { util } from "@lib/xxx"; // → src/lib/xxx
import config from "@constants/xxx"; // → src/constants/xxx
// ... 更多别名见 tsconfig.json

常用命令

# 开发
pnpm dev              # 启动开发服务器（默认 localhost:4321）

# 构建
pnpm build            # 构建生产版本
pnpm preview          # 预览生产构建

# 代码质量
pnpm lint             # 运行 ESLint
pnpm lint-md          # 检查 Markdown 文件
pnpm lint-md:fix      # 自动修复 Markdown 问题
pnpm knip             # 查找未使用的文件和依赖

# Koharu CLI
pnpm koharu                   # 交互式主菜单
pnpm koharu new               # 新建内容（交互式选择）
pnpm koharu new post          # 新建博客文章
pnpm koharu new friend        # 新建友情链接
pnpm koharu backup            # 备份博客内容（--full 完整备份）
pnpm koharu restore           # 还原备份（--latest, --dry-run）
pnpm koharu migrate           # 迁移旧内容链接（--dry-run）
pnpm koharu update            # 更新主题（--check, --clean, --rebase, --tag, --dry-run 等）
pnpm koharu generate          # 生成内容资产（交互式选择）
pnpm koharu generate lqips    # 生成 LQIP 占位符
pnpm koharu generate similarities  # 生成相似度向量
pnpm koharu generate summaries     # 生成 AI 摘要
pnpm koharu generate all      # 生成全部资产
pnpm koharu clean             # 清理旧备份（--keep N）
pnpm koharu list              # 查看所有备份

# 工具
pnpm change           # 生成 CHANGELOG.md（基于 git-cliff）

Docker 部署

astro-koharu 支持通过 Docker 进行容器化部署，适合需要自托管的场景。

快速开始：

# 1. 编辑 config/site.yaml，配置 comment.remark42 和 analytics.umami 部分

# 2. 构建并启动
docker compose -f docker/docker-compose.yml up -d --build

# 3. 访问
open http://localhost:4321

目录结构：

docker/
├── Dockerfile           # 多阶段构建配置
├── docker-compose.yml   # 编排配置
├── nginx/
│   └── default.conf     # Nginx 静态服务配置
└── rebuild.sh           # 便捷重建脚本

关于生成脚本：

以下脚本需要在本地运行，不能在 Docker 构建时执行：

脚本	原因
`pnpm generate:lqips`	使用 `sharp` 原生模块处理图片
`pnpm generate:similarities`	需下载 500MB+ 的 ML 模型
`pnpm generate:summaries`	需连接本地 LLM 服务器

推荐工作流：

# 本地开发：添加新图片或文章后
pnpm generate:all

# 提交生成的数据文件
git add src/assets/*.json
git commit -m "chore: update generated assets"

# 重建 Docker 容器
./docker/rebuild.sh

使用 rebuild.sh：

cd docker
./rebuild.sh

该脚本会：

检查环境变量文件
停止现有容器
重新构建并启动

评论与统计配置：

在 config/site.yaml 中配置评论系统和统计：

# 评论系统（可选）
comment:
  remark42:
    enabled: true
    host: https://your-remark-server.com/
    siteId: your-site-id

# 统计系统（可选）
analytics:
  umami:
    enabled: true
    id: your-umami-id
    endpoint: https://your-umami-server.com
    # 页面访问量展示（可选，需要 share token）
    # statistics_display:
    #   token: your-umami-share-token
    #   article_page_views: true
    #   footer_site_stats: true

Docker 端口可在 .env 中配置 BLOG_PORT=4321。

注意事项：

生成的 JSON 文件必须提交到 git，Docker 构建时会直接使用
如果忘记运行生成脚本，相关功能（LQIP 占位符、相关文章推荐等）将不可用
Docker 镜像基于 nginx
，仅包含静态文件，无需 Node.js 运行时

Koharu CLI

博客自带交互式命令行工具，提供备份还原、主题更新、内容生成、新建内容等功能。

启动方式：

pnpm koharu              # 交互式主菜单

新建内容

使用 CLI 快速创建博客文章和友链：

# 交互式选择创建类型（文章或友链）
pnpm koharu new

# 或直接指定类型
pnpm koharu new post     # 新建博客文章
pnpm koharu new friend   # 新建友情链接

新建博客文章功能：

交互式输入文章信息：
- 标题 - 文章标题（必填）
- Slug - 自定义 URL（可选，默认根据标题自动生成拼音）
- 描述 - 文章摘要（可选）
- 分类 - 从已有分类中选择（必选）
- 标签 - 添加标签，逗号分隔（可选）
- 草稿 - 是否保存为草稿（默认否）
自动生成 frontmatter（包含 title、date、categories、tags 等）
检查文件是否已存在，避免覆盖
文章保存在对应的分类目录下（如 src/content/blog/note/front-end/my-post.md）

新建友情链接功能：

交互式输入友链信息：
- 站点名称 - 友站的名称（必填）
- 站点 URL - 友站的链接（必填，需完整 URL）
- 站长昵称 - 友站站长的昵称（必填）
- 站点描述 - 友站的简介（必填）
- 头像 URL - 友站的头像链接（必填）
- 主题色 - 友站的主题色（可选，可选择预设颜色或自定义十六进制）
自动追加到 config/site.yaml 的 friends.data 数组
保留 YAML 文件的格式和注释

使用示例：

# 创建新文章
pnpm koharu new post
# 按提示输入：
# 标题: React Hooks 使用指南
# Slug: (自动生成 react-hooks-shi-yong-zhi-nan，可修改或清空)
# 描述: React Hooks 的完整使用教程
# 分类: 选择"笔记 → 前端"
# 标签: React, Hooks, 教程
# 草稿: 否

# 创建友链
pnpm koharu new friend
# 按提示输入友站信息

备份与还原

更新主题前，建议先备份你的个人内容：

# 基础备份（博客文章、配置、头像、.env）
pnpm koharu backup

# 完整备份（包含所有图片和生成的资产）
pnpm koharu backup --full

# 查看所有备份
pnpm koharu list

# 还原最新备份
pnpm koharu restore --latest

# 预览将要还原的文件（不实际还原）
pnpm koharu restore --dry-run

# 强制还原（覆盖已存在的文件）
pnpm koharu restore --force

# 清理旧备份（保留最近 5 个）
pnpm koharu clean --keep 5

备份文件存储在 backups/ 目录，格式为 backup-YYYY-MM-DD-HHMMSS.tar.gz。

更新主题

使用 CLI 自动更新主题，完成备份 → 拉取 → 合并 → 安装依赖的完整流程：

# 完整更新流程（默认会先备份）
pnpm koharu update

# 仅检查是否有更新
pnpm koharu update --check

# 跳过备份直接更新
pnpm koharu update --skip-backup

# 强制模式（跳过工作区检查和确认）
pnpm koharu update --force

# 更新到指定版本（如 v2.1.0）
pnpm koharu update --tag v2.1.0

# clean 模式（零冲突，强制备份，适合首次迁移或冲突较多时）
pnpm koharu update --clean

# rebase 模式（重写历史，强制备份，适合熟悉 git 的用户）
pnpm koharu update --rebase

# 预览操作（不实际执行，可配合 --clean 或 --rebase 使用）
pnpm koharu update --dry-run

选项说明：

选项	说明
`--check`	仅检查更新，不执行合并
`--skip-backup`	跳过备份步骤（clean/rebase 模式下无效，强制备份）
`--force`	跳过工作区脏检查和确认提示（不影响合并方式）
`--tag`	指定目标版本（如 `v2.1.0`），支持升级和降级
`--clean`	Clean 模式，零冲突更新（替换主题文件 + 还原用户内容）
`--rebase`	Rebase 模式，重写历史完全同步上游（强制要求备份）
`--dry-run`	预览操作，不实际执行

三种更新模式：

模式	命令	适合场景	备份	冲突处理
默认	`pnpm koharu update`	日常更新	可选	用户内容自动保留，主题冲突手动解决
Clean	`--clean`	首次迁移、冲突较多	强制	零冲突
Rebase	`--rebase`	熟悉 git 的用户	强制	需手动解决

默认模式（Merge）：

使用 git merge --no-ff 合并上游更新，保留 merge-base 信息，让后续更新的冲突更少。

智能冲突处理：

用户内容文件（博客文章、配置、独立页面、图片等）发生冲突时，自动保留本地版本
主题文件（组件、脚本、样式等）发生冲突时，需要手动解决
如果所有冲突都是用户内容 → 整个更新自动完成，零手动操作

📝 提交格式：

chore: merge upstream theme v2.3.2

Clean 模式：

用上游最新版本替换所有主题文件，然后从备份还原用户内容，实现零冲突更新。

执行流程：

强制备份你的博客内容
创建 merge commit 记录版本关系
用上游文件覆盖本地所有文件
从刚才的备份还原用户内容（博客文章、配置、独立页面、图片、.env）

⚠️ 注意：

你对主题文件的自定义修改（如改了某个组件、布局、样式）不会被保留
备份范围包含：src/content/blog/、config/site.yaml、src/pages/*.md、public/img/、.env
使用 --full 备份选项可额外保留 favicon、LQIP、相似度、AI 摘要等生成资产

适用场景：

首次从旧版本迁移，历史冲突太多无法正常 merge
没有自定义主题文件，只写了博客内容

Rebase 模式：

执行 git rebase upstream/main（或指定的 tag），将本地提交重放到上游之上。适合熟悉 git 操作的用户。

⚠️ 注意：Rebase 模式会重写 Git 历史，请确保已备份重要内容。CLI 会强制要求备份（忽略 --skip-backup 和 --force）。

使用 --dry-run 预览：

所有模式都支持 --dry-run 预览操作效果：

pnpm koharu update --dry-run          # 预览默认 merge
pnpm koharu update --clean --dry-run  # 预览 clean 模式
pnpm koharu update --rebase --dry-run # 预览 rebase 操作

💡 给熟悉 git 的用户： CLI 更新命令是对 git 操作的封装便利工具。如果你对 git 比较熟悉，建议直接使用 git fetch upstream && git rebase upstream/main 手动操作，这样能更精确地控制合并过程。

更新流程说明：

检查 Git 状态 — 确保工作区干净（无未提交的更改）
备份当前内容 — 可选（clean/rebase 模式强制备份）
设置 upstream — 自动添加 upstream remote（如果不存在）
获取最新代码 — git fetch upstream
显示更新预览 — 列出新增的提交和更新日志
执行更新 — 根据所选模式执行 merge / clean / rebase
安装依赖 — pnpm install

处理合并冲突：

默认 merge 模式下，用户内容冲突会被自动解决（保留本地版本）。如果主题文件仍有冲突，CLI 会显示冲突文件列表。你可以：

选择"中止合并"恢复到更新前状态
手动解决冲突后运行 git add . && git commit

# 如果选择手动解决冲突
git status                    # 查看冲突文件
# 编辑冲突文件，保留需要的内容
git add .
git commit -m "merge: resolve conflicts"

更新时使用的 Git 命令：

操作	命令
检查工作区状态	`git status --porcelain`
获取当前分支	`git rev-parse --abbrev-ref HEAD`
检查 upstream	`git remote -v`
添加 upstream	`git remote add upstream https://github.com/cosZone/astro-koharu.git`
获取更新	`git fetch upstream`
查看新提交数量	`git rev-list --left-right --count HEAD...upstream/main`
查看新提交列表	`git log HEAD..upstream/main --pretty=format:"%h \| %s \| %ar \| %an"`
默认合并	`git merge --no-ff upstream/main`
Clean 合并	`git merge -s ours upstream/main` + `git checkout upstream/main -- .`
Rebase	`git rebase upstream/main`
中止合并	`git merge --abort`

内容生成

生成各种内容资产：

# 交互式选择生成类型
pnpm koharu generate

# 或直接指定类型
pnpm koharu generate lqips        # 生成 LQIP 图片占位符
pnpm koharu generate similarities # 生成语义相似度向量
pnpm koharu generate summaries    # 生成 AI 摘要
pnpm koharu generate all          # 生成全部

如何添加新页面

在 src/pages/ 目录创建 .astro 文件
Astro 使用文件系统路由，文件路径即 URL 路径

示例：

src/pages/about.astro       → /about
src/pages/tags/[tag].astro  → /tags/:tag（动态路由）

如何自定义样式

全局样式：

编辑 src/styles/index.css。

组件样式：

使用 Tailwind CSS 工具类或 Astro 的 <style> 标签。

Tailwind 配置：

编辑 tailwind.config.ts 自定义主题、颜色、字体等。

主题变量：

在 src/styles/index.css 中定义的 CSS 变量：

:root {
  --primary-color: #ff6b6b;
  /* ... 更多变量 */
}

动画系统

使用 CSS 动画以及 Motion。

动画配置：

在 src/constants/anim/ 目录中：

spring.ts - 弹簧动画配置
variants.ts - 动画变体定义
props.ts - 可复用的动画属性

使用示例：

import { motion } from "motion/react";
import { fadeIn } from "@constants/anim/variants";

<motion.div variants={fadeIn} initial="hidden" animate="visible">
  内容
</motion.div>;

与 Hexo/Shoka 主题的对比

保留的特性

✅ 分类和标签系统
✅ 文章置顶功能
✅ 深色/浅色主题切换
✅ 响应式设计
✅ 友链页面
✅ 归档页面

改进之处

性能：

⚡ 静态站点生成 (SSG)，加载速度更快
⚡ 按需加载 JavaScript
⚡ 图片优化

开发体验：

🛠️ TypeScript 类型安全
🛠️ 热模块替换 (HMR)
🛠️ 现代化的开发工具链

功能增强：

🔍 更强大的全站搜索（Pagefind）
📝 内容集合 (Content Collections) 类型安全
🎨 Tailwind CSS 4.x 样式系统
🌊 View Transitions API 页面过渡

技术栈差异

方面	Hexo + Shoka	astro-koharu
框架	Hexo (Node.js)	Astro 7.x
模板引擎	EJS/Pug	Astro + React
样式	Stylus	Tailwind CSS 4.x
构建工具	Webpack	Vite
类型检查	无	TypeScript
内容管理	文件系统	Content Collections

常见问题

如何修改封面图片？

在文章 frontmatter 中设置 cover 字段：

cover: /img/cover/1.webp

图片放在 public/img/ 目录。如果不设置，会使用默认封面。

如何自定义域名？

部署到 Vercel 后，在 Vercel 项目设置中添加自定义域名，然后更新 config/site.yaml 中的 site.url 字段。

如何添加评论功能？

项目支持四种评论系统：Waline、Giscus、Remark42、Twikoo。在 config/site.yaml 的 comment 配置块中选择使用的提供商。

Waline（推荐）

Waline 是一个简洁、安全的评论系统，支持多种部署方式（Vercel、Railway、Zeabur 等）。

特点：

🚀 部署简单，支持多种平台一键部署
💬 支持 Markdown、表情、@提及、邮件通知
📊 内置浏览量统计、评论管理后台
🔐 支持多种登录方式（匿名、社交账号）
🛡️ 内置反垃圾评论、敏感词过滤
🎨 自动跟随站点深色/浅色主题

前置要求：

部署 Waline 服务端（部署指南）
获取服务端 URL

配置示例：

comment:
  provider: waline
  waline:
    serverURL: https://your-waline-server.vercel.app # Waline 服务端地址（必填）
    lang: zh-CN # 语言
    dark: html.dark # 暗黑模式 CSS 选择器
    meta: # 评论者信息字段
      - nick
      - mail
      - link
    requiredMeta: # 必填字段
      - nick
    login: enable # 登录模式 ('enable' | 'disable' | 'force')
    wordLimit: 0 # 评论字数限制 (0 = 无限制)
    pageSize: 10 # 每页评论数
    imageUploader: false # 图片上传功能
    highlighter: true # 代码高亮
    texRenderer: false # LaTeX 渲染
    search: false # 搜索功能
    reaction: false # 文章反应功能
    # recaptchaV3Key: '' # reCAPTCHA v3 Key (可选)
    # turnstileKey: '' # Cloudflare Turnstile Key (可选)

参数说明：

参数	类型	默认值	说明
`serverURL`	`string`	必填	Waline 服务端地址
`lang`	`string`	`'zh-CN'`	界面语言（支持 zh-CN, en, jp 等）
`dark`	`string`	`'html.dark'`	暗黑模式 CSS 选择器
`meta`	`string[]`	`['nick','mail','link']`	评论者信息字段
`requiredMeta`	`string[]`	`['nick']`	必填字段
`login`	`'enable'` \| `'disable'` \| `'force'`	`'enable'`	登录模式
`wordLimit`	`number`	`0`	评论字数限制（0 = 无限制）
`pageSize`	`number`	`10`	每页评论数
`imageUploader`	`boolean`	`false`	是否启用图片上传
`highlighter`	`boolean`	`true`	是否启用代码高亮
`texRenderer`	`boolean`	`false`	是否启用 LaTeX 渲染
`search`	`boolean`	`false`	是否启用搜索功能
`reaction`	`boolean`	`false`	是否启用文章反应功能
`recaptchaV3Key`	`string`	-	reCAPTCHA v3 Key（可选，防垃圾评论）
`turnstileKey`	`string`	-	Cloudflare Turnstile Key（可选）

部署 Waline 服务端：

推荐使用 Vercel 一键部署：

访问 Waline 快速开始
点击 "Deploy with Vercel" 按钮
登录 Vercel，授权 GitHub 仓库
配置环境变量（数据库连接、管理员邮箱等）
部署完成后获取服务端 URL（如 https://your-waline.vercel.app）

主题自动切换：

Waline 组件已实现主题自动切换，通过 dark 参数（默认 html.dark）自动跟随站点深色/浅色模式。

参考链接：

Remark42

Remark42 是一个轻量级的自托管评论系统，隐私友好，无需第三方服务。

特点：

🔒 自托管，完全掌控数据
🚫 无广告、无追踪
💾 支持多种存储后端（BoltDB、Memory）
🔐 支持多种社交登录（GitHub、Google、Twitter 等）
📧 邮件通知、评论审核
🎨 自动跟随站点深色/浅色主题

前置要求：

部署 Remark42 服务端（部署指南）
配置站点 ID 和域名

配置示例：

comment:
  provider: remark42
  remark42:
    host: https://comment.example.com/ # Remark42 服务器地址（必填）
    siteId: your-site-id # 站点 ID（必填）

参数说明：

参数	类型	说明
`host`	`string`	Remark42 服务器地址（必填，需带 `http://` 或 `https://`）
`siteId`	`string`	站点 ID（必填，在 Remark42 服务端配置中定义）

部署 Remark42 服务端：

推荐使用 Docker 部署：

docker run -d \
  --name remark42 \
  -p 8080:8080 \
  -e REMARK_URL=https://comment.example.com \
  -e SECRET=your-secret-key \
  -e SITE=your-site-id \
  -e AUTH_GITHUB_CID=your-github-client-id \
  -e AUTH_GITHUB_CSEC=your-github-client-secret \
  -v /path/to/data:/srv/var \
  umputun/remark42:latest

详细配置请参考 Remark42 安装指南。

主题自动切换：

Remark42 组件已实现主题自动切换，使用 MutationObserver 监听站点主题变化，自动调用 window.REMARK42.changeTheme() 更新评论框主题。

参考链接：

Giscus

Giscus 是基于 GitHub Discussions 的评论系统，无需自建后端，评论数据存储在你的 GitHub 仓库中。

具体配置可以看看这篇文章：https://zhuanlan.zhihu.com/p/693434928

前置要求：

仓库必须是公开的
安装 giscus app
在仓库中启用 Discussions 功能

获取配置参数：

访问 giscus.app
输入你的仓库名称（格式：owner/repo）
选择页面与 Discussion 的映射方式（推荐 pathname）
选择 Discussion 分类（推荐 Announcements）
启用所需功能（reactions、评论框位置等）
复制生成的 data-repo-id 和 data-category-id

配置示例：

comment:
  provider: giscus
  giscus:
    repo: username/repo # GitHub 仓库名 (owner/repo 格式)
    repoId: R_kgDOxxxxxx # 仓库 ID (从 giscus.app 获取)
    category: Announcements # Discussion 分类名称
    categoryId: DIC_kwDOxxxxxx # 分类 ID (从 giscus.app 获取)
    mapping: pathname # 映射方式
    reactionsEnabled: "1" # 启用 reactions ('1' 启用, '0' 禁用)
    emitMetadata: "0" # 发送元数据
    inputPosition: top # 输入框位置 ('top' | 'bottom')
    lang: zh-CN # 语言

参数说明：

参数	类型	说明
`repo`	`string`	GitHub 仓库，格式为 `owner/repo`
`repoId`	`string`	仓库 ID，从 giscus.app 获取
`category`	`string`	Discussion 分类名称
`categoryId`	`string`	分类 ID，从 giscus.app 获取
`mapping`	`string`	页面与 Discussion 的映射方式
`term`	`string`	当 `mapping` 为 `specific` 或 `number` 时使用
`strict`	`'0' \| '1'`	严格匹配模式，默认 `'0'`
`reactionsEnabled`	`'0' \| '1'`	是否启用 reactions，默认 `'1'`
`emitMetadata`	`'0' \| '1'`	是否发送页面元数据，默认 `'0'`
`inputPosition`	`'top' \| 'bottom'`	评论输入框位置，默认 `'top'`
`lang`	`string`	界面语言，默认 `'zh-CN'`
`host`	`string`	自托管 Giscus 实例的地址（可选）
`theme`	`string`	固定主题（不设置则跟随站点主题切换）
`loading`	`'lazy' \| 'eager'`	加载方式，默认 `'lazy'`

映射方式说明：

pathname（推荐）：使用页面路径匹配，如 /post/my-article
url：使用完整 URL 匹配
title：使用页面标题匹配
og:title：使用 Open Graph 标题匹配
specific：使用 term 参数指定的值
number：使用 term 参数指定的 Discussion 编号

主题自动切换：

本主题已实现 Giscus 评论框的主题自动切换，会跟随站点的深色/浅色模式自动调整。实现原理：

组件挂载时读取当前主题
使用 MutationObserver 监听 document.documentElement 的 class 变化
检测到主题切换时通过 postMessage 通知 Giscus iframe 更新主题

参考链接：

Twikoo

Twikoo 是一个搭建免费，部署简单，功能丰富的简洁、安全、易用的静态网站评论系统。

特点：

☁️ 云开发 / 自托管双部署模式
🔒 隐私安全，无广告、无恶意追踪
📧 支持邮件 / 微信公众号评论通知
⚙️ 后台评论审核、敏感词过滤
😊 内置表情包、支持图片上传
🌙 原生支持深色 / 浅色主题切换
👥 访客标记、评论点赞、楼中楼回复
🛡️ 内置反垃圾评论防护

前置要求：

部署 Twikoo 服务端（腾讯云开发 / 自托管，部署指南）
配置云开发环境 ID 或自托管服务地址

配置示例：

comment:
  provider: twikoo
  twikoo:
    envId: # Twikoo 环境 ID (腾讯云) 或 Vercel 环境地址 (必填)
    region: # 环境地域，默认为 ap-shanghai
    path: # 用于区分不同文章的自定义 js 路径，如果您的文章路径不是 location.pathname，需传此参数
    lang: # 语言 (默认: 'zh-CN')

参数说明：

参数	类型	说明
`envId`	`string`	Twikoo 环境 ID (必填，需带 `https://` 或 `https://`）
`region`	`string`	环境地域，默认为 `'ap-shanghai'`
`path`	`string`	用于区分不同文章的自定义 js 路径，如果您的文章路径不是 location.pathname，需传此参数
`lang`	`string`	语言 (默认: `'zh-CN'`)

部署 Twikoo 服务端：

参考 Twikoo 官网获取详细部署指南。

主题自动切换：

Twikoo 已实现主题自动切换

参考链接：

Twikoo 官网

草稿文章如何预览？

运行 pnpm dev 本地开发模式，草稿会自动显示（带 DRAFT 标识）。

如何关闭某些功能？

关闭某个系列：设置该系列的 enabled: false

featuredSeries:
  - slug: weekly
    enabled: false # 禁用此系列
    # ...

关闭所有系列：将 featuredSeries 设为空数组 []
关闭搜索：移除 astro.config.mjs 中的 pagefind() 集成
关闭统计：设置 analytics.umami.enabled = false
关闭评论：移除 comment.provider 配置或将其设置为空
关闭 Shoka 语法：在 config/site.yaml 的 content 部分将对应功能设为 false，如 enableShokaContainers: false（关闭提醒块/折叠块/标签卡）、enableShokaSpoiler: false（关闭隐藏文字）等
关闭数学公式：设置 content.enableMath = false
关闭练习题：设置 content.enableQuiz = false

如何更改文章 URL 格式？

默认使用文件名作为 URL。可以通过 link 字段自定义：

link: my-custom-url

URL 特殊字符处理

文章链接（link）和标签（tags）支持包含特殊字符，系统会自动进行 URL 编码处理。

文章链接特殊字符：

---
title: C# 学习笔记
link: test-C# # 包含 # 字符
---

访问时 URL 会自动编码为 /post/test-C%23，确保浏览器正确解析。

标签特殊字符：

tags:
  - C#
  - C++
  - .NET
  - Node.js

标签会自动转换为 URL 安全的格式：

C# → /tags/c%23
C++ → /tags/c%2B%2B
.NET → /tags/.net
Node.js → /tags/node.js

注意事项：

特殊字符包括：#、+、&、?、%、空格等
标签中的 / 会被替换为 -（如 前端/React → 前端-react）
分类名称通过 categoryMap 映射，建议使用纯英文 slug 避免编码问题

参考资源

更新日志

查看 CHANGELOG.md 了解版本更新历史。

如有问题或建议，欢迎在 GitHub Issues 中反馈。

在公开文章里藏一小段：局部加密块的用法

Sun, 09 Nov 2025 11:40:00 GMT

主题支持两种加密：在 frontmatter 里写 password 加密整篇文章，或者用 :::encrypted 只加密其中一段。这篇只讲后者。

本文示例密码：koharu

什么时候用局部加密

文章大部分内容可以公开，只有一小段不希望被搜索引擎收录，比如网盘链接、给朋友的留言、还在保密期的计划。

如果整篇都不想公开，用整篇加密更合适，可以参考站内的「加密文章演示」。

写法

:::encrypted{password="koharu"}
这里是只给知道密码的人看的内容。
:::

渲染出来是这样的，输入 koharu 试试：

多个加密块

一篇文章里可以有多个加密块，每个块的密码相互独立：

需要注意的地方

前端加密的目的是防止明文被直接收录，而不是对抗有针对性的破解。密码强度决定了这段内容到底有多安全。

密码会出现在 Markdown 源文件里。如果你的博客仓库是公开的，加密块对仓库访客没有任何作用。

加密块会影响哪些功能？

站内搜索：页面里只有密文，加密内容不会进入搜索索引
AI 摘要与相关文章：这两个脚本读取的是 Markdown 源文件，加密块的明文会被读到。所以本文在 frontmatter 里设置了 excludeFromSummary: true
复制 Markdown：含局部加密块的文章不提供原文，「复制 Markdown」「下载」和「在写作室打开」都不会出现，避免明文和密码随源文件一起公开

顺便：标签的几种颜色

默认主要信息成功警告危险

写教程时，我常用标签标出「示例密码」这类需要读者留意的信息，比放在正文里更醒目。

用一道体检题复习贝叶斯公式

Sat, 23 Aug 2025 07:30:00 GMT

最近帮朋友看一道概率题，发现自己对贝叶斯公式的印象只剩下「分母很长」。这里重新推一遍，顺便出几道题给自己练手。

题目

假设某种疾病在人群中的患病率是 1%。有一种检测：

患病的人去检测，99% 会呈阳性
没患病的人去检测，5% 会被误判为阳性

一个人检测结果为阳性，他真正患病的概率是多少？

先凭直觉猜一个数，再往下看。

推导

记 DDD 为「患病」，+++ 为「检测阳性」。题目给出的是：

P(D)=0.01,P(+∣D)=0.99,P(+∣¬D)=0.05P(D) = 0.01,\quad P(+ \mid D) = 0.99,\quad P(+ \mid \neg D) = 0.05P(D)=0.01,P(+∣D)=0.99,P(+∣¬D)=0.05

我们要求的是 P(D∣+)P(D \mid +)P(D∣+)。贝叶斯公式：

P(D∣+)=P(+∣D) P(D)P(+)P(D \mid +) = \frac{P(+ \mid D)\,P(D)}{P(+)}P(D∣+)=P(+)P(+∣D)P(D)

分母用全概率公式展开：

P(+)=P(+∣D) P(D)+P(+∣¬D) P(¬D)P(+) = P(+ \mid D)\,P(D) + P(+ \mid \neg D)\,P(\neg D)P(+)=P(+∣D)P(D)+P(+∣¬D)P(¬D) 展开计算过程

代入数值：

P(+)=0.99×0.01+0.05×0.99=0.0099+0.0495=0.0594P(+) = 0.99 \times 0.01 + 0.05 \times 0.99 = 0.0099 + 0.0495 = 0.0594P(+)=0.99×0.01+0.05×0.99=0.0099+0.0495=0.0594

于是：

P(D∣+)=0.00990.0594=16≈16.7%P(D \mid +) = \frac{0.0099}{0.0594} = \frac{1}{6} \approx 16.7\%P(D∣+)=0.05940.0099=61≈16.7%

答案是：大约六分之一，也就是 16.7%

为什么和直觉差这么多

直觉往往会盯着「99% 的准确率」，忽略了患病率本身只有 1%。换成具体人数会更直观：假设有 10000 人去检测，

	人数	检测阳性
患病	100	99
未患病	9900	495

阳性的一共 594 人，其中真正患病的只有 99 人，正好是六分之一。没患病的人基数太大，5% 的误判也就不少了。

这种「忽略基础比率」的倾向，在心理学里叫基础比率谬误。

用代码验证

Python JavaScript

bayes.py

p_d = 0.01
p_pos_given_d = 0.99
p_pos_given_not_d = 0.05

p_pos = p_pos_given_d * p_d + p_pos_given_not_d * (1 - p_d)
print(p_pos_given_d * p_d / p_pos)  # 0.1666...

bayes.js

const pD = 0.01;
const pPos = 0.99 * pD + 0.05 * (1 - pD);
console.log((0.99 * pD) / pPos); // 0.1666...

练习

如果患病率从 1% 提高到 10%，其他条件不变，阳性者真正患病的概率会怎样变化？
- 基本不变
- 明显升高
- 明显降低

解析：基础比率变大，分子增长得比分母快。代入计算约为 68.75%。

以下哪些做法可以提高阳性结果的可信度？
- 降低误判率
- 对阳性者再做一次独立检测
- 扩大检测人数

解析：扩大检测人数不改变任何一个概率。第二次独立检测相当于用第一次的结果作为新的先验。

贝叶斯公式中的分母 P(+)P(+)P(+) 可以用全概率公式展开。

解析：P(+)P(+)P(+) 按「患病」与「未患病」两种情况分别计算再相加。

在本题中，P(+∣D)P(+ \mid D)P(+∣D) 叫作检测的灵敏度，1−P(+∣¬D)1 - P(+ \mid \neg D)1−P(+∣¬D) 叫作检测的特异度。

解析：灵敏度衡量「有病能查出来」，特异度衡量「没病不误报」。

示例周刊 Vol.3 | 写作环境

Fri, 04 Jul 2025 13:00:00 GMT

距离上一期隔了好几个月。周刊不一定要准时，能接着写下去就好。

这一期聊写作环境。

一篇文章的路径

infographic sequence-zigzag-steps-underline-text
data
  title 从草稿到上线
  items
    - label 起草
      desc 在编辑器或写作室里写下初稿
    - label 预览
      desc 本地开发服务器实时查看排版
    - label 检查
      desc 跑一遍 lint 和类型检查
    - label 发布
      desc 推送后由 CI 构建部署

本期工具

本地预览

写长文时我习惯开着开发服务器，左边编辑器，右边浏览器：

pnpm dev

保存文件后页面会自动刷新。改了 config/site.yaml 的话需要重启服务器，配置在构建时会被缓存。

草稿

还没写完的文章在 frontmatter 里加上 draft: true，生产构建时会被排除，开发环境仍然可见。

新建文章

不想手写 frontmatter 的话，可以用 CLI 交互式创建：

pnpm koharu new post

读到的东西

Astro 文档：内容集合：写自定义 frontmatter 字段之前值得读一遍。
MDN：<details> 元素：主题里的折叠块就是类似的交互。

一句话

先写完，再写好。

这是目前的最新一期。翻到页面底部，可以看到它和前两期之间的上一期导航。

示例周刊 Vol.2 | 把手边的工具用顺

Fri, 14 Mar 2025 12:30:00 GMT

这一期没有大新闻，主要聊几样每天都在用、但很少专门写的工具。顺带一提，从这一期开始，系列页面会把每期标题里 Vol.N 之后的部分当作本期标题，所以标题写成「示例周刊 Vol.2 | 把手边的工具用顺」这样就行。

本期推荐

本博客主题

先放一张链接卡片。链接单独占一段时，构建阶段会去抓取页面的 Open Graph 信息，渲染成卡片：

github.com

GitHub - cosZone/astro-koharu: astro-koharu 是一个萌系/二次元/粉蓝配色的 astro 主题博客，灵感来自 Hexo 的 Shoka 主题，加了很多自己的小巧思，性能优越。

astro-koharu 是一个萌系/二次元/粉蓝配色的 astro 主题博客，灵感来自 Hexo 的 Shoka 主题，加了很多自己的小巧思，性能优越。 - cosZone/astro-koharu

https://github.com/cosZone/astro-koharu

抓取结果会写进 .cache/og-data.json，下次构建直接读缓存；抓取失败也不会让构建失败，只是退回成普通链接。

在 React 里嵌入推文

github.com

GitHub - vercel/react-tweet: Embed tweets in your React application.

Embed tweets in your React application. Contribute to vercel/react-tweet development by creating an account on GitHub.

https://github.com/vercel/react-tweet

主题的推文嵌入就是基于这个库做的。如果你的文章里经常引用推文，可以在 config/site.yaml 的 content.enableTweetEmbed 里开关。

工具

静态搜索

Pagefind 在构建后扫描生成的 HTML，产出分片的索引文件。访客搜索时只下载需要的那几片，不需要任何服务端。对于几百篇文章的博客来说，这个方案几乎没有维护成本。

格式化与检查

仓库用 Biome 同时负责格式化和 lint。提交前跑一次：

pnpm lint:fix

备份

升级主题前先备份一下内容和配置：

pnpm koharu backup
pnpm koharu list

一句话

工具顺手的标志是你忘了它的存在。

下一期聊聊写作环境本身。

Tailwind CSS v4 升级笔记

Sun, 16 Feb 2025 13:20:00 GMT

Tailwind CSS v4.0 正式发布后，我把一个小项目从 v3 升了上去。整体比预想顺利，但有几处改动不看文档很难发现，记在这里。

这篇写于 v4.0 发布后不久。后续版本的细节可能有调整，以官方升级指南为准。

先跑官方升级工具

官方提供了一个自动迁移工具，会改依赖、改配置、改模板里的类名：

npx @tailwindcss/upgrade

建议在干净的 Git 工作区里跑，改完用 diff 逐个看一遍。下面几节是我看 diff 时记下的。

配置搬进 CSS

入口文件

v3 的三条指令变成了一行导入：

global.css

/* v3 */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* v4 */
@import "tailwindcss";

主题变量

自定义颜色、字体不再写在 tailwind.config.js 里，而是用 @theme 声明 CSS 变量：

global.css

@import "tailwindcss";

@theme {
  --color-sakura: oklch(0.82 0.08 0);
  --font-display: "Noto Serif SC", serif;
}

声明之后，bg-sakura、font-display 这些类就能直接用，同时 var(--color-sakura) 也可以在任何地方引用。

暂时保留旧配置

如果一时迁不完，可以用 @config 继续加载 JS 配置文件：

@config "../../tailwind.config.mjs";

构建集成

用 Vite 的项目改用官方插件，比走 PostCSS 简单：

vite.config.js

import { defineConfig } from 'vite';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  plugins: [tailwindcss()],
});

另外 v4 会自动检测模板文件，不再需要 content 数组。如果有文件在默认扫描范围之外，用 @source 补上。

改了名字的工具类

升级工具大部分能自动改，但我还是在几个动态拼接的类名上漏了：

v3	v4
`shadow-sm`	`shadow-xs`
`shadow`	`shadow-sm`
`rounded-sm`	`rounded-xs`
`rounded`	`rounded-sm`
`outline-none`	`outline-hidden`

还有两处默认值的变化：ring 的默认宽度从 3px 变成了 1px，border 的默认颜色变成了 currentColor。页面上突然多出来的深色边框，基本都是后者导致的。

小结

升级本身花了一个晚上，大部分时间在逐页对比样式。如果你的项目也有用字符串拼接出来的类名，记得手动搜一遍。

《我推的孩子》第二季观后感：一出舞台剧，拍了大半季

Sun, 19 Jan 2025 15:10:00 GMT

拖了一个季度，终于把《我推の子(おしのこ)》第二季补完了。第一季的开头太有冲击力，我一度担心后面撑不住。看完第二季，担心是多余的，只是它换了一种讲法。

大半季都在排一出戏

第二季的主体是一部漫画改编的 2.5 次元舞台剧，从剧本会开到首演，几乎占满了整季。如果只是想看主线推进，这段可能会让人着急；但我反而觉得这是整部作品目前最扎实的部分。

它把「改编」这件事拆得很细：原作者在意什么，编剧要妥协什么，演员又怎么理解角色。几方都不是坏人，只是站的位置不同。原作者和编剧之间那段沟通的戏，我看的时候一直在想现实里的改编纠纷，看完也没觉得哪一方完全有理。

舞台上的两个人

这一季最好看的是两位女演员在台上的较劲。一个是童星出身，习惯配合别人；一个是剧团出身、以钻研角色见长的演员。她们在台上互相点燃，台下的关系也跟着微妙起来。

动画在这里用了不少大胆的演出：舞台背景直接溶解成角色的心象，灯光和镜头一起把情绪推上去。这几集我暂停了好几次，就为了多看几眼画面。

一点具体的剧透（点击展开）

主角在舞台上把自己最不愿意回想的过去，变成了表演的燃料。演得越好，代价越大。这一段的演出很克制，没有哭喊，反而更难受。

季末的转向

舞台剧落幕之后，故事很快拉回复仇的主线。季末几集的信息量不小，有一个角色的状态变化尤其明显：那个一直很阳光的角色，在得知某个真相之后，眼神变了。

我对这个结尾的感觉很复杂。一方面，它为第三季埋好了钩子；另一方面，舞台剧那段好不容易建立起来的温度，一下子就被收走了。也许这本来就是这部作品想说的：台前再热闹，台后的事情不会因此消失。

一些零碎的想法

OP 依然很好听，我单曲循环了一周
配角的戏份比第一季丰富，几位年长演员的台词尤其耐听
剧中剧的台词写得很用心，可以当成一部独立的短篇来看

第三季出了再接着写。

关闭目录编号示例

Sat, 06 Jan 2024 16:00:00 GMT

本文展示如何关闭目录的自动编号功能。

目录编号功能

默认情况下，astro-koharu 会使用 CSS 计数器为目录自动添加层级编号，如：

1. 第一章
- 1.1. 第一节
- 1.2. 第二节
1. 第二章

关闭编号

通过设置 tocNumbering: false 可以关闭特定文章的编号：

---
title: 我的文章
tocNumbering: false
---

效果对比

开启编号（默认）

目录项会显示 1., 1.1., 1.1.1. 这样的编号。

关闭编号

目录项只显示标题文本，没有编号前缀。

本文效果

本文已设置 tocNumbering: false，你可以查看右侧目录（桌面端）或展开目录（移动端）来查看效果。

技术实现

编号功能通过纯 CSS 计数器实现，零运行时开销：

.toc-numbering {
  counter-reset: h2;
}

.toc-numbering h2::before {
  counter-increment: h2;
  content: counter(h2) ". ";
}

使用建议

以下场景可能需要关闭编号：

随笔类文章
标题本身已有编号
内容结构较松散的文章
个人偏好

总结

目录编号是一个可选功能，根据文章类型灵活使用即可。

Hello World

Thu, 04 Jan 2024 16:00:00 GMT

你好，世界！这是我的第一篇随笔。

关于这篇文章

这篇文章故意没有设置 description 字段，用于测试以下功能：

自动描述提取 - 系统会自动从正文提取前 150 字作为描述
AI 摘要 - 如果运行了 pnpm generate:summaries，会使用 AI 生成的摘要

随笔分类

随笔分类适合记录：

生活感悟
年度总结
随想随记
个人成长

写作建议

写博客是一件有趣的事情。这里有一些建议：

保持更新

定期更新能让博客保持活力。哪怕是简短的记录，也比长期沉寂好。

记录真实

真实的记录比完美的文字更有价值。不必追求每篇都是精品。

享受过程

写作本身就是一种思考和整理的过程，享受这个过程吧。

结语

这就是一篇简单的随笔示例。希望你也能在这里记录自己的故事。

祝你写作愉快！

示例周刊 Vol.1

Wed, 03 Jan 2024 16:00:00 GMT

这是一期示例周刊，展示周刊/系列文章功能的使用方式。

关于周刊功能

周刊是 astro-koharu 的特色功能之一，适合发布定期更新的系列内容，如：

技术周刊
读书笔记系列
学习记录
项目进度更新

周刊配置

在 config/site.yaml 中配置：

featuredSeries:
  categoryName: 周刊       # 分类名称
  label: 我的周刊          # 显示标签
  fullName: 我的技术周刊
  description: 周刊描述...
  cover: /img/weekly_header.webp
  enabled: true            # 设为 false 可关闭

周刊特点

专属页面 - 周刊有独立的 /weekly 页面
首页展示 - 最新一期会在首页置顶展示
独立列表 - 周刊不会出现在普通文章列表中
系列导航 - 周刊之间有上下篇导航

本期内容示例

工具推荐

工具	用途	链接
Biome	代码检查	biome.dev
Motion	动画库	motion.dev

本周学习

这周学习了以下内容：

Astro 内容集合
Tailwind 主题配置
Motion 动画进阶

下期预告

下期将介绍更多进阶功能，敬请期待！

感谢阅读本期周刊！

小哇牛博客

deepseek-v4.1-flash论文阅读笔记

frontmatter 关键词设置

摘要

Introduction

从 Astro 5 到 Astro 6：astro-koharu 的一次完整迁移实录

先定义成功，而不是先改版本号

依赖升级不是全部追最新

最核心的变化：Content Layer 身份模型

为什么旧文章里的 slug 不能原样留下

历史文章不能靠用户手工迁移

恢复旧备份不能只是 cp -r

四个只在真实构建里暴露的问题

1. Markdown 插件配置开始弃用

2. react-tweet 在预渲染环境里无法加载 CSS

3. RSS 的旧 patch 版本不兼容 Zod 4

4. i18n 配置描述了一个实际不存在的重定向

怎样证明公开行为没有漂移

先验证模板公开行为

再验证迁移脚本，而不只验证 happy path

最后用真实下游仓库做完整恢复

哪些 Astro 6 能力值得顺手开启

一份可复用的迁移顺序

总结

容器查询实战：让卡片自己决定布局

问题：视口宽度不等于组件宽度

媒体查询的写法

为什么不给侧栏单独写一套

基本用法

声明容器

container-type 的取值

编写查询

容器查询单位

cqi 与 cqw

什么时候用 cqw

没有容器时会怎样

在 Tailwind 里使用

踩过的坑

容器不能查询自己

和 overflow 的配合

调试

小结

一篇 Markdown 在构建时经过了什么

总览

remark 阶段

链接卡片的数据从哪来

rehype 阶段

代码块

小结

下雨的周六下午

自定义关键词示例

frontmatter 关键词设置

🔒 加密文章演示

Shoka 主题 Markdown 语法演示

文字特效

下划线 (ins)

下划线颜色

高亮 (mark)

上下标

颜色文字

彩虹文字

键盘键

隐藏文字 (Spoiler)

标签块 (Labels)

提醒块 (Note Blocks)

折叠块 (Collapse)

标签卡 (Tabs)

注音

代码块增强

数学公式

友链卡

多媒体

音频

音频歌单

视频

练习题

单选题

多选题

判断题

填空题

为什么旧文章里的 `slug` 不能原样留下

恢复旧备份不能只是 `cp -r`

2. `react-tweet` 在预渲染环境里无法加载 CSS