06-构建与脚本

项目共有 6 个 Node 脚本（scripts/*.js），其中 3 个作为 Vite 插件在构建期自动执行，1 个在 astro build 之后执行，2 个是手动命令。

1. 脚本总览

三个脚本会改写你的 markdown 源文件

ensure-post-slugs、update-post-updated、format-post-meta 都会写文件。建议：

• 先构建再提交（pnpm build && git commit），让自动改动一次进版本库；
• 若 CI 环境是只读文件系统，请关闭 siteConfig.autoUpdatePostUpdated（默认已关闭），并确保所有文章已有 slug。

2. scripts/ensure-post-slugs.js

2.1 职责

1. 扫描 src/content/posts/**/*.md；
2. 对没有 slug 的文章，用 title 生成拼音 slug 并写回文件；
3. 生成 .generated/post-index.json 供 rehypeRelativeLinks 使用。

2.2 参数

2.3 titleToSlug(title) 的 pinyin 参数

pinyin(String(title), {
  toneType: 'none',      // 不带声调：zhōng → zhong
  type: 'array',         // 返回数组，便于逐段处理
  nonZh: 'consecutive',  // 非中文连续保留成一段（英文单词不会被拆开）
  v: true,               // ü 转成 v（如 lü → lv）
})

随后：join(' ') → toLowerCase() → 非 [a-z0-9\s-] 变空格 → 空白与连续 - 折叠 → 去首尾 - → 空则 'post'。

2.4 查重与写入

控制台输出：[post-slug] slug filled: 文件名 -> slug

2.5 post-index.json 结构

[
  { "file": "posts/Markdown语法样例.md", "slug": "markdown-yu-fa-yang-li", "draft": false }
]

排序：按 file 字典序。内容未变化时不重写文件（对比后写入）。

手动运行：该文件没有直接运行入口（不像 generate-lqips.js 有 process.argv[1] 判断）。直接 node scripts/ensure-post-slugs.js 只会 import 模块——它仍然会执行模块顶层语句（mkdirSync 创建 .generated/ 目录），但不会扫描或改写任何文章。要单跑请调用工厂：

js复制

12

import { ensurePostSlugs } from './scripts/ensure-post-slugs.js'
ensurePostSlugs().buildStart()

3. scripts/generate-lqips.js

3.1 职责

扫描文章里的图片引用，采样 3 个主色，写入 .generated/lqips.json，供 rehypeImages 生成首屏渐变占位。

3.2 参数与环境变量

3.3 处理流程

1. 遍历 src/content/posts 下所有 .md

2. stripFencedCode()  去掉 ``` 围栏代码块（避免把示例里的图片语法当真）

3. stripInlineCode()  去掉 `行内代码`

4. 正则提取所有图片 src：
   - data: 开头        → 跳过
   - http(s):// 开头   → 作为远程 URL 目标（kind: 'url'）
   - / 或 # 或 scheme  → 跳过（public 资源与锚点不采样）
   - 其他（相对路径）  → 解析成本地绝对路径，算 contentImageKey

5. 跳过 existing 里已有的 key（增量）

6. 逐个处理：
   - 本地文件 → sharp 直接读
   - 远程 URL → fetch（8s 超时）→ Buffer

7. sampleColors(): resize(2,2,{fit:'fill'}).removeAlpha().raw()
   → 取字节 0..3、3..6、9..12 三个像素的 RGB 十六进制拼接（共 18 位）

8. 过滤掉已不在 targets 里的旧 key，按 key 排序后写文件

3.4 输出格式

值是18 位无分隔符的小写十六进制字符串（3 个像素的 RGB 依次直接拼接，没有空格）：

{
  "/content-images/883d9fc6f4cc516e.webp": "632d1b6a301b582816"
}

拆解：632d1b（第 1 像素）+ 6a301b（第 2 像素）+ 582816（第 4 像素）。

rehypeImages.ts 消费时按 18 位长度校验，切成 3 个颜色生成 linear-gradient(135deg, c1 0%, c2 50%, c3 100%)。

3.5 控制台输出与失败处理

3.6 常见操作

4. scripts/update-post-updated.js

4.1 职责

按文章文件的 mtime 同步 frontmatter 的 updated 字段。仅在 buildStart 执行（构建、dev 启动各一次），dev 运行中保存文章不会触发，避免保存过程中的中间态污染。

4.2 开关

astro.config.mjs：

updatePostUpdated({ enabled: siteConfig.autoUpdatePostUpdated })

enabled 为 false 时函数返回 null，Vite 忽略该插件（当前默认关闭）。

4.3 参数

4.4 状态文件与幂等机制

{
  "MarkDown元数据说明.md": { "mtime": 1788447321747, "stamp": "2026-09-03 22:55:21" }
}

mtime 是毫秒时间戳，stamp 是同一时刻的 UTC 时间字符串（用 getUTC* 格式化，不依赖构建机时区；示例取自仓库真实的 .generated/post-updated.json）。

为什么用「mtime 快照」而不是把 mtime 改回去？

源码注释解释得很清楚：写入 updated 本身会刷新文件 mtime，所以需要记录「写入后的 mtime」来判断是否被再次保存。

不能写完再把 mtime 改回原值——Git for Windows 的索引按秒比对 mtime，恢复后字节数相同的时间戳变更会被 git 误判为「未修改」，导致改动提交不上去。

4.5 写入位置

换行符沿用原文件。

控制台输出：[post-updated] 文件名 -> 2026-09-15 20:49:56（每篇一行）、[post-updated] synced N posts（汇总）。

4.6 启用建议

5. scripts/postbuild.js

5.1 职责（四件事，并行 + 串行结合）

main()
 ├─ 并行：spawn('pagefind', ['--site', 'dist'])        ← 生成站内搜索索引
 └─ 串行：遍历 dist/**/*.html
            ├─ minifyHtml()      压缩内联脚本（esbuild）
            └─ injectPreloads()  注入 modulepreload
 └─ 串行：trimKatexFonts()                             ← 删除 dist/_astro 里 KaTeX 的 ttf/woff，只留 woff2

5.2 参数

5.3 输出统计

[postbuild] minified N inline scripts, saved X KiB; injected M preload links (T/N HTML files touched)
[postbuild] trimmed K KaTeX font files (ttf/woff, woff2 kept), saved Y KiB
[postbuild] dist total A MiB (F files), _astro B KiB (G files)
[postbuild] top 5: <相对路径> <体积> | …

5.4 体积预算

预算实测与验证

V1.0.9 基线本地实测 dist total 6.3 MiB (122 files)、_astro 499.1 KiB (50 files)。触发告警的验证方式是临时把一个 58 MiB 文件放进 public/ 后构建：总量 64.3 MiB → 输出 budget exceeded 与 top 5 明细（首条即该文件），删除后重建恢复正常。计划书原写「6 MB 文件」是按更大的历史产物量估算，当前基线需约 54 MiB 以上才会越过 60 MiB 门槛。

5.5 失败处理

字体裁剪与 KaTeX 按需加载配套

文章页只在正文真的渲染出 .katex 时才动态 import('katex/dist/katex.min.css')（见 05-内容与Markdown.md）。官方 CSS 的 @font-face 按 woff2 → woff → ttf 排列，后两者只是老浏览器兜底，因此构建后直接删除，dist/_astro 里的 KaTeX 字体约 250 KiB。

5.4 失败处理

为什么需要 modulepreload 注入？

Vite 默认只对入口 chunk 输出 <link rel="modulepreload">，动态 import 的 chunk 依赖需要浏览器在运行时发现。injectPreloads 读取每个 module script 引用的 chunk，从里面的 __vite__mapDeps 数组解析出依赖列表，提前写进 <head>，从而减少瀑布式请求。

修改 pagefind.yml 后必须重新构建

pagefind 只在 postbuild.js 里被调用。改 pagefind.yml 后需要 pnpm build 才能反映到索引。

6. scripts/new-post.js

模板：

---
title: "{slug}"
slug:
index: 0
description: "一句话摘要"
category: "未分类"
tags: []
# 连载（同一主题 3 篇以上、需按顺序阅读）时才填写，零散文章留空：
# series: "系列名"
# series_order: 1
published: {当前 UTC 时间，YYYY-MM-DD HH:mm:ss}
---

从这里开始写作。

成功后打印 created: <绝对路径>。

7. scripts/format-post-meta.js

字段顺序规则

const ORDER = ['title', 'slug', 'index', 'description', 'category', 'tags', 'published']
const LAST  = ['updated', 'draft']

最终顺序 = ORDER 中存在的 → 其他未列出的自定义字段（保持原相对顺序）→ LAST 中存在的。

8. 构建产物结构

dist/
├── index.html                        # 首页（第 1 页）
├── 2/index.html 3/index.html …       # 首页分页（第 1 页除外）
├── 404.html
├── about/index.html
├── archive/index.html
├── categories/index.html
├── categories/{分类名}/index.html
├── tags/index.html
├── tags/{标签名}/index.html
├── friends/index.html
├── posts/{slug}/index.html
├── content-images/{sha1前16位}.{ext} # 文章图片
├── pagefind/                         # 搜索索引（postbuild 生成，以下为实测产物）
│   ├── pagefind.js                     # 检索入口（SearchModal 动态 import 的就是它）
│   ├── pagefind-ui.js  pagefind-ui.css  pagefind-highlight.js
│   ├── pagefind-modular-ui.js  pagefind-modular-ui.css
│   ├── pagefind-component-ui.js  pagefind-component-ui.css
│   ├── pagefind-entry.json  pagefind-worker.js  wasm.unknown.pagefind
│   ├── pagefind.{lang}_{hash}.pf_meta
│   ├── filter/    {lang}_{hash}.pf_filter
│   ├── fragment/  {lang}_{hash}.pf_fragment   # 注意：在子目录里
│   └── index/     {lang}_{hash}.pf_index      # 注意：在子目录里
├── rss.xml
├── robots.txt
├── sitemap-index.xml
├── sitemap-0.xml
├── _astro/                           # 带内容哈希的 JS/CSS
├── avatar.webp  logo.webp  favicon.ico
├── friends/logo.webp
└── music/                            # public/ 原样拷贝

8.1 缓存策略

本项目是纯静态产物，缓存由托管平台决定。全站只有 /_astro/ 与 /content-images/ 带内容哈希，其余资源路径固定——因此不能对所有资源用长缓存。

上表是「按路径分层」的原则，具体在哪个平台怎么填，由该平台的缓存配置入口决定。

content-images 的缓存陷阱

/content-images/{hash} 中 hash 只基于相对路径，不基于内容。且路由响应的 Cache-Control 是 max-age=31536000, immutable（一年）。

后果：替换 src/content/images/logo.webp 的内容但路径不变时，URL 也不变，已访问过的浏览器会长期使用旧图。

规避方式：改文件名（如 logo-v2.webp），或清理部署平台缓存。

8.2 HTML 后处理的具体变化

postbuild.js 会改写每个 HTML 文件：

9. 部署

9.1 环境要求

9.2 各平台

9.3 托管平台缓存与尾斜杠

更新说明.md 提到过一个真实问题：

在进行页面切换时发现了多次重复请求预取的问题，导致页面流量异常，经排查为预取请求与 Canonical URL 不一致造成的。将前端路由的缓存策略与托管平台（Cloudflare Pages）的 URL 规范严格对齐，现在已修复。

结论：全站 URL 统一使用尾斜杠形式（/posts/xxx/、/categories/xxx/）。localePath() 会自动补尾斜杠，但对含 . 的最后一段（如 rss.xml）不补（源码里 isFile 判断）。

若你换了托管平台且该平台默认去掉尾斜杠（或反之），需要保证 301 规则一致，否则 Swup 预取会产生大量重复请求。

10. 常用命令速查

推荐的本地工作流

pnpm new-post my-post        # 1. 新建
# 2. 写作
pnpm format-post-meta        # 3. 元数据排序
pnpm dev                     # 4. 预览
pnpm check && pnpm type-check # 5. 检查
pnpm build                   # 6. 构建（补 slug / LQIP / 搜索索引）
pnpm preview                 # 7. 验证 dist
git add -A && git commit     # 8. 提交（先 build 再 commit）

11. 构建问题排查表