如何使用个人博客

这篇文章记录当前博客系统的完整使用规则。博客源码保存在 GitHub，Cloudflare Pages 负责构建和发布。

本地文件 → GitHub main 分支 → Cloudflare Pages → 公开网站

当前项目：

GitHub 仓库：hugeJan/personal-blog
公开网站：https://personal-blog-9s3.pages.dev/
生产分支：main

1. 目录规则

内容	正确位置	说明
博客文章	`src/content/posts/`	只在这里新建 `.md` 或 `.mdx` 文件
About 页面内容	`src/content/pages/about.md`	修改 About 页正文
首页介绍	`src/pages/index.astro`	修改首页标题下方的介绍文字
归档页面程序	`src/pages/archives/index.astro`	自动读取文章，不需要为每篇文章手动修改
文章列表程序	`src/pages/posts/[…page].astro`	自动分页显示已发布文章
网站配置	`astro-paper.config.ts`	网站名称、链接、功能开关等
静态图片	`public/images/`	可在 Markdown 中通过 `/images/文件名` 引用

不要把文章放进 src/pages/posts/。这个目录存放页面路由程序，不是文章集合。

不要直接修改 dist/、node_modules/ 或 .astro/。这些目录由构建工具生成或管理。

2. 新建一篇文章

在 src/content/posts/ 新建文件，例如：

src/content/posts/my-first-post.md

文件名会影响文章 URL。文件名可以使用中文，但使用小写英文和短横线更容易分享，例如 my-first-post.md。

文章必须包含 Frontmatter（文件头元数据）。最小可用模板如下：

---
title: "我的第一篇文章"
pubDatetime: 2026-08-08T20:00:00+08:00
description: "文章简介。"
tags: []
draft: false
---

这里写正文。

## 小标题

正文支持 Markdown。

Frontmatter 的开始和结束标记必须单独占一行：---。

3. Frontmatter 字段规则

字段	类型	是否必需	作用
`title`	字符串	是	文章标题
`pubDatetime`	日期时间	是	发布时间，也决定 Archives 的年月分组
`description`	字符串	是	文章简介，用于列表和页面元信息
`draft`	布尔值	否	`true` 时不发布；建议正式文章明确写 `false`
`featured`	布尔值	否	`true` 时显示在首页 Featured 区域
`tags`	字符串数组	否	文章标签；不需要标签时写 `[]`
`modDatetime`	日期时间或 `null`	否	修改文章时填写，用于显示更新时间
`author`	字符串	否	作者；不填写时使用站点默认作者 `hugeJan`
`ogImage`	图片路径或 URL	否	分享到社交平台时使用的预览图
`canonicalURL`	URL 字符串	否	文章的规范 URL，通常不需要填写
`hideEditPost`	布尔值	否	`true` 时隐藏文章页的编辑链接
`timezone`	字符串	否	单篇文章使用的时区，例如 `Asia/Shanghai`

日期建议使用带时区的 ISO 格式：

pubDatetime: 2026-08-08T20:00:00+08:00

草稿和定时发布

draft: true：文章不会出现在生产环境的首页、Posts 或 Archives。
draft: false：文章可以正常发布。
pubDatetime 为未来时间时，生产环境会等到发布时间附近再显示。
本地开发环境会显示非草稿文章，便于提前预览定时文章。

正式发布前，确认 draft: false，并检查 pubDatetime。

4. Featured、Archives 和 Tags

Featured（精选）

精选不是单独上传的页面。将文章 Frontmatter 设置为：

featured: true

文章会从首页的 Recent Posts 移到 Featured 区域。没有任何文章设置 featured: true 时，首页不会显示精选区域。

首页最多显示配置中的数量；当前 perIndex 为 4。完整文章仍然可以在 Posts 页面访问。

Archives（归档）

Archives 页面由 src/pages/archives/index.astro 自动生成，不需要手动创建文章卡片。

符合发布条件的文章会按照 pubDatetime 自动按年份和月份分组。访问地址：

本地：http://localhost:4321/archives/
线上：https://personal-blog-9s3.pages.dev/archives/

如果 Archives 为空，先检查文章是否放在 src/content/posts/，以及 draft 和 pubDatetime 是否正确。

Tags（标签）

顶部导航中的 Tags 已移除。文章仍然支持 tags 字段，并可能在文章页底部显示标签。

不需要标签时，明确写：

tags: []

5. Markdown 正文

文章正文支持常用 Markdown 语法：

## 二级标题

普通段落。

- 无序列表
- 另一项

1. 有序列表
2. 另一项

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

~~~ts
const message = "代码块";
~~~

插入图片

将图片放入：

public/images/example.png

在文章中引用：

![图片说明](/images/example.png)

图片路径区分大小写。文件名中建议使用英文、数字和短横线。

使用 MDX

需要在 Markdown 中使用 AstroPaper 支持的组件或交互内容时，可以使用 .mdx 扩展名。普通文章优先使用 .md，这样更简单，也更容易排查格式问题。

6. 本地预览

进入项目目录：

cd "/Users/huuymjan/Documents/ChatGPT/个人博客"

启动开发服务器：

npm run dev

常用本地地址：

首页：http://localhost:4321/
所有文章：http://localhost:4321/posts/
About：http://localhost:4321/about/
Archives：http://localhost:4321/archives/
搜索：http://localhost:4321/search/

文章 URL 通常是：

http://localhost:4321/posts/文件名/

开发服务器运行时，保存 .md 文件后通常会自动刷新，不需要每次重启。如果页面没有变化，先刷新浏览器；仍然无变化时，再停止并重新运行 npm run dev。

7. 构建检查

推送到 GitHub 前，建议运行：

npm run build

这个命令会执行类型检查、Astro 构建、搜索索引生成和静态文件整理。出现错误时，不要继续发布；先修复终端中最早出现的错误。

文章数量变化后，如果本地搜索结果没有更新，重新运行 npm run build。

8. 发布到 GitHub 和 Cloudflare

确认本地页面正常后，查看变更：

git status

提交文章或配置修改：

git add .
git commit -m "feat: add or update blog content"
git push origin main

只想提交单篇文章时，可以使用：

git add "src/content/posts/文章文件名.md"
git commit -m "feat: add blog post"
git push origin main

Cloudflare Pages 当前使用以下设置：

GitHub 仓库：hugeJan/personal-blog
生产分支：main
构建命令：npm run build
输出目录：dist
自动部署：已启用

推送到 main 后，Cloudflare 会自动构建。Cloudflare 控制台只用于查看部署状态，不需要手动上传 dist。

9. 修改站点其他内容

修改 About

编辑：

src/content/pages/about.md

保留文件头中的 title。修改正文后，重新预览并提交。

修改首页介绍

编辑：

src/pages/index.astro

首页的 Featured 和 Recent Posts 会根据文章 Frontmatter 自动生成，不需要手动复制文章标题。

修改站点名称、链接和功能

编辑：

astro-paper.config.ts

当前常用配置包括：

site.title：站点名称
site.description：站点描述
site.url：公开站点地址
socials：首页和页脚的社交链接
features.showArchives：是否显示 Archives
features.search：是否启用搜索
posts.perPage：Posts 每页文章数
posts.perIndex：首页 Recent Posts 数量

修改配置后，必须重新运行 npm run build 检查。

10. 常见问题

文章不出现在 Posts

按以下顺序检查：

文件是否位于 src/content/posts/。
文件扩展名是否为 .md 或 .mdx。
Frontmatter 是否包含 title、pubDatetime 和 description。
draft 是否为 false。
pubDatetime 是否写成了未来时间。
是否访问了正确的 /posts/ 页面。

首页没有 Featured

确认文章 Frontmatter 中存在：

featured: true

没有任何精选文章时，首页不会显示 Featured 标题。

Archives 没有文章

Archives 不读取 src/pages/archives/ 中的 Markdown 文件。它只读取 src/content/posts/ 中符合发布条件的文章。

页面报 Missing content entry: about.md

确认以下文件存在：

src/content/pages/about.md

不要删除这个文件；About 路由需要它。

Cloudflare 线上没有更新

确认以下事项：

git push origin main 已成功执行。
GitHub 仓库中已经出现最新提交。
Cloudflare Pages 的 Deployments 页面显示构建成功。
浏览器刷新了线上地址，而不是仍在查看 localhost。