DDW-1123 博客维护手册 | 日常

这篇文章是 DDW-1123 的第一篇完整维护手册。

以后无论是在本地改，还是直接在 GitHub 网页上改，都可以回到这里查步骤。目标很简单：把博客变成一个可以长期自己维护、慢慢生长的小站。

一句话记忆版：
文字配置改 config/site.yaml，图库改 config/gallery.yaml，文章放 src/content/blog，图片放 public/img，上线用 git push origin main。

1. 项目目录速览

项目在本地的位置：

C:\Users\1\Desktop\DDW-worktree\DDW-1123

最常用的文件和目录：

位置	用途
`config/site.yaml`	站点标题、导航、头像、社交链接、歌单、追番等总配置
`config/gallery.yaml`	图库分类与图片列表
`src/pages/about.md`	关于页
`src/pages/music.md`	歌单页
`src/content/blog`	文章目录
`public/img`	图片总目录
`public/img/posts`	文章插图建议放这里
`public/img/gallery`	图库图片建议放这里
`src/components/ui/cover/Cover.astro`	博客内页大横幅

1.1 日常维护优先改哪里

日常 DIY 优先改这些：

config/site.yaml
config/gallery.yaml
src/pages/about.md
src/pages/music.md
src/content/blog/xxx.md
public/img/xxx

尽量少直接改这些：

.astro 组件
.ts 代码
.css 样式

除非是在改布局、交互或页面功能。

2. 本地修改版流程

本地修改适合稍微复杂一点的调整，因为可以先预览，再上线。

2.1 启动本地预览

打开 PowerShell：

cd C:\Users\1\Desktop\DDW-worktree\DDW-1123
corepack pnpm dev

浏览器打开：

http://localhost:4321/

遇到端口被占用的情况，(或者关闭代理)：

cd C:\Users\1\Desktop\DDW-worktree\DDW-1123
corepack pnpm dev -- --port 4322

浏览器打开：

http://localhost:4322/

然后就可以一边改文件，一边刷新浏览器看效果。

2.2 停止本地预览

确认没问题后，在 PowerShell 里按：

Ctrl + C

如果提示是否终止，输入：

2.3 构建检查

上线前先跑一次构建：

$env:ASTRO_TELEMETRY_DISABLED='1'; corepack pnpm build

看到 Complete!，并且没有红色报错，就可以推送。

2.4 提交并推送

git status
git add -A
git commit -m "chore: update site content"
git push origin main

这几行分别表示：

命令	含义
`git status`	查看改了哪些文件
`git add -A`	把所有改动加入提交
`git commit -m "..."`	保存一个版本
`git push origin main`	推送到 GitHub

推送成功后，GitHub 更新，Cloudflare 和 Vercel 会自动部署。

3. GitHub 网页修改版流程

GitHub 网页修改适合小改动，比如改文字、换配置、上传图片、写文章。

3.1 进入仓库

打开：

https://github.com/1314520ddw/ddw-1123

找到要改的文件，例如：

config/site.yaml
config/gallery.yaml
src/pages/about.md
src/pages/music.md
src/content/blog
public/img

3.2 编辑并提交

点右上角铅笔图标。
修改内容。
页面底部填写提交说明，例如 update site content。
选择 Commit directly to the main branch。
点 Commit changes。

提交后会自动触发 Cloudflare 和 Vercel 部署。

3.3 哪些适合 GitHub 网页改

适合：

文章内容
关于页
歌单页
图库 YAML
少量站点配置
上传图片

不太建议：

大改 .astro 页面结构
大改 .ts 逻辑
大改 CSS 样式
批量重构

GitHub 网页没有本地预览，复杂修改更容易出错。

4. 站点基本信息

站点基本信息在：

config/site.yaml

核心区域：

site:
  title: DDW的小站
  subtitle: WA 的一声就哭了
  name: DDW
  description: DDW 记录生活的博客
  avatar: /img/ddw.jpg
  author: DDW
  url: https://ddw-1123.pages.dev
  defaultOgImage: /img/ddw.jpg
  startYear: 2026

对应关系：

字段	控制内容
`site.title`	博客主页大标题
`site.subtitle`	博客主页副标题
`site.name`	左侧栏名称
`site.description`	左侧栏个性签名
`site.avatar`	左侧栏头像
`site.url`	站点正式地址，影响 SEO 和 RSS
`defaultOgImage`	分享预览图
`startYear`	页脚起始年份

5. 起始页维护

起始页配置在 config/site.yaml 的 startPage。

startPage:
  enabled: true
  title: DDW
  subtitle: ""
  quote: "我想把喜欢的东西放进来^-^"
  avatar: /img/ddw.jpg
  backgroundImage: /img/bg.png
  blogPath: /blog
  footer: © DDW-1123

对应关系：

字段	控制内容
`title`	起始页大字
`subtitle`	大字下面的小字，不想要就写 `""`
`quote`	引号里的句子
`avatar`	起始页头像
`backgroundImage`	起始页背景
`blogPath`	进入博客按钮，保持 `/blog`
`footer`	底部版权文字

5.1 起始页按钮

buttons:
  - label: 哔哩哔哩
    url: https://space.bilibili.com/你的ID
    icon: ri:bilibili-fill
    variant: secondary
    external: true
  - label: 进入博客
    url: __BLOG__
    icon: ri:quill-pen-ai-fill
    variant: primary

进入博客按钮建议保持：

url: __BLOG__

6. 图片管理

网站里图片路径和本地文件路径的对应关系：

本地文件	网页路径
`public/img/ddw.jpg`	`/img/ddw.jpg`
`public/img/bg.png`	`/img/bg.png`
`public/img/posts/a.jpg`	`/img/posts/a.jpg`
`public/img/gallery/a.jpg`	`/img/gallery/a.jpg`

6.1 头像

avatar: /img/ddw.jpg

6.2 起始页背景

backgroundImage: /img/bg.png

6.3 文章封面

cover: /img/posts/my-cover.jpg

6.4 文章插图

![图片说明](/img/posts/my-image.jpg)

注意：

文件名大小写必须一致。
不要在网页路径里写 public。
正确：/img/bg.png
错误：public/img/bg.png

7. 博客内页大横幅

博客主页、文章页、图库页顶部的大横幅在：

src/components/ui/cover/Cover.astro

现在使用：

const bannerLqipStyle = getLqipStyle('/img/bg.png');

图片本体：

<img
  src="/img/bg.png"
  alt="cover"
  class="h-full w-full object-cover"
  loading="eager"
  fetchpriority="high"
  decoding="async"
/>

如果以后换成：

public/img/blog-banner.jpg

就把两处都改成：

/img/blog-banner.jpg

7.1 关于 srcset

如果只有一张图，不建议使用 srcset。

如果要使用，格式必须是：

图片路径 空格 宽度

例如：

srcset="/img/bg-800.jpg 800w, /img/bg-1920.jpg 1200w"

8. 社交图标

社交图标在 config/site.yaml 的 social。

social:
  github:
    url: https://github.com/1314520ddw
    icon: ri:github-fill
    color: '#191717'
  bilibili:
    url: https://space.bilibili.com/你的ID
    icon: ri:bilibili-fill
    color: '#fb7299'
  email:
    url: mailto:你的邮箱@qq.com
    icon: ri:mail-line
    color: '#55acd5'

想删除某个图标，就删除对应整块。

想新增网易云：

music:
  url: https://music.163.com/#/user/home?id=你的ID
  icon: ri:netease-cloud-music-line
  color: '#e60026'

9. 顶部导航

顶部导航在 config/site.yaml 的 navigation。

navigation:
  - name: 首页
    path: /blog
  - name: 文章
    children:
      - name: 分类
        path: /categories
      - name: 标签
        path: /tags
      - name: 归档
        path: /archives
  - name: 友情链接
    path: /friends
  - name: 关于
    path: /about
  - name: 歌单
    path: /music
  - name: 图库
    path: /gallery

想隐藏某个导航，就删除对应整段。

10. 文章写作

中文文章放在：

src/content/blog

比如：

src/content/blog/life/my-first-post.md

文章模板：

---
title: 我的第一篇文章
link: my-first-post
date: 2026-04-15 12:00:00
description: 这里写文章摘要
cover: /img/posts/my-cover.jpg
tags:
  - 生活
  - 记录
categories:
  - 随笔
catalog: true
sticky: false
draft: false
---

这里开始写正文。

## 小标题

这是一段文字。

![图片说明](/img/posts/example.jpg)

10.1 Frontmatter 字段

字段	含义
`title`	文章标题
`link`	文章链接，建议英文、数字、短横线
`date`	发布时间
`description`	摘要
`cover`	封面图
`tags`	标签
`categories`	分类
`catalog`	是否显示目录
`sticky`	是否置顶
`draft`	是否草稿

不想置顶：

sticky: false

不想上线：

draft: true

10.2 Markdown 排版

# 一级标题

## 二级标题

### 三级标题

这是一段正文。

- 无序列表
- 第二项

1. 有序列表
2. 第二步

> 这是一段引用。

**加粗文字**

`行内代码`

```js
console.log('hello');

链接文字


## 11. 删除文章

直接删除对应 `.md` 文件即可。

例如：

```text
src/content/blog/life/hello-world.md

不确定要不要删时，可以先改成草稿：

draft: true

这样线上不显示，本地还可以继续看。

12. 精选分类

首页“精选分类”在：

config/site.yaml

featuredCategories:
  - link: life
    label: 随笔
    image: /img/cover/2.webp
    description: 生活记录、随想随笔

分类映射在：

categoryMap:
  随笔: life
  笔记: note
  工具: tools

文章里这样写：

categories:
  - 随笔

它就会进入 /categories/life。

12.1 新增分类示例

categoryMap:
  灵感: inspiration

精选卡片：

featuredCategories:
  - link: inspiration
    label: 灵感
    image: /img/cover/inspiration.jpg
    description: 图片、配色、想法收集

文章：

categories:
  - 灵感

13. 歌单页

歌单页在：

src/pages/music.md

示例：

---
layout: ../layouts/PageLayout.astro
title: "歌单"
description: "我喜欢的音乐"
---

{% media audio %}
- title: CN
  list:
    - https://music.163.com/playlist?id=12700562532
- title: ENG
  list:
    - https://music.163.com/playlist?id=12699099138
{% endmedia %}

新增歌单：

- title: 新歌单名
  list:
    - https://music.163.com/playlist?id=你的歌单ID

13.1 全站 BGM

右下角全站 BGM 在：

config/site.yaml

bgm:
  enabled: true

不想要右下角音乐按钮：

bgm:
  enabled: false

14. 图库维护

图库配置文件：

config/gallery.yaml

基本结构：

title: 图库
description: ""
defaultCategory: all
categories:
  - id: favorite
    name: 收藏
    description: 喜欢的图先放这里
    images:
      - src: /img/gallery/a.jpg
        title: 标题可不写
        description: 说明可不写
        alt: 图片说明

字段说明：

字段	含义
`title`	图库页标题
`description`	图库页说明，不想显示就写 `""`
`defaultCategory`	默认分类，`all` 表示全部
`categories`	分类列表
`id`	分类英文 ID，不要中文，不要空格
`name`	页面显示的分类名
`images`	图片列表
`src`	图片路径
`title`	图片标题，可空
`description`	图片说明，可空
`alt`	图片替代文本，建议写
`downloadName`	下载文件名，可不写

14.1 无文字图片

- src: /img/gallery/photo-01.jpg
  title: ""
  description: ""
  alt: photo 01

14.2 新增分类

- id: anime
  name: 动漫
  description: 喜欢的动漫图
  images:
    - src: /img/gallery/anime-01.jpg
      title: ""
      description: ""
      alt: 动漫图片

图库现在支持：

分类筛选
点击图片放大预览
Esc 关闭预览
右下角下载按钮
图片说明可有可无

15. 追番页

追番使用 Bangumi，也就是：

https://bgm.tv

配置在：

config/site.yaml

bangumi:
  userId: 你的Bangumi用户名
  label: 追番
  icon: ri:bilibili-fill

如果没有数据，检查：

用户名是否正确
收藏是否公开
Bangumi 是否能访问
API 是否临时不稳定

16. 关于页

关于页在：

src/pages/about.md

示例：

---
layout: ../layouts/PageLayout.astro
title: "About"
coverTitle: "关于我"
description: "关于我？"
---

# 你好，这里是 DDW

这里写你的介绍。

17. 自动部署

现在站点可以通过 GitHub 自动部署。

17.1 Cloudflare

Cloudflare Pages 绑定 GitHub 后，只要 main 分支更新，就会自动部署。

17.2 Vercel

Vercel 推荐配置：

Framework Preset: Astro
Root Directory: ./
Build Command: corepack pnpm build
Output Directory: dist
Install Command: corepack pnpm install
Production Branch: main

只要执行：

git push origin main

或者在 GitHub 网页上 Commit changes 到 main，就会自动触发：

GitHub 更新
Cloudflare 部署
Vercel 部署

18. 常见问题

18.1 图片不显示

检查：

图片是否真的在 public/img
路径是否写成 /img/xxx
文件名大小写是否一致
后缀是否一致，比如 .jpg、.png、.webp

18.2 GitHub 提交后线上没变化

检查：

Cloudflare / Vercel 是否有新的部署记录
部署是否成功
是否提交到了 main 分支
浏览器是否缓存，试试强制刷新

18.3 YAML 报错

YAML 对缩进很敏感。

正确：

site:
  title: DDW的小站
  name: DDW

错误：

site:
title: DDW的小站
name: DDW

字符串里有特殊符号时，可以加引号：

quote: "我想把喜欢的东西放进来^-^"

18.4 本地没有改动可提交

如果看到：

nothing to commit, working tree clean

说明没有新改动，不需要推送。

19. 推荐维护节奏

小改动用 GitHub 网页：

改文章
改关于页
改歌单
改图库 YAML
上传图片
改少量配置

大改动用本地：

改布局
改样式
改 Astro 组件
改图库功能
批量删文章
排查构建错误

推荐顺序：

本地预览。
只改一小块。
刷新确认。
构建检查。
提交推送。
查看 Cloudflare / Vercel 部署状态。

20. 最后

这个博客会从这篇文章开始，慢慢变成自己的地方。

它不需要一下子完整，也不需要每一处都完美。先把喜欢的东西放进来，再慢慢整理。