DEV Community: lizhaopeng-cn

从零搭建个人技术博客 · 篇三：用 Claude Code 的 skill 和 command 接管博客增删改查

lizhaopeng-cn — Fri, 24 Apr 2026 16:31:21 +0000

这是"从零搭建个人技术博客"系列的第三篇。前两篇讲了怎么把站点跑起来、怎么把文章自动分发到 dev.to / Hashnode；这一篇往回退一步，聊写作流本身 —— 写/改/删一篇博客的动作太零碎了，想把它自动化掉。

本篇目标：用 Claude Code 的 slash command + skill 给 blog.xtuul.com 装一个"AI 管家"，任何目录下都能敲：

/blog new "pnpm workspace 踩坑"
/blog list 只看草稿
/blog edit setup-astro-cloudflare-astropaper 把踩坑第 4 条扩展一下
/blog delete some-old-post

不在本篇：主站搭建（篇一）和跨平台分发（篇二）。

为什么不用脚本

最朴素的方案是写几个 bash 脚本：new-post.sh、list-posts.sh、delete-post.sh。能用，但对我来说有三个硬伤：

frontmatter 的写入仍然要我自己想。脚本能填日期、slug、author，但 title / tags / description 这几个字段还是得我自己琢磨。AI 可以顺手把这几件事一起做了。
自然语言参数处理不了。我说"把篇一踩坑第 4 条扩展一下"，脚本怎么知道第 4 条在哪？Claude 能自己读文件理解结构。
跨会话上下文。 脚本不记得"我的博客在哪个目录、用什么 schema、风格是什么"；Claude Code 的 skill 可以把这些写进 SKILL.md，每次触发自动加载。

所以这次直接在 Claude Code 里做。

Slash command vs Skill

开动之前先理清两个概念。Claude Code 里能扩展命令的有两样：

	Slash command	Skill
位置	`~/.claude/commands/xxx.md` 或 `.claude/commands/xxx.md`	`~/.claude/skills/xxx/SKILL.md` 或 `.claude/skills/xxx/SKILL.md`
触发	只能显式 `/xxx`	`/xxx` 或 Claude 根据 description 自动匹配
结构	单文件	文件夹，可带 `templates/` `references/` `examples/` `scripts/`
长度	适合一段短 prompt	适合长 playbook（官方推荐 <2000 词）
组合	一个命令可以调用 skill	skill 可以调用其他 skill

简单说：skill 是 command 的超集。新写东西默认选 skill，除非只是"给我贴一段固定 prompt"。

但 /blog new 这种形态必须由 command 提供 —— skill 的 slash 名就是它自己的 name（比如 /blog-new），没法拆成 /blog + 子命令。所以最终方案是 command 做路由 + 四个 skill 做实现。

整体架构

                      用户输入 /blog <sub> [args]
                                │
                                ▼
            ┌──────────────────────────────────────┐
            │ ~/.claude/commands/blog.md （路由）  │
            │  - 解析 $ARGUMENTS 第一个 token      │
            │  - 分派到对应 skill                  │
            └────────────────┬─────────────────────┘
                             │
       ┌──────────┬──────────┼──────────┬──────────┐
       ▼          ▼          ▼          ▼
   blog-new   blog-list  blog-edit  blog-delete
       │          │          │          │
       └──────────┴────┬─────┴──────────┘
                       │ 按需加载
                       ▼
       ~/.claude/skills/blog-shared/
         ├── templates/post.md
         ├── references/frontmatter-schema.md
         └── examples/reference-article.md

blog.md（command）只做一件事：看 $ARGUMENTS 第一个词，转发给对应 skill。
四个 skill 各自是独立的 playbook，互不干扰。edit 和 delete 在 slug 为空时会调用 blog-list（skill 之间可以互相调）。
blog-shared 不是 skill，而是共享资源目录，放 frontmatter schema、正文模板、风格范文。所有 skill 都按需读它，不常驻上下文。

实现：command 薄壳

~/.claude/commands/blog.md 是一个带 YAML frontmatter 的 Markdown：

---
argument-hint: <new|list|edit|delete> [参数或自由文本]
description: xtuul-blog 博客文章增删改查入口。按第一个词分派到对应 skill。
allowed-tools: Read, Write, Edit, Bash, Glob, Grep
---

# /blog 路由

用户输入：`$ARGUMENTS`

## 解析规则

1. 把 `$ARGUMENTS` 按**第一个空白**切分：
   - 第一个 token → **子命令**（必须是 new/list/edit/delete 之一）
   - 剩余全部文本 → **自由参数**，**原样**透传给对应 skill

2. 子命令和参数之间只用空格，不识别 `:` `|` `-` `#` 等分隔符。
   含空格的标题/slug 用双引号包裹。

## 执行

- new    → 调用 Skill `blog-new`，透传剩余文本
- list   → 调用 Skill `blog-list`，透传剩余文本
- edit   → 调用 Skill `blog-edit`，透传剩余文本
- delete → 调用 Skill `blog-delete`，透传剩余文本
- 其他或空 → 输出用法说明，不自行推断

关键点：不自己设计任何分隔符，只用空格 + 引号 + 自然语言。Claude 自己解析。

实现：blog-new skill

~/.claude/skills/blog-new/SKILL.md：

---
name: blog-new
description: This skill should be used when the user asks to
  "write a new blog post", "draft an article", "新开一篇文章",
  "起草博客", or invokes `/blog new`. Creates a new markdown
  post under /Users/xtuul/projects/xtuul-blog/src/data/blog/
  following xtuul-blog's AstroPaper frontmatter schema.
  Does not touch git.
argument-hint: "[标题 或 主题描述]"
allowed-tools: Read, Write, Edit, Bash, Glob, Grep
---

# blog-new：起草一篇新文章

... 工作流 ...

description 是 router 的命根子。Claude 靠这段决定你说"新写一篇博客"要不要触发这个 skill。官方文档里强调三点：

第三人称：This skill should be used when...，不用 You should...
具体触发短语：把用户会怎么说列出来
中英文并列：触发短语中英文都写，命中率更高

body 里按祈使句写步骤：确定标题 → 生成 slug → 写 frontmatter → 写正文 → 写入文件 → 汇报。参数为空时追问用户"想写什么"，而不是自己编。

实现：blog-list / edit / delete

blog-list：Glob src/data/blog/**/*.md，读每个文件前 30 行 frontmatter，按 pubDatetime 降序出表格。支持自然语言过滤（"只看草稿"、"标签 astro"）。
blog-edit：第一个 token 作 slug，剩余作修改意图。slug 为空时调用 blog-list 让用户选 —— skill 之间互相调用是合法的，而且复用现成逻辑最干净。
blog-delete：强制二次确认。用户必须原样打出 确认删除 <slug> 才执行，回 y/是/删 一概不算。

为什么 delete 要这么死板

删除不走 git（本仓库 push 之前都在本地）。文件一旦 rm 就没了。
y 太容易手滑打出来，原样复述 slug 才能保证用户真的看清了要删哪篇。

共享资源：blog-shared

blog-shared 不是 skill —— 没有 SKILL.md，Claude 不会主动扫描它。它是普通文件夹：

~/.claude/skills/blog-shared/
├── templates/post.md                # 带 {{...}} 占位符的正文骨架
├── references/frontmatter-schema.md # 字段硬规则（必填、格式、示例）
└── examples/reference-article.md    # draft: true 的风格范文

在各 skill 的 ## Additional Resources 小节里显式引用绝对路径：

## Additional Resources

- `~/.claude/skills/blog-shared/references/frontmatter-schema.md` — frontmatter 字段硬规则
- `~/.claude/skills/blog-shared/templates/post.md` — 正文骨架模板
- `~/.claude/skills/blog-shared/examples/reference-article.md` — 风格范文

Claude 触发 skill 时，只加载 SKILL.md body；需要时才 Read 上面这三个资源。这就是官方说的 progressive disclosure：主文件轻量化，详细内容按需加载。

好处很实在：改 schema 只改一个文件，四个 skill 自动跟着更新；改风格范文也不会污染真实的 src/data/blog/。

项目级 vs 用户级

Claude Code 支持两个位置：

位置	作用域	何时用
`<repo>/.claude/`	仅该仓库工作目录下生效	和仓库强耦合的命令；团队共享
`~/.claude/`	全局，任意目录都能用	个人工具、跨仓库可复用

两份同名会项目级覆盖用户级。

我最开始放在项目级，结果发现两个问题：

必须 cd ~/projects/xtuul-blog && claude 才能用 /blog，在桌面/下载目录里想顺手开一篇博客就不行。
GitHub 仓库里有 .claude/ 目录会被当成项目文件同步，别的设备或者协作者 clone 下来就自动启用了，不符合"这是我个人的工具"的定位。

所以搬到了用户级 ~/.claude/，并把 SKILL.md 里所有 src/data/blog/... 相对路径全部改成绝对路径 /Users/xtuul/projects/xtuul-blog/src/data/blog/...。代价是这套 skill 只能我这台机器用，但对我来说就是自己用，刚好。

踩过的坑

/blog 首次调用报 Unknown command。Claude Code 只在会话启动时扫描 commands 和 skills 目录。新建/搬迁文件后，必须重启 Claude Code 才能识别，/reload 之类的软重载不够。
项目级和用户级同名冲突。我忘了删项目级的旧版，新会话里仍然跑的是旧的相对路径 SKILL.md。删掉项目级的 .claude/ 后正常。
description 写得像文档就失效。第一版我写了 用于管理 xtuul-blog 的博客文章，Claude 根本不匹配自然语言请求。改成 This skill should be used when the user asks to "write a new blog post", "新开一篇文章", or invokes /blog new 之后命中率立马上去。description 是触发条件而不是文档，越具体越好。
skill body 超 2000 词后 Claude 抓不住重点。第一版 blog-new 把 schema 字段表、风格约束全塞进去，400 多行。后来按官方推荐拆成 SKILL.md（只写流程）+ references/frontmatter-schema.md（字段表）+ templates/post.md（骨架），主文件压到 100 多行，生成质量明显好转。
skill 内的路径必须是绝对路径。只要没法保证用户一直在某个 CWD，相对路径都是坑。我在 SKILL.md 里硬编码了 /Users/xtuul/projects/xtuul-blog/，同时在每个 skill 开头加了一段"路径（硬编码绝对路径，不依赖 CWD）"说明 —— 未来换机器要改的地方集中在一处。

小结

架构：commands/blog.md 做路由薄壳，四个独立 skill 做实现，一个 blog-shared 目录放共享资源
描述：skill 的 description 用第三人称 + 具体中英文触发短语，直接决定 router 命中率
篇幅：SKILL.md 控制在 <2000 词，详细内容走 references/ 和 templates/，按需加载
路径：全局 skill 里一律用绝对路径，不依赖当前工作目录
不碰 git：所有 skill 都禁 git 命令，最终 push 前人工 review —— 博客的每一次提交都值得亲眼看一遍

下一步想把 blog-new 再增强一下：支持传入参考文章 URL 或本地 markdown 路径，Claude 读完后再写。这样写技术选型类文章时就不用我一段段复制粘贴上下文。

至此系列三篇闭环了：篇一搭主站，篇二接分发，篇三管写作流。以后写一篇博客就是打开任意终端敲 /blog new 主题 → Claude 起稿 → 我修 → git push → workflow 自动同步到所有海外平台。整条链路零运维、按需生效，对一个人博客来说刚刚好。

从零搭建个人技术博客 · 篇二：跨平台自动分发

lizhaopeng-cn — Fri, 24 Apr 2026 11:52:15 +0000

篇一是主站（blog.xtuul.com）本身的搭建，篇三是写作流（/blog new 这套 skill）。这一篇填篇二：文章写完 push 上去之后，自动同步到其他平台，不用我手动复制粘贴。

本篇讲什么：一个具体的 GitHub Actions + TypeScript 小工具，push 到 main 就把 src/data/blog/*.md 发到 dev.to、Hashnode、博客园，首发拿到平台 id，之后再推就是 update 而不是重发。

本篇不讲什么：具体某个平台的 API 怎么接（RTFM 的活），以及为什么最后国内平台一个没留。最后一节会单独讲这个。

要解决的问题

主站在 Cloudflare Pages 上，但一篇文章想被人看到，光靠 Google 搜索和主站 RSS 远远不够。常见做法有三种：

只在主站写，其他平台空着——SEO 和流量都吃亏
每篇写完手动复制粘贴到其他平台——第 3 篇之后我就会放弃
写完一次 push，代码自动同步——这篇要做的事

关键约束：

主站是 canonical：dev.to / Hashnode 都支持声明 canonical_url，明确告诉搜索引擎"原文在 blog.xtuul.com"，这样即使文章被多平台收录，SEO 权重也不会被稀释
幂等：同一篇文章推两次不能变成两篇。要走"首发→拿到 id→以后用 id update"的路径
一个平台挂不阻塞别的：博客园风控拦了不能让 dev.to 也发不出去

整体架构

先把地图画出来：

┌───────────────────────────────────────────────────────────┐
│ 本地写作：/blog new → src/data/blog/<slug>.md             │
│                                                           │
│                    git push origin main                   │
│                            │                              │
└────────────────────────────┼──────────────────────────────┘
                             │
                             ▼
┌───────────────────────────────────────────────────────────┐
│ GitHub Actions: .github/workflows/syndicate.yml           │
│                                                           │
│   on.push.paths: [src/data/blog/**/*.md]                  │
│     │                                                     │
│     ▼                                                     │
│   pnpm dlx tsx scripts/crosspost/index.ts                 │
│     │                                                     │
│     │──► diff HEAD~1..HEAD 或 workflow_dispatch 入参     │
│     │──► 对每篇改动的 .md：                              │
│     │     ├─ load frontmatter                             │
│     │     ├─ if draft: skip                               │
│     │     ├─ for each platform (devto/hashnode/cnblogs): │
│     │     │    ├─ 已有 id → update                       │
│     │     │    └─ 无 id   → create, 拿 id+url           │
│     │     └─ 写回 frontmatter.crosspost.<platform>       │
│     └──► git add / commit / push [skip ci]               │
└───────────────────────────────────────────────────────────┘

代码都在 scripts/crosspost/：

scripts/crosspost/
├── index.ts              # 入口，解析 diff，调度每个 publisher
├── lib/
│   ├── frontmatter.ts    # 手写的极简 YAML parse/stringify
│   └── types.ts          # Post / Publisher / PublishResult 接口
└── platforms/
    ├── devto.ts          # POST /api/articles
    ├── hashnode.ts       # GraphQL mutation publishPost / updatePost
    └── cnblogs.ts        # MetaWeblog XML-RPC

设计决定与权衡

1. 文件就是状态，没有外部数据库

frontmatter 里直接加一个 crosspost 字段：

crosspost:
  devto:
    id: 3544836
    url: "https://dev.to/lizhaopengcn/xxx"
  hashnode:
    id: 69eb1b54bada4a44e9c589e2
    url: "https://xtuul.hashnode.dev/xxx"

第一次推文章：三个字段都不存在 → 脚本走 create → 拿到 id 和 url 写回 frontmatter → auto-commit 回 main。

第二次推同一篇：frontmatter 里已经有 id → 脚本走 update，不会产生重复文章。

为什么不用 SQLite / KV：这是个一人博客。加一个外部存储等于多一个要备份、要恢复、要对齐状态的东西。文章本身已经在 git 里了，id 就放旁边，状态和内容原子地一起 commit。

2. canonical URL 固定指向主站

每次发文章时都显式带 canonical_url: https://blog.xtuul.com/posts/<slug>/，哪怕主站还没上线那篇。

dev.to：支持 canonical_url 字段，显示"Originally published at blog.xtuul.com"
Hashnode：originalArticleURL 字段，行为一样
博客园：MetaWeblog 没 canonical 这个字段，只能在正文开头手动加一行"原文："（实际上最后没做，原因后面说）

3. 每个 publisher 实现同一个接口

export interface Publisher {
  name: "devto" | "hashnode" | "cnblogs";
  enabled: () => boolean;            // 环境变量齐了就 enable
  publish: (post: Post) => Promise<PublishResult>;
}

index.ts 不关心具体平台怎么调 API，只负责：挑出 enabled 的平台、串行跑、把 PublishResult 写回 frontmatter、最后 git commit。每加一个平台只要写一个新的 platforms/<name>.ts。

4. per-post 串行、per-platform 独立

一篇文章里三个平台串行发（dev.to → Hashnode → 博客园），每个都单独 try/catch。任意一个失败不阻塞其他平台，也不阻塞下一篇文章。所有结果最后统一打印。

for (const post of posts) {
  for (const platform of platforms) {
    try {
      const result = await platform.publish(post);
      writeback(post, result);
    } catch (err) {
      console.error(`✗ ${platform.name} ${action}: ${err.message}`);
    }
  }
}

踩过的坑

真写出来之后，前后一共掉坑里三次。记下来。

坑 1：Astro 的 `z.date()` 不接受带引号的 ISO 字符串

写完代码本地测试通过，push 到 main 之后 Cloudflare Pages 构建挂了：

pubDatetime: Expected type "date", received "string"

问题出在 "脚本回写 frontmatter" 这一步。Astro content collection 的 schema 里 pubDatetime 是 z.date()，它要求 YAML 里是裸的 timestamp，不能是字符串：

# 这样 Astro 能识别为 Date
pubDatetime: 2026-04-24T19:50:10+08:00

# 这样 Astro 会当 string，schema 直接挂
pubDatetime: "2026-04-24T19:50:10+08:00"

我的 YAML stringify 函数 "遇到包含 : 或其他特殊字符的字符串就加引号"，ISO 时间戳正好命中。修法是给日期类字段开白名单，裸输出：

const DATETIME_KEYS = new Set(["pubDatetime", "modDatetime"]);

function emit(key, value) {
  if (DATETIME_KEYS.has(key) && typeof value === "string") {
    return `${key}: ${value}`;   // 不加引号
  }
  // ...其他走通用 stringify
}

这种"主站和同步脚本之间有个看不见的契约"的坑，本地开发过程中完全不会碰到，只有 push 之后 Cloudflare 那边才会炸。CI 流水线一定要在两边都跑一次才能发现。

坑 2：自己写的 YAML parser 不支持嵌套对象

上面那段 crosspost.devto.id 是嵌套两层的。一开始我图省事，手写了个 20 行的 YAML parser，只支持"key: value"和列表。结果第二次推文章时：

✗ devto create: Canonical url has already been taken
✓ hashnode create → xxx-1-1     ← 注意 "-1-1"

脚本没读到已有的 id，当成全新文章再发了一遍。dev.to 靠 canonical 查重、直接 422 拒绝；但 Hashnode 完全不查重，默默给新文章一个 -1、-1-1 的递增 slug，看起来"发布成功"，实际上我的博客上重复文章越堆越多。

后来把 parser 换成支持递归缩进的版本，才读得出嵌套结构。教训：

不要在状态机关上图省事自己造轮子。要省就连嵌套都别用（比如把 crosspost_devto_id 拍平成一级 key），要嵌套就用 js-yaml。
"默默成功"比"显式失败"可怕得多。Hashnode 这种接口设计等于在地雷区里埋了一个脸朝下的地雷。

坑 3：博客园把 GitHub Actions 的出站 IP 风控了

这是让我最后放弃国内平台的直接原因，值得单拎一节。

为什么最后没做国内平台

本来清单上是：dev.to + Hashnode + 博客园。三个平台的 API 都接好了、secret 也配好了、本地 dry-run 全过。推上去跑 workflow：

✓ devto update → https://dev.to/...
✓ hashnode update → https://xtuul.hashnode.dev/...
✗ cnblogs create: HTTP 500 (empty body)

第一反应：鉴权有问题？XML-RPC 包错了？字段不全？

挨个验证：

在本地跑 curl，同样的 token、同样的 username、同样的 endpoint，打一条最小的 metaWeblog.newPost 过去。200，返回 postid，完美。
在本地跑脚本，用 loadPost 读真实文章、构造和 Actions 里字节级完全相同的 XML，再 curl 发出去。又是 200，postid 正常返回。
回到 Actions，一模一样的代码、一模一样的 secret。仍然 HTTP 500，body 空。

排查逻辑很简单——如果鉴权或内容有问题，博客园会返回 <fault> 带具体 faultString；400、401、404 也都会有 body 说明原因。500 + 空 body 是非常特殊的组合：请求根本没到业务层，而是在前置的网关/WAF 上就被掐掉了。

rpc.cnblogs.com 的网关对 Azure westus 的 IP 段做了风控。GitHub Actions 的 runner 正好在那里。对 "Azure IP 对国内内容平台的出站连接" 这件事有过了解的人应该都见过类似剧情——十年来这类平台对海外云的 IP 越来越敏感。

没有干净的解法：

在 runner 上装代理 → 需要一台国内机器当出口，相当于给博客同步这件事凭空加一台要维护的 VPS，零运维的前提破了
换平台官方 SDK → 博客园官方 API 只有 MetaWeblog，没有别的公开协议
用 Puppeteer 模拟浏览器 → CI 里跑无头 Chrome 要装 100MB 依赖、要在 CI 内完成扫码/验证码，越想越不值
调研了一下其他国内平台（掘金、CSDN、SegmentFault）：要么同样的 IP 风控，要么没有公开 API，抓包出来的接口几个月就会变一次

我算了下账：

方案	搭建成本	维护成本	稳定性
加一台国内中转机	半天	每月续费 + 偶尔抢救	中
Puppeteer 方案	2~3 天	平台前端一改就挂，每平台每季度至少修一次	中
浏览器插件（ArtiPub 之流）	装一下	低（但手动点击，不算自动化）	高但不自动
全部放弃国内平台	0	0	—

对一个个人博客来说，我不做国内平台的"机会成本" 是：国内读者来主站（或 dev.to / Hashnode 的英文版）的时候少看到一点入口。可以接受。

继续做国内平台的"直接成本" 是：一台新机器 or 一套会定期 rot 的 Puppeteer 代码。不能接受。

所以：

scripts/crosspost/platforms/cnblogs.ts 代码留着，以后哪天有国内机器了直接改 endpoint 就能用
workflow 里留着 CNBLOGS_* 的 secret 判断——没配就跳过，什么都不会打印
目前跑 workflow 只会看到 dev.to 和 Hashnode 成功

当前成品

workflow 配置

.github/workflows/syndicate.yml 的骨架：

name: Syndicate

on:
  push:
    branches: [main]
    paths:
      - "src/data/blog/**/*.md"
  workflow_dispatch:
    inputs:
      files:
        description: "要同步的文件路径（空格分隔），留空=diff"
        required: false

concurrency:
  group: syndicate
  cancel-in-progress: false

jobs:
  crosspost:
    runs-on: ubuntu-24.04
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 2 }
      # ... setup pnpm / node
      - run: pnpm dlx tsx scripts/crosspost/index.ts ${{ inputs.files }}
        env:
          DEVTO_API_KEY: ${{ secrets.DEVTO_API_KEY }}
          HASHNODE_API_KEY: ${{ secrets.HASHNODE_API_KEY }}
          HASHNODE_PUBLICATION_ID: ${{ secrets.HASHNODE_PUBLICATION_ID }}
          SITE_BASE: https://blog.xtuul.com/
      # ... auto-commit if frontmatter changed

关键点：

paths 过滤让"我只改了 README 或配置"的 push 不触发
concurrency 防止连续两次 push 引起竞态（前一次还没写回 id，后一次又 create 一遍）
fetch-depth: 2 才够算 HEAD~1..HEAD 的 diff
permissions: contents: write 才允许回写 commit

每篇文章的状态

前两篇文章现在的 frontmatter 尾部看起来是这样：

crosspost:
  devto:
    id: 3544836
    url: "https://dev.to/lizhaopengcn/..."
  hashnode:
    id: 69eb1b54bada4a44e9c589e2
    url: "https://xtuul.hashnode.dev/..."

以后任何一篇我改了正文 push 上去，脚本看到已有 id，走 update 路径，平台上直接原地更新，url 不变、评论不丢。

小结

这篇的主题本来应该是"跨平台分发"，实际结果是"跨两个海外平台分发 + 一篇国内平台劝退录"。

一些可以带走的结论：

canonical URL 必须显式。主站永远是 source of truth，分发只是副本。
幂等靠 id，不靠 title/slug 做匹配。id 写回 frontmatter，和文章原子地一起 commit，不要引入外部状态。
"默默成功"的平台要特别警惕。dev.to 的 422 比 Hashnode 的 -1-1 slug 友好得多。
零运维的门槛是"不需要我再额外养任何一台机器"。一旦为了一个副功能要上国内 VPS 或浏览器自动化，整个系统的维护成本结构就变了。

篇四还没想好，大概会写主站接入 Umami、或者 AstroPaper 主题的几处魔改。

从零搭建个人技术博客 · 篇一：Astro + Cloudflare Pages + AstroPaper

lizhaopeng-cn — Fri, 24 Apr 2026 07:27:15 +0000

这是"从零搭建个人技术博客"系列的第一篇，记录我把 blog.xtuul.com 从无到有跑起来的完整过程 —— 技术选型、架构、操作步骤、踩到的坑。

本篇目标：用最小的维护成本搭一个快、干净、免费、有个人品牌感的主站。
不在本篇：跨平台自动分发（dev.to / Hashnode / 掘金 / 公众号）—— 放到后续篇章。

整体架构与选型

最终架构

         Claude Code（在本地生成 Markdown）
                       │
                       ▼
          src/data/blog/xxx.md（Git 跟踪）
                       │  push
                       ▼
           GitHub: lizhaopeng-cn/xtuul-blog
                       │  webhook
                       ▼
              Cloudflare Pages（自动构建）
                       │
                       ▼
          blog.xtuul.com（HTTPS + 全球 CDN）
             + Cloudflare Web Analytics（站长后台）
             + 不蒜子（页面可见计数）
             + Giscus（GitHub Discussions 评论）

一个仓库、一次 push、全自动部署。没有服务器、没有数据库、没有后台。

为什么选这套组合

层	选型	为什么
框架	Astro	静态输出、零 JS 默认、支持 MD/MDX、生态比 Hugo 现代、比 Next.js 轻
主题	AstroPaper	Lighthouse 100、自带明暗主题/搜索/标签/RSS/sitemap、TypeScript + Tailwind
托管	Cloudflare Pages	免费、自带 CDN 和 HTTPS、与 Cloudflare DNS 天然融合
DNS	Cloudflare	域名本来就在这里，一条 CNAME 都省了
包管理	pnpm	磁盘效率和 monorepo 友好；AstroPaper 官方模板就是 pnpm

排除项（为什么不选它们）

WordPress —— 要维护数据库、安全补丁、主机账单。静态博客是一次性工作，没必要。
Hexo / VuePress —— 能用但生态趋冷，主题更新慢。
Next.js —— 大炮打蚊子。博客不需要 SSR / Server Components。
Vercel —— 也不错，但国内访问不如 Cloudflare 稳，且 DNS 不在一处。
GitHub Pages —— 无 CDN、自定义域名要额外配置、国内访问慢。

前置条件

一个顶级域名（我用的 xtuul.com），已托管在 Cloudflare
本地装好：node (20+)、pnpm、git、gh（GitHub CLI）
一个 GitHub 账号，gh auth login 登录过

验证：

node -v          # v20 以上
pnpm -v
git --version
gh auth status

第一步：用 pnpm 脚手架生成 AstroPaper

全程只用 pnpm。AstroPaper 官方模板、本地开发、Cloudflare Pages 构建命令都统一到 pnpm，保证只有一份 pnpm-lock.yaml，后面构建稳定性会省很多事。

cd ~/projects
pnpm create astro@latest xtuul-blog \
  --template satnaing/astro-paper \
  --install \
  --skip-houston \
  --no-git \
  --yes

参数含义：

--template satnaing/astro-paper 直接以 AstroPaper 作为起点
--install 自动 pnpm install
--no-git 先不初始化 git，后面手动推（避免 Astro 默认 commit 污染历史）
--skip-houston / --yes 跳过交互式问答

完成后：

cd xtuul-blog
pnpm dev
# 浏览器访问 http://localhost:4321/ 应该能看到 AstroPaper 默认主题

第二步：品牌化与本地化

AstroPaper 的全站配置集中在 src/config.ts。把站点信息改成自己的：

// src/config.ts
export const SITE = {
  website: "https://blog.xtuul.com/",
  author: "Xtuul",
  profile: "https://github.com/lizhaopeng-cn",
  desc: "记录 AI、编程、自动化和个人项目。",
  title: "Xtuul Blog",
  ogImage: "astropaper-og.jpg",
  lightAndDarkMode: true,
  postPerIndex: 4,
  postPerPage: 4,
  scheduledPostMargin: 15 * 60 * 1000,
  showArchives: true,
  showBackButton: true,
  editPost: { enabled: false, text: "", url: "" },
  dynamicOgImage: true,
  dir: "ltr",
  lang: "zh-CN",
  timezone: "Asia/Shanghai",
} as const;

社交链接在 src/constants.ts，默认带了 X / LinkedIn / WhatsApp 等，按需裁剪。我只留 GitHub + 邮箱：

export const SOCIALS: Social[] = [
  { name: "GitHub", href: "https://github.com/lizhaopeng-cn", linkTitle: `${SITE.title} on GitHub`, icon: IconGitHub },
  { name: "Mail", href: "mailto:xtuul@xtuul.com", linkTitle: `Send an email to ${SITE.title}`, icon: IconMail },
] as const;

导航栏中文化

src/components/Header.astro 里把 Posts / Tags / About / Archives / Search 改成 文章 / 标签 / 关于 / 归档 / 搜索，Skip to content 改成 跳转到正文。

默认深色模式

src/layouts/Layout.astro 里找到这段内联脚本，把空字符串改成 "dark"：

const initialColorScheme = "dark"; // 之前是 ""，现在强制首访深色

lightAndDarkMode: true 保留，用户点顶部月亮/太阳按钮仍可切换。

验证本地构建

pnpm build

看到 Finished in Xs 并且没有红色错误，就说明配置改动都是合法的。

第三步：推送到 GitHub

cd ~/projects/xtuul-blog
git init
git add -A
git commit -m "initial commit: Xtuul Blog on AstroPaper"

# 用 gh 一条命令建 public 仓库 + 推送
gh repo create xtuul-blog --public --source=. --remote=origin --push

public 还是 private？ 博客内容公开，仓库也建议 public。public 仓库的 GitHub Actions 额度是无限的，private 每月只有 2000 分钟，这在后续加自动分发时会成为实际差别。

第四步：Cloudflare Pages 首次部署

Dashboard → Workers & Pages → Create → Pages → Connect to Git。

选仓库 lizhaopeng-cn/xtuul-blog
Framework preset: Astro
Build command: pnpm install --frozen-lockfile && pnpm build
Build output directory: dist
Environment variables（Production）: NODE_VERSION = 22（纯文本）

为什么显式写 pnpm 命令：Cloudflare Pages 默认根据 lockfile 探测包管理器，大多数情况会对，但偶尔会 fallback 到 npm。显式写最稳。

为什么固定 Node 版本：构建容器默认 Node 可能是 18，而新版 Astro 要求 20+。指定 22 是目前的 LTS，最保险。

点 Save and Deploy，1–3 分钟后应该看到绿色 Success。

第五步：绑定自定义域名

Pages 项目 → Custom domains → Set up a custom domain → 填 blog.xtuul.com。

因为域名本来就在 Cloudflare，它会自动在 DNS 区加一条 CNAME：

blog    CNAME    xtuul-blog.pages.dev    (Proxied)

等几十秒证书签发完成，https://blog.xtuul.com/ 就活了。

以后发布新文章的流程

文章存放位置：src/data/blog/（文件名即 URL slug）。

标准 frontmatter 模板

---
author: Xtuul
pubDatetime: 2026-04-22T10:30:00+08:00
title: "文章标题"
slug: article-slug
featured: false   # true 显示在首页"精选文章"
draft: false      # true 不会发布
tags:
  - tag1
  - tag2
description: 一句话摘要（会出现在文章卡片和 SEO 描述里）
---

正文...

三步发布

# 1. 写文章（放到 src/data/blog/xxx.md）
# 2. 本地预览（可选）
pnpm dev

# 3. 提交推送
git add src/data/blog/xxx.md
git commit -m "post: 标题"
git push

Cloudflare Pages 监听到 push，自动构建 + 部署，从 push 到线上可见通常 2 分钟内。

写作期间的小技巧

draft: true → 线上看不到但本地能预览，适合攒稿
featured: true → 首页置顶
本地改 src/config.ts / 组件时 pnpm dev 会热更新

用 Claude Code 直接产出 Markdown

上面的发布流程能跑，但从 0 到一篇成稿还是我自己打字。博客更顺手的工作流是：

一句话需求 → Claude Code 写到 src/data/blog/xxx.md → 本地预览 → git push

我写博客的时候直接在仓库根目录开 Claude Code：

cd ~/projects/xtuul-blog
claude

然后一句话命题作文：

"写一篇新文章放到 src/data/blog/setup-astro-cloudflare-astropaper.md，主题是从零搭建个人技术博客，选型是 Astro + Cloudflare Pages + AstroPaper，frontmatter 用 author: Xtuul、pubDatetime 用当前时间、featured: true、tags 给 astro/cloudflare/astropaper/blog/devops。"

Claude Code 直接落盘成 .md 文件，本地 pnpm dev 实时预览，不满意继续对话改（"第二部分太啰嗦，合并到第一部分"），满意了就 commit + push。

为什么要这样写，而不是甩一个"帮我写博客"

几点经验：

文件路径写死。明确告诉 Claude 写到哪个文件、slug 是什么，它就会直接 Write 工具落盘，不会先在对话里生成一坨让你复制。
frontmatter 所有字段都写死。作者、tags、是否 featured、是否 draft。Claude 对 AstroPaper 的 frontmatter schema 没先验知识，不写死它会漏字段或乱填。
技术选型和事实由你给，Claude 负责组织行文和代码块。让 Claude 自由发挥容易出"正确但不是你的"内容——你的博客是写给你自己的受众，口吻、技术偏好、踩坑细节都得自己提供。
分多轮迭代。先让它写大纲，再写某一节正文，再让它把某个代码块换成更简洁的版本。一次性让它写完 2000 字通常质量不如分块。

工作流的好处

不离开编辑器：写、改、预览、提交在一个 shell 里完成，不用在对话窗口和编辑器之间来回切。
可追溯：所有改动都是 git diff，不好回滚就 git checkout --。
自动化友好：以后可以把"发布到 dev.to / Hashnode / 掘金"也交给 Claude Code 跑 MCP 调用外部 API，这是篇二要做的事。

第六步：接入访问统计与评论

主站能跑之后，马上会想要两件事：这篇文章有多少人看过、读者能不能留言。我接了三个互不重叠的服务：

需求	方案	数据给谁看
站长看流量后台（趋势、地理分布、Referer）	Cloudflare Web Analytics	我，在 CF Dashboard
页面上可见的计数（页脚总 PV/UV、文章阅读量）	不蒜子	所有访客
评论系统	Giscus（基于 GitHub Discussions）	所有访客，数据在我仓库

全部免费、零后端。

6.1 Cloudflare Web Analytics

Dashboard → Analytics & Logs → Web Analytics → Add a site → 选 Manual（手动 JS 片段），会拿到一段：

<script defer src="https://static.cloudflareinsights.com/beacon.min.js"
        data-cf-beacon='{"token": "YOUR_TOKEN"}'></script>

把它放到 src/layouts/Layout.astro 的 <head> 里（<ClientRouter /> 之后），全站自动上报。

注意：

后台数据只有自己看。访客看不到任何数字，不蒜子才是"前台展示"。
每个 site 一个独立 token。我 xtuul.com 是橙云走自动统计，blog.xtuul.com 是 Pages 自带的灰云（Pages 的自定义域都是灰云，这是正常的，不用改橙），走不到自动统计，所以单独为它生成了 token。
如果你还想统计主站就再加一个 site、给主站页面嵌入对应 token 的片段即可，数据不会互相混。

6.2 不蒜子：页面可见计数

不蒜子是国内开发者博客最常用的极简计数器，一个 script + 三个约定的 span id：

<!-- 站点总 PV -->
<span id="busuanzi_container_site_pv">
  总访问量 <span id="busuanzi_value_site_pv"></span> 次
</span>

<!-- 站点 UV -->
<span id="busuanzi_container_site_uv">
  访客数 <span id="busuanzi_value_site_uv"></span> 人
</span>

<!-- 当前文章 PV -->
<span id="busuanzi_container_page_pv">
  阅读量 <span id="busuanzi_value_page_pv"></span> 次
</span>

脚本只有三行：

<script async defer
  src="https://busuanzi.ibruce.info/busuanzi/2.3/busuanzi.pure.mini.js"></script>

三个关键细节：

容器默认 display:none。不蒜子脚本拿到数据后会把 busuanzi_container_* 显示出来。如果不默认隐藏，脚本返回前会看到 访客数：人 这种裸文案，很丑。
Astro ClientRouter 切页脚本不会重跑。AstroPaper 用 <ClientRouter /> 做无刷新页面切换，<script src> 只在首次加载时执行一次，切换到下一篇文章的 page_pv 不会刷新。解决：在 astro:page-load 事件里重新注入脚本。
只在 astro:page-load 里注入，不要在 IIFE 里再调一次。否则页面首次加载时首次 IIFE + astro:page-load 事件会各发一次 JSONP，PV +2。

最后得到的是这样一段：

<script is:inline>
  document.addEventListener("astro:page-load", () => {
    // 清掉上次注入的脚本标签
    document.querySelectorAll("script[data-busuanzi]")
      .forEach(node => node.remove());
    const s = document.createElement("script");
    s.src = "https://busuanzi.ibruce.info/busuanzi/2.3/busuanzi.pure.mini.js";
    s.async = true;
    s.defer = true;
    s.setAttribute("data-busuanzi", "1");
    document.body.appendChild(s);
  });
</script>

不蒜子的局限（被很多教程模糊带过）：

只有 page_pv，没有 page_uv。想知道某篇文章有多少独立访客——不蒜子做不到，只能自己上 Cloudflare Workers + KV。
本地 localhost:4321 的数字是全球所有本地开发者共享的，动辄几万几十万，这是正常现象，上线到真实域名后从 0 开始计数。

6.3 Giscus：基于 GitHub Discussions 的评论

Giscus 把评论直接挂在你仓库的 GitHub Discussions 上。好处：

评论数据在你自己仓库，跟着仓库迁移走
访客用 GitHub 账号登录，天然过滤机器人
支持 reaction、Markdown、代码块
不要你跑任何后端

准备工作：

仓库开启 Discussions：Settings → Features → Discussions ✅
安装 giscus GitHub App 到仓库
去 giscus.app 配置向导，选 repo + discussion category（建议用 Announcements 这种受限分类，避免无关讨论），拿到一段 <script>

在 Astro 里包装成组件，关键要点有两个：

主题要跟站内明暗同步。Giscus 默认 preferred_color_scheme 跟系统，但 AstroPaper 允许用户手动切换 <html data-theme="...">，两者会对不上。要用 MutationObserver 监听 data-theme 变化，通过 postMessage 告诉 giscus iframe 换皮。
ClientRouter 切页要重新挂载。否则上一篇文章的评论残留在下一篇。

简化后的组件（完整版在仓库 src/components/Giscus.astro）：

<section id="giscus-container">
  <h2>评论</h2>
  <div id="giscus"></div>
</section>

<script is:inline data-astro-rerun>
  (function () {
    const container = document.getElementById("giscus");
    if (!container) return;
    container.innerHTML = ""; // 清理上一页残留

    function currentGiscusTheme() {
      return document.documentElement.getAttribute("data-theme") === "dark"
        ? "noborder_dark"
        : "noborder_light";
    }

    const s = document.createElement("script");
    s.src = "https://giscus.app/client.js";
    s.setAttribute("data-repo", "lizhaopeng-cn/xtuul-blog");
    s.setAttribute("data-repo-id", "...");
    s.setAttribute("data-category", "Announcements");
    s.setAttribute("data-category-id", "...");
    s.setAttribute("data-mapping", "pathname");
    s.setAttribute("data-theme", currentGiscusTheme());
    s.setAttribute("data-lang", "zh-CN");
    s.setAttribute("data-loading", "lazy");
    s.setAttribute("crossorigin", "anonymous");
    s.async = true;
    container.appendChild(s);

    // 站内主题切换时通知 iframe 同步
    new MutationObserver(() => {
      const frame = document.querySelector("iframe.giscus-frame");
      frame?.contentWindow?.postMessage(
        { giscus: { setConfig: { theme: currentGiscusTheme() } } },
        "https://giscus.app"
      );
    }).observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["data-theme"],
    });
  })();
</script>

然后在 src/layouts/PostDetails.astro 里 <Giscus /> 一行就挂上了。

踩过的坑

Cloudflare Pages 不改构建命令：默认的 npm run build 在项目只有 pnpm-lock.yaml 时会因为缺 package-lock.json 失败。必须显式改成 pnpm install --frozen-lockfile && pnpm build。
Node 版本：不指定 NODE_VERSION，构建容器可能给你 18，新版 Astro 直接报错。
默认主题探测：AstroPaper 默认是跟随系统 prefers-color-scheme。想强制首次深色，改 Layout.astro 里的 initialColorScheme = "dark"，别去动 lightAndDarkMode（那个是是否允许切换的开关）。
不蒜子在 localhost:4321 上数字离谱：不蒜子按域名隔离，localhost 被所有开发者共享，本地看到几万几十万是正常的。上线到 blog.xtuul.com 才从 0 开始独立计数。
Giscus 不跟随 AstroPaper 主题切换：Giscus 默认用 preferred_color_scheme 跟系统，但 AstroPaper 允许用户点按钮切 data-theme，两者会脱节。必须用 MutationObserver 监听 data-theme，通过 postMessage 通知 iframe 换皮。

下一篇预告

篇二：把一篇 Markdown 自动分发到 dev.to / Hashnode，canonical 指向主站。

核心思路：

统一 frontmatter 里加 syndicate: { devto: true, hashnode: true } 开关
GitHub Actions 监听 src/data/blog/ 变化，调用各平台 API 发布/更新
首发后把平台返回的文章 ID 回写到 frontmatter，实现幂等更新

等系列跑完，最终目标是：在 Claude Code 里一句话生成 md → git push → 全网同步更新。

DEV Community: lizhaopeng-cn

从零搭建个人技术博客 · 篇三：用 Claude Code 的 skill 和 command 接管博客增删改查

目录

为什么不用脚本

Slash command vs Skill

整体架构

实现：command 薄壳

实现：blog-new skill

实现：blog-list / edit / delete

为什么 delete 要这么死板

共享资源：blog-shared

项目级 vs 用户级

踩过的坑

小结

从零搭建个人技术博客 · 篇二：跨平台自动分发

目录

要解决的问题

整体架构

设计决定与权衡

1. 文件就是状态，没有外部数据库

2. canonical URL 固定指向主站

3. 每个 publisher 实现同一个接口

4. per-post 串行、per-platform 独立

踩过的坑

坑 1：Astro 的 z.date() 不接受带引号的 ISO 字符串

坑 2：自己写的 YAML parser 不支持嵌套对象

坑 3：博客园把 GitHub Actions 的出站 IP 风控了

为什么最后没做国内平台

当前成品

workflow 配置

每篇文章的状态

小结

从零搭建个人技术博客 · 篇一：Astro + Cloudflare Pages + AstroPaper

目录

整体架构与选型

最终架构

为什么选这套组合

排除项（为什么不选它们）

前置条件

第一步：用 pnpm 脚手架生成 AstroPaper

第二步：品牌化与本地化

导航栏中文化

默认深色模式

验证本地构建

第三步：推送到 GitHub

第四步：Cloudflare Pages 首次部署

第五步：绑定自定义域名

以后发布新文章的流程

标准 frontmatter 模板

三步发布

写作期间的小技巧

用 Claude Code 直接产出 Markdown

为什么要这样写，而不是甩一个"帮我写博客"

工作流的好处

第六步：接入访问统计与评论

6.1 Cloudflare Web Analytics

6.2 不蒜子：页面可见计数

6.3 Giscus：基于 GitHub Discussions 的评论

踩过的坑

下一篇预告

坑 1：Astro 的 `z.date()` 不接受带引号的 ISO 字符串