MocLab 博客系统维护说明

MocLab 博客系统维护说明这份文档只介绍当前项目里的博客系统，不包含学术页部分。

1. 博客内容放在哪里#

博客文章统一放在：

1
src/content/posts/

支持的文章格式是：

1
.md
2
.mdx

也就是说，你平时发博客，最常见的做法就是直接在 src/content/posts/ 下面新建一个 Markdown 文件。

例如：

1
src/content/posts/why-moclab.md
2
src/content/posts/agent-security-notes.md
3
src/content/posts/aigc-detection-log.mdx

如果你想用脚本快速创建文章，也可以直接运行：

1
pnpm new-post your-post-name

这个命令对应的脚本在：

1
scripts/new-post.js

它会自动在 src/content/posts/ 下生成一篇带基础 frontmatter 的新文章。

2. 文章的基本格式#

当前博客文章的数据结构定义在：

1
src/content.config.ts

最常用的写法如下：

1
---
2
title: 为什么我要搭建 MocLab
3
published: 2026-05-05
4
description: 记录搭建个人技术博客的原因、定位与长期计划。
5
image: ""
6
tags: ["Blog", "Research", "Personal"]
7
category: "Reflection"
8
draft: false
9
lang: "zh-CN"
10
---
11

12
这里开始写正文。

常用字段说明：

1
title        文章标题，必填
2
published    发布时间，必填
3
description  文章简介，列表页和 SEO 会用到
4
image        封面图，可留空
5
tags         标签数组，可写多个
6
category     分类，只写一个
7
draft        是否草稿，true 时生产环境不会显示
8
lang         语言标记，可留空
9
updated      更新时间，可选
10
pinned       是否置顶，可选
11
author       作者，可选
12
sourceLink   原文链接，可选
13
licenseName  许可名称，可选
14
licenseUrl   许可链接，可选
15
comment      是否开启评论，可选
16
password     文章密码，可选
17
passwordHint 密码提示，可选

3. 发博客的原理#

这个博客使用的是 Astro Content Collection。

简单理解就是：

你把文章写进 src/content/posts/
src/content.config.ts 负责校验文章 frontmatter 格式
Astro 在构建时读取这些文章
首页、归档、标签页、分类页、文章详情页都会自动使用这些内容

所以平时新增文章时，一般不需要手动去改路由或页面组件，只需要：

新建文章文件
填好 frontmatter
写正文
运行 pnpm build 或 pnpm dev

4. 标签和分类的逻辑#

标签怎么写#

标签来自文章 frontmatter 里的：

1
tags: ["AI Agent", "Memory", "Security"]

特点：

tags 是数组，所以一篇文章可以有多个标签
标签名按你写的字符串原样统计
同名标签会自动聚合到标签页

标签统计逻辑在：

1
src/utils/content-utils.ts

对应函数：

1
getTagList()

标签页入口在：

1
src/pages/tags.astro

点击标签后，实际会跳到归档页并带查询参数：

1
/archive/?tag=xxx

对应逻辑在：

1
src/utils/url-utils.ts

分类怎么写#

分类来自文章 frontmatter 里的：

1
category: "AI Agent"

特点：

category 是单个字符串，不是数组
一篇文章通常只属于一个分类
如果为空，会被归到“未分类”

分类统计逻辑也在：

1
src/utils/content-utils.ts

对应函数：

1
getCategoryList()

分类页入口在：

1
src/pages/categories.astro

点击分类后，实际会跳到：

1
/archive/?category=xxx

如果文章没有分类，会走：

1
/archive/?uncategorized=true

5. 文章 URL 的规则#

文章详情页路由在：

1
src/pages/posts/[...slug].astro

文章链接是根据你在 src/content/posts/ 里的文件路径生成的。

例如：

1
src/content/posts/why-moclab.md

通常会生成：

1
/posts/why-moclab/

如果你用了子目录：

1
src/content/posts/research/agent-memory.md

通常会生成：

1
/posts/research/agent-memory/

6. 头像和个人信息在哪里改#

最核心的个人资料入口在：

1
src/config/moclabSite.ts

这里集中维护了：

1
siteName
2
name
3
identity
4
blogTagline
5
description
6
blogBio
7
avatar
8
avatarFallback
9
github
10
email
11
blogNavigation

你平时最常改的是这些字段：

1
siteName: "MocLab"
2
name: "Zhongxu / Moc"
3
identity: "Computer Science Graduate Student"
4
blogTagline: "..."
5
blogBio: "..."
6
avatar: "/assets/images/icon3.jpg"
7
github: "https://github.com/..."
8
email: "mailto:your-email@example.com"

博客左侧个人卡片真正读取的配置在：

1
src/config/profileConfig.ts

不过它本身只是从 moclabSite.ts 映射过去，所以一般你直接改：

1
src/config/moclabSite.ts

就够了。

头像显示组件在：

1
src/components/widget/Profile.astro

7. 网站标题、导航和基础站点信息在哪里改#

站点级配置主要在：

1
src/config/siteConfig.ts

这里控制的内容包括：

1
站点标题
2
副标题
3
站点 URL
4
SEO 描述
5
主题色相
6
默认明暗模式
7
导航栏 logo
8
页面开关
9
文章列表布局
10
分页数量
11
分析统计

当前导航菜单的数据来源在：

1
src/config/moclabSite.ts

导航配置会被：

1
src/config/navBarConfig.ts
2
src/components/layout/Navbar.astro

读取并渲染。

如果你要修改博客导航项，优先改：

1
src/config/moclabSite.ts

8. 壁纸、横幅和主题色在哪里改#

主题色相#

主题色相配置在：

1
src/config/siteConfig.ts

对应字段：

1
themeColor: {
2
  hue: 250,
3
  fixed: false,
4
  defaultMode: "system",
5
}

其中：

1
hue          主题色相
2
fixed        是否锁定色相
3
defaultMode  默认明暗模式

壁纸和横幅#

壁纸、横幅、首页大图相关配置在：

1
src/config/backgroundWallpaper.ts

这里控制的内容包括：

1
壁纸模式
2
桌面端和移动端图片
3
首页横幅标题和副标题
4
导航栏在横幅上的透明/模糊表现
5
轮播
6
波浪动画
7
遮罩透明度

你平时最常改的字段有：

1
mode: "banner"
2
switchable: true
3
src: {
4
  desktop: [...],
5
  mobile: [...],
6
}
7
banner: {
8
  homeText: {
9
    title: "MocLab",
10
    subtitle: [...],
11
  }
12
}

壁纸图片放哪里#

当前配置里引用的壁纸图片主要在：

1
src/assets/images/DesktopWallpaper/

如果你要替换首页横幅图片，通常有两种做法：

把新图放进 src/assets/images/DesktopWallpaper/
然后去 src/config/backgroundWallpaper.ts 改 src.desktop 和 src.mobile

如果你想完全不要横幅图，只保留纯色背景，也是在这个文件里改 mode。

9. 明暗模式和文章布局在哪里改#

博客当前保留的可调项主要是：

1
明暗模式
2
文章列表/网格布局

10. 公告在哪里改#

首页公告卡片配置在：

1
src/config/announcementConfig.ts

可改内容包括：

1
公告标题
2
公告正文
3
跳转按钮文案
4
跳转链接
5
是否允许关闭

例如：

1
title: "公告"
2
content: "欢迎来到 MocLab..."
3
link: {
4
  enable: true,
5
  text: "了解更多",
6
  url: "https://academic.moclab.top",
7
}

11. 友链在哪里改#

友链页面配置在：

1
src/config/friendsConfig.ts

这个文件里有两部分：

页面级配置#

1
friendsPageConfig: {
2
  title,
3
  description,
4
  showCustomContent,
5
  showComment,
6
  randomizeSort,
7
}

友链列表数据#

1
friendLinks: [
2
  {
3
    title,
4
    imgurl,
5
    desc,
6
    siteurl,
7
    tags,
8
    weight,
9
    enabled,
10
  }
11
]

字段含义：

1
title    站点名称
2
imgurl   站点图标或头像
3
desc     简介
4
siteurl  链接地址
5
tags     标签
6
weight   排序权重，越大越靠前
7
enabled  是否显示

友链页面本体在：

1
src/pages/friends.astro

12. 赞赏在哪里改#

赞赏页面配置在：

1
src/config/sponsorConfig.ts

你可以在这里改：

1
页面标题
2
说明文案
3
赞赏用途
4
是否在文章页显示赞赏按钮
5
赞赏方式列表

最重要的是：

1
methods: [
2
  {
3
    name,
4
    icon,
5
    qrCode,
6
    link,
7
    description,
8
    enabled,
9
  }
10
]

字段含义：

1
name         赞赏方式名称
2
icon         图标
3
qrCode       收款码图片
4
link         外链方式，例如 GitHub Sponsors
5
description  说明
6
enabled      是否显示

赞赏页面本体在：

1
src/pages/sponsor.astro

如果你要换支付宝或微信收款码，通常是：

把新图片放到合适的静态资源目录
修改 src/config/sponsorConfig.ts 里的 qrCode 路径

13. About 页面在哪里改#

博客里的关于页内容来自：

1
src/content/spec/about.md

如果你只是想改“关于我”的正文，一般直接改这个文件即可。

14. 常改文件速查表#

发文章#

1
src/content/posts/

改文章字段规则#

1
src/content.config.ts

快速新建文章脚本#

1
scripts/new-post.js

改个人信息#

1
src/config/moclabSite.ts

改头像映射#

1
src/config/profileConfig.ts

改网站基础配置#

1
src/config/siteConfig.ts

改壁纸和横幅#

1
src/config/backgroundWallpaper.ts

改公告#

1
src/config/announcementConfig.ts

改友链#

1
src/config/friendsConfig.ts

改赞赏#

1
src/config/sponsorConfig.ts

改导航#

1
src/config/moclabSite.ts

改关于页#

1
src/content/spec/about.md

15. 本地预览和构建#

开发时常用命令：

1
pnpm dev

构建检查命令：

1
pnpm build

建议你每次改完以下内容后都跑一次构建：

新文章 frontmatter
导航配置
头像路径
壁纸图片路径
友链图片路径
赞赏二维码路径

16. 最简单的日常维护流程#

如果只是普通发文，最常见流程就是：

在 src/content/posts/ 新建一篇 .md
按 frontmatter 格式补全标题、时间、标签、分类、简介
写正文
跑 pnpm dev 本地看效果
最后跑 pnpm build

如果只是改个人资料，最常见流程就是：

改 src/config/moclabSite.ts
如果换头像，确认图片路径有效
跑 pnpm build

如果只是改首页横幅或壁纸，最常见流程就是：

改 src/config/backgroundWallpaper.ts
如有需要替换图片资源
跑 pnpm build