博客日常使用指南：写文章、发动态、加书签（自用记录）

1. 确认环境#

打开终端（Windows 用 PowerShell），分别输入这两条命令检查版本：

1
node -v   # 需要 v22.23 以上
2
pnpm -v   # 需要 11.22 以上

如果提示「不是内部或外部命令」，说明还没安装：去 nodejs.org 装 Node.js（会自带核心），再输入 npm install -g pnpm 装 pnpm。装完重开一个终端再检查一次。

2. 启动网站#

1
cd D:\blog\Firefly    # 换成你的项目文件夹路径
2
pnpm install          # 第一次运行才需要，安装依赖
3
pnpm dev              # 启动本地开发服务器

看到终端里出现 Local http://localhost:4321/ 就说明成功了。用浏览器打开这个地址，你看到的就是自己的网站。

热更新：只要 pnpm dev 开着，你改任何文件保存，浏览器页面会自动刷新。写文章时建议左边开编辑器、右边开浏览器，改一段看一眼。

按 Ctrl + C 停止开发服务器。

文章放在哪里#

所有文章都是 src/content/posts/ 目录下的 Markdown 文件，一个 .md 文件就是一篇文章。不需要注册或登记，文件放进去就自动出现在首页、归档和 RSS 里。

目录按分类建了文件夹：

1
src/content/posts/
2
├── tech/     # 技术类：建站、教程、运维
3
├── daily/    # 日常随笔
4
└── anime/    # 追番相关

以后想加新分类，在 posts/ 下新建一个文件夹就行，不需要改任何配置。

方法一：用脚手架创建（推荐）#

在项目根目录的终端里执行（把 tech/my-first-post 换成你的文件名）：

1
pnpm new-post -- tech/my-first-post

这条命令会自动做三件事：

1. 在 src/content/posts/tech/ 下创建 my-first-post.md；
2. 写好 frontmatter 模板（标题、日期、slug 都是现成的）；
3. 如果文件名里写了中文，会自动转成拼音作为 URL，比如 我的笔记 → wo-de-bi-ji。

文件名可以带子文件夹前缀（如 tech/xxx），也可以不带（直接生成在 posts/ 根目录，再手动挪进分类文件夹）。

方法二：手动创建#

在 src/content/posts/tech/ 里直接新建一个 我的文章.md，把下面的模板整个粘进去，然后按注释逐行改：

1
---
2
title: 我的第一篇文章            # 必填，显示在列表和浏览器标签页
3
published: 2026-09-22           # 必填，发布日期
4
description: 一两句话的摘要       # 建议填，列表页和分享卡会显示
5
tags: [建站, 随笔]               # 标签，方括号里逗号分隔，可以多个
6
category: 技术                  # 分类，和所在文件夹保持一致
7
draft: false                    # false = 正式发布；true = 草稿
8
slug: my-first-post             # 可选，自定义 URL；不填就用文件名
9
---
10

11
正文从这里开始，标准 Markdown 语法……

脚手架用户注意：pnpm new-post 生成的模板里有一行 image: ''（空值 = 不显示封面）。想要随机二次元封面，就把这一行删掉；想指定封面再填图片直链。

frontmatter 字段速查#

frontmatter 就是文件开头两行 --- 之间的那段 YAML，是文章的”身份证”。常用字段：

几个要点：

• URL 规则：tech/docker-basics.md 不写 slug 时地址是 /posts/tech/docker-basics/；写了 slug: docker-basics 则是干净的 /posts/docker-basics/。建议每篇都写 slug，以后调整文件夹不影响链接；
• 中文文件名可以用（脚手架会自动转拼音），但手动建文件时建议文件名用英文短横线风格，URL 更好看；
• 时区坑点：published 只写日期没问题；如果精确到几点几分，必须写成 2026-09-21T09:00:00+08:00 带时区的格式。因为构建机在 GitHub 的 UTC 时区，不带时区会被当成 UTC，时间全部偏移 8 小时。

保存，看效果#

保存文件，浏览器（http://localhost:4321）会自动刷新——首页列表里出现你的新文章了。点进去检查排版，改到满意为止。

基础排版#

1
## 二级标题（一级标题留给文章大标题，正文从二级开始）
2

3
普通段落，**加粗**、*斜体*、~~删除线~~、`行内代码`。
4

5
- 无序列表项
6
- 另一项
7

8
1. 有序列表项
9
2. 另一项
10

11
> 引用块，适合放注意事项或台词
12

13
[链接文字](https://example.com)

图片#

1
![图片说明](https://example.com/photo.jpg)   # 网络图片，直接贴直链
2
![本地图片](/assets/images/photo.jpg)        # 本地图片放到 public/assets/images/ 下

代码块#

三个反引号开头，后面跟语言名：

1
```js
2
console.log("Hello, blog!");
3
```

支持语法高亮和复制按钮。超过 15 行的长代码会自动折叠（显示前 8 行 + 展开按钮），也可以在语言名后面写 collapse 手动控制。

提示框（callout）#

> [!类型] 开头的引用块会渲染成彩色提示框，支持五种类型：

1
> [!NOTE]
2
> 补充说明，蓝色。
3

4
> [!TIP]
5
> 小技巧，绿色。
6

7
> [!IMPORTANT]
8
> 重要信息，紫色。
9

10
> [!WARNING]
11
> 警告内容，黄色。
12

13
> [!CAUTION]
14
> 危险操作，红色。

表格#

1
| 姓名 | 作用 |
2
| --- | --- |
3
| Astro | 静态站点框架 |
4
| Svelte | 前端交互框架 |

数学公式#

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

3
独立公式块：
4
$$
5
\int_{-\infty}^{\infty} e^{-x^2} \, dx = \sqrt{\pi}
6
$$

流程图（Mermaid）#

1
```mermaid
2
graph LR
3
    A[写文章] --> B[git push]
4
    B --> C[自动构建]
5
    C --> D[自动上线]
6
```

时序图（PlantUML）#

1
```plantuml
2
@startuml
3
游客 -> 网站 : 打开文章
4
网站 --> 游客 : 返回内容
5
@enduml
6
```

每篇文章自带的「AI 智能总结」#

文章页顶部有个「AI 智能总结」卡片，不需要你做任何事：

• 摘要在网站构建时用免费 AI 预先生成好，直接烘进页面，访客秒开；
• 只在你改了文章内容后，下次构建才会重新生成那篇的摘要；
• 开关、接口、字数、逐字特效等参数都在 src/config/index.ts 的「AI 总结」模块；
• 只在构建时把正文发给 AI 一次，不收集任何访客信息。