柒月の雨

让 published 和 updated 自己维护

Mon, 02 Nov 2026 04:30:00 GMT

写文章的时候，最烦的往往不是正文，而是 frontmatter 里的那几个时间字段：published 忘了写就构建报错，updated 写了又经常忘记改。这次干脆把它们交给构建流程自己维护。

目标#

published 不再是必填，留空时构建自动填当前时间；
updated 也不再需要手写，留空时按规则自动维护；
文章内容一旦变化，updated 自动更新为构建时间；
内容没变时，多次构建结果保持稳定，不能每次构建都把时间刷新一遍。

一、published 改为非必填#

在 src/content.config.ts 里加了一个预处理：

1
const emptyToUndefined = (value: unknown) => {
2
  if (value === undefined || value === null) return undefined;
3
  if (typeof value === "string" && value.trim() === "") return undefined;
4
  return value;
5
};
6

7
const autoDate = () =>
8
  z.preprocess(emptyToUndefined, z.date().optional().default(() => buildNow()));

效果是：不写 published、写 published:（空值）、写 published: "" 都会被当成“未填写”，构建时填入当前时间。

现在最小可用 frontmatter 只剩一行标题：

1
---
2
title: 只有标题也能建
3
---

二、updated 缺省时先回退到 published#

updated 同样是可选字段，缺省时先回退为 published，避免出现“每篇文章都显示最后修改”的情况：

1
schema: z
2
  .object({
3
    published: autoDate(),
4
    updated: optionalDate(),
5
    // ...
6
  })
7
  .transform((data) => ({
8
    ...data,
9
    updated: data.updated ?? data.published,
10
  })),

到这一步，时间字段已经可以完全不手写了，但还差“内容变了要自动更新”的能力。

三、构建时检测内容变更#

这是这次改动的核心：每次构建都拿源文件内容和上一次构建的记录做比较，变了就把 updated 设为当前时间。

实现#

用一个自定义 loader 包住 glob：

1
const postsBaseLoader = glob({
2
  pattern: "**/*.{md,mdx}",
3
  base: "./src/content/posts",
4
});
5

6
const postsLoader: Loader = {
7
  name: "firefly-posts-with-updated-tracking",
8
  load: async (context) => {
9
    await postsBaseLoader.load(context);
10

11
    const previous = readPostHashes();
12
    const next: Record<string, PostHashRecord> = {};
13

14
    for (const entry of context.store.values()) {
15
      const raw = readFileSync(filePath, "utf8");
16
      const hash = createHash("sha256").update(raw).digest("hex");
17
      // 显式写了 updated 就以文件为准
18
      if (explicitUpdated) updated = explicitUpdated;
19
      else if (!record) updated = published;      // 首次收录
20
      else if (record.hash === hash) updated = new Date(record.updated); // 没变
21
      else updated = new Date();                  // 变了
22

23
      entry.data.published = published;
24
      entry.data.updated = updated;
25
      context.store.set(entry);
26
      next[entry.id] = { hash, published: ..., updated: ... };
27
    }
28

29
    if (changed) writePostHashes(next);
30
  },
31
};

展开收起

基线记录存在 src/constants/post-hashes.json：

1
{
2
  "hello-world": {
3
    "hash": "e113d212...",
4
    "published": "2026-10-28T00:00:00.000Z",
5
    "updated": "2026-10-28T00:00:00.000Z"
6
  }
7
}

为什么哈希源文件，而不是解析后的数据#

一开始我直接对 entry.data 做哈希，结果第二次构建怎么都不会触发更新。原因有两个：

Astro 会把校验后的数据缓存进数据仓库，entry.data 里已经带上了 schema 默认值（tags: []、draft: false……），和源文件里的 frontmatter 不是一回事；
上一轮注入的 updated 也留在了缓存里，下一轮会被误判成“用户显式写的更新时间”。

所以最终改成直接读源文件、对文件内容做 SHA-256，并且用正则从 frontmatter 里单独取 published / updated，完全绕开缓存带来的字段污染。

实测#

用一篇临时文章验证了四种情况：

场景	updated 结果
首次构建	等于 published
修改正文后构建	构建当前时间
不改内容再次构建	保持不变
删除文章后构建	基线记录自动移除

页面里 JSON-LD 的 dateModified 也跟着变，astro check 0 errors，astro build 25 页正常。

几个注意点#

显式优先：手写 updated 时不会被自动逻辑覆盖；
基线要提交：src/constants/post-hashes.json 需要跟着仓库走，否则换台机器构建会把所有文章当成“新文章”；
只在构建时更新：pnpm dev 里改文件会立刻写基线，但线上要 pnpm deploy 才生效；
内容变化包括 frontmatter：改标题、标签、分类也会触发更新时间。

小结#

现在写完文章只要负责正文，时间字段交给构建流程：

1
---
2
title: 只写标题就行
3
---

发布、改稿、再发布，updated 会自己跟着走。代码改动已经提交（d6cc53d），基线文件也在仓库里。

Markdown 写法手册

Sun, 01 Nov 2026 12:20:00 GMT

写博客最麻烦的往往不是想法，而是「这段该用什么语法」。这篇文章把本站支持的 Markdown 写法整理成一份速查表，内容本身就是可运行的示例——看到的效果就是语法渲染出来的样子。

基础语法#

标题#

用 # 到 ###### 表示一到六级标题。正文里建议从 ## 开始，# 留给文章标题；右侧「文章目录」会自动收集二、三级标题。

1
## 二级标题
2
### 三级标题

强调与行内代码#

加粗、斜体、删除线、行内代码，也可以组合：加粗里的 代码。

1
**加粗**、*斜体*、~~删除线~~、`行内代码`

链接与图片#

站内链接写相对路径，站外链接会在新标签页打开：Astro 文档、关于我。

图片用 ![替代文字](图片地址)，本地图片放在 public/ 下就能用绝对路径引用：

示例图片

1
[文字](https://example.com)
2
![替代文字](/images/posts/markdown-guide/demo-01.webp "title")

列表#

无序列表用 -、* 或 +
嵌套列表缩进两格或四格
- 像这样
有序列表用 1. 2.

第一步
第二步

任务列表（GitHub 风格）：

已经做完的事
还没做完的事

引用与分割线#

引用用来放摘录。
也可以有多段。

1
> 引用内容
2
---

换行与转义#

段落之间空一行；段落内换行需要行尾加两个空格。想原样显示 *、_、# 等符号时，用反斜杠转义：*不是斜体*。

表格#

表头与内容之间用 --- 分隔，冒号控制对齐：

语法	对齐	说明
`:---`	左对齐	默认
`:---:`	居中	常用
`---:`	右对齐	数字

1
| 左 | 中 | 右 |
2
| :--- | :---: | ---: |
3
| a | b | c |

代码块#

用三个反引号包裹代码，并在开头标注语言。代码块带行号、语言徽章和右上角复制按钮；超过 15 行会自动折叠，点「展开」看全文。

1
export function greet(name) {
2
  return `你好，${name}`;
3
}

行内命令或变量用单个反引号：pnpm dev。

写一段长一点的代码，可以观察自动折叠的效果（下面这段 17 行）：

1
export function buildPost({ title, tags, body }) {
2
  const meta = {
3
    title,
4
    tags,
5
    published: new Date(),
6
    draft: false,
7
    comment: true,
8
  };
9

10
  const lines = body.split("\n");
11

12
  return {
13
    ...meta,
14
    body: lines.map((line) => line.trimEnd()).join("\n"),
15
  };
16
}

展开收起

1
```js
2
const a = 1;
3
```

提示块#

用引用语法加类型标记，支持 GitHub 风格的提示块：NOTE、TIP、IMPORTANT、WARNING、CAUTION。

Note

这是 NOTE，用来补充说明。

Tip

这是 TIP，放一点小技巧。

Important

这是 IMPORTANT，强调必须知道的事。

Warning

这是 WARNING，提醒可能的坑。

Caution

这是 CAUTION，用于危险操作。

1
> [!NOTE]
2
> 内容是 Markdown，可以换行、加列表、放代码。

数学公式#

行内公式用 $...$ ，独立公式用 $$...$$，由 KaTeX 渲染：

行内：当 a≠0a \ne 0a=0 时，方程 ax2+bx+c=0ax^2 + bx + c = 0ax2+bx+c=0 的两个根为 x=−b±b2−4ac2ax = \frac{-b \pm \sqrt{b^2-4ac}}{2a}x=2a−b±b2−4ac。

独立公式：

∑i=1ni=n(n+1)2\sum_{i=1}^{n} i = \frac{n(n+1)}{2}i=1∑ni=2n(n+1)

1
行内 $E = mc^2$
2

3
$$
4
\int_0^1 x^2 \, dx = \frac{1}{3}
5
$$

Mermaid 图表#

用 mermaid 代码块画流程图、时序图，构建时会渲染成静态 SVG：

通过

失败

写 Markdown

构建

发布到 CDN

看构建日志

通过

失败

写 Markdown

构建

发布到 CDN

看构建日志

时序图：

博客读者博客读者打开文章返回 HTML

图片网格#

多张图片并排时，用 [grid] 包起来，列数按图片数量自动排：

示例图二

示例图三

示例图四

1
[grid]
2
![图一](/path/a.jpg)
3
![图二](/path/b.jpg)
4
[/grid]

Wiki 链接#

Obsidian 风格的 [[文章]] 可以按文件名链接到其他文章，支持 [[文件名|显示文字]]：

在七月的雨里开始

给这场迟来的夏雨留一页纸，也给这个刚刚开始的博客写下第一句话。

2026-10-28随笔#日常

1
[[hello-world]]
2
[[hello-world|在七月的雨里开始]]

文章 Frontmatter#

每篇文章开头用 --- 包住一段 YAML，决定标题、时间、分类这些信息：

1
---
2
title: 文章标题
3
published: 2026-11-01T20:20:00+08:00   # 建议带时区，避免日期显示偏一天
4
description: 列表和搜索结果里显示的一句话简介。
5
image: ""          # 封面图，留空则不显示
6
tags: [Markdown, 写作]
7
category: 教程
8
draft: false       # true 则只在开发环境可见
9
pinned: false      # 置顶
10
comment: true      # 是否允许评论（需先启用评论系统）
11
---

文件名就是 URL：src/content/posts/markdown-guide.md 对应 /posts/markdown-guide/。

写作小贴士#

一篇只用一个 #（文章标题），正文从 ## 开始，目录更清爽；
代码块一定写语言，徽章和高亮都靠它；
长文章多用二级标题分段，读者可以顺着目录跳；
图片放 public/ 用绝对路径引用，避免相对路径在列表页失效；
写完跑一次 pnpm build，构建能过基本就没问题。

以上就是本站的 Markdown 写法。语法不用全记住，用到时回来查一眼就够了。

在七月的雨里开始

Tue, 27 Oct 2026 16:00:00 GMT

你好，我是左柒，欢迎来到「柒月の雨」。

这个名字来自我对七月雨天的偏爱：雨落下来时，世界像是暂时慢了一点。我想把这个小小的博客留给日常，记下读过的书、做过的事，以及那些还没有答案的问题。

不追赶更新，也不急着把每件事说清楚。先从认真观察开始，把值得记住的片刻写下来。愿每一场雨过后，都还留有一点温柔。

谢谢你路过。希望你在这里读得轻松。