📖 前置须知#

• 本站强制使用 pnpm（项目里配了 preinstall: only-allow pnpm，用 npm/yarn 会被拦下）
• 环境要求：Node ≥ 22.23，pnpm 11 系（package.json 里锁了 packageManager）
• 换机器/新克隆仓库后，先 pnpm install 装依赖，再跑下面命令

一、指令速查表#

二、内容脚手架#

1
pnpm new-post my-first-post        # 或中文名也行
2
pnpm new-post guide/xxx            # 支持子目录，自动建目录

1
---
2
title: my-first-post      # 记得改成真正标题
3
published: 2026-09-07     # 自动填今天
4
description: ''
5
tags: []
6
category: ''
7
draft: false
8
---

1
pnpm new-dynamic 今天的第一条碎碎念！
2
pnpm new-d            # new-dynamic 的别名

三、构建流水线（build 到底做了什么）#

pnpm build 不是单纯打包，是一整串流水线（按顺序执行）：

1
① 生成 GitHub 仓库卡片数据   → generate-github-card-data
2
② 生成图片占位 LQIP          → generate-lqips
3
③ 拉取封面数据（按配置）      → generate-vndb-covers
4
④ Astro 主构建               → astro build（产出 dist/）
5
⑤ 清理无用看板娘资源         → prune-pio-assets
6
⑥ 字体子集化                 → subset-fonts
7
⑦ 压缩内联脚本               → minify-inline-scripts
8
⑧ 生成站内搜索索引           → run-pagefind（Pagefind）

所以要理解两件事：

1. build 比较慢是正常的（要跑 8 步），别以为卡住了
2. 有几步（LQIP、字体、搜索索引）的产物是要提交进仓库的——本地跑过 build 后若提示这些文件有改动，记得一并 git add，否则线上构建用的数据可能旧

四、本地发布自检流程（每次发布前）#

1
pnpm dev        # ① 起本地，浏览器看效果（新文章在 posts 列表/系列里）
2
# —— 满意了 ——
3
pnpm build      # ② 生产构建，确保零报错通过（可选，改动纯内容时可用 dev 代替）
4
git add . && git commit -m "新增：xxx" && git push   # ③ 上线

只加/改 Markdown 内容时，dev 预览够了；动了配置/源码（.ts、.astro、组件）建议 pnpm check + pnpm build 都过一遍再推。

⚠️ 常见坑#

✅ 速记#

• 日常两条：pnpm dev 看效果，git 三连上线
• 写文章 pnpm new-post、发碎碎念 pnpm new-dynamic，让脚手架帮你填日期和模板
• 发布前：纯内容用 dev 预览；动了源码就 check + build 都过
• build 是 8 步流水线，慢是正常的；生成的数据要记得 commit