1970 字
10 分钟
NieBlog 项目维护指南
NieBlog 项目维护指南
本文档面向博客的日常维护者，说明项目结构、文件规范，以及「发布文章」「上传图片」「部署更新」的完整操作流程。 技术栈：Astro（静态站点）+ Fuwari 模板 + Tailwind CSS + EdgeOne Pages 部署 + Waline 评论。
一、目录结构总览
NieBlog/├── public/ # 静态资源（原样复制到网站，无需编译）│ ├── assets/ # ★ 站点图片（文章封面、壁纸、Banner 等）│ ├── gallery/ # ★ 图库照片（没有可自建此目录）│ ├── favicon/ # 网站图标│ └── .well-known/ # 域名验证文件（勿动）│├── src/ # 网页源代码│ ├── content/│ │ ├── posts/ # ★ 文章目录（Markdown 文件，一篇一个 .md）│ │ ├── spec/ # 「关于」等特殊页面（about.md）│ │ └── weekly/ # 周刊数据（自动聚合，一般不动）│ ├── pages/ # 路由页面（文件名即网址）│ │ ├── [...page].astro # 首页（含统计仪表盘+时间线）│ │ ├── archive.astro # 归档页│ │ ├── about.astro # 关于页│ │ ├── friends.astro # 友链页│ │ ├── gallery.astro # 图库页│ │ ├── guestbook.astro # 留言板│ │ ├── hubs.astro # 专题页│ │ ├── weekly.astro # 周刊页│ │ └── posts/[...slug].astro # 文章详情页模板（自动带评论区）│ ├── components/ # 页面组件│ │ ├── widget/ # 侧边栏组件（音乐播放器、重要提醒、公告等）│ │ ├── control/ # 控件（分页、返回顶部等）│ │ ├── misc/ # 通用小组件（图片包装等）│ │ └── *.astro # Navbar 导航栏、Footer 页脚、PostCard 文章卡片等│ ├── layouts/ # 页面骨架（Layout.astro 全局 / MainGridLayout 主布局）│ ├── config.ts # ★ 站点配置（标题、建站日期、导航栏、横幅等）│ ├── styles/ # 全局样式│ ├── constants/ # 常量（颜色、尺寸）│ ├── utils/ # 工具函数（文章排序、URL 处理）│ ├── i18n/ # 多语言文案│ └── types/ # 类型定义│├── dist/ # 构建产物（自动生成，勿手动改）├── astro.config.mjs # Astro 构建配置├── package.json # 依赖与脚本命令└── PROJECT_GUIDE.md # 本文档带 ★ 的是日常维护最常打交道的三个位置：public/assets/（图片）、src/content/posts/（文章）、src/config.ts（站点配置）。
二、图片文件规范
1. 存放路径
| 用途 | 路径 | 说明 |
|---|---|---|
| 文章封面图 | public/assets/ | 在文章 frontmatter 里引用 |
| 网站壁纸 | public/assets/ | 文件名 wallpaper-1.jpg、wallpaper-2.jpg（导航栏调色板里引用） |
| 网站横幅 | public/assets/ | 由 src/config.ts 的 banner.src 指定 |
| 图库照片 | public/gallery/ | 目录不存在就新建一个 |
2. 命名规范
- 只用小写英文 + 数字 + 连字符，禁止中文、空格、大写字母
- 推荐：
cover-my-blog-road.jpg、gallery-2026-09-01.jpg - 不推荐：
我的封面.JPG、Screen Shot 2026.png
- 推荐：
- 文章封面建议统一前缀：
cover-<文章文件名>.jpg，方便对应查找 - 图片格式：优先
.jpg/.webp（截图可用.png）；单张建议 小于 500KB，宽度 1200px 左右即可
3. 如何在文章中使用图片
---title: 文章标题published: 2026-09-01image: /assets/cover-my-blog-road.jpg # 必须以 /assets/ 开头（对应 public/assets/）---- 注意是
/assets/...而不是public/assets/...（public目录在网址里不出现） - 不填
image字段时，首页卡片会自动生成一张紫蓝渐变的 SVG 封面，标题会写上去，不用害怕没图
三、文章文件规范
1. 存放位置与文件名
- 所有文章放在
src/content/posts/，一个.md文件 = 一篇文章 - 文件名就是文章网址，所以必须用英文：
hello-my-friend.md→ 网址https://niezhenhaoblog.cc.cd/posts/hello-my-friend/- 文件名一旦发布就不要再改，否则网址会变
2. 文件格式（frontmatter + Markdown 正文）
每个 .md 文件开头必须有一段 --- 包裹的配置（frontmatter），然后是正文：
---title: 这里是文章标题published: 2026-09-01description: 一两句话的摘要，显示在首页卡片和搜索里tags: [标签1, 标签2]category: 分类名image: /assets/cover-xxx.jpg # 可选，不填自动生成渐变封面draft: false # true = 草稿，网站上不显示---
正文从这里开始，正常写 Markdown 即可：
## 二级标题
普通文字，**加粗**，*斜体*，[链接](https://example.com)
字段说明：
| 字段 | 必填 | 说明 |
|---|---|---|
title | ✅ 必填 | 文章标题 |
published | ✅ 必填 | 发布日期，格式 2026-09-01（首页时间线按它排序） |
description | 可选 | 摘要，建议写 |
tags | 可选 | 标签数组 |
category | 可选 | 分类（专题页 hub 会自动归组） |
image | 可选 | 封面图路径 |
draft | 可选 | true 为草稿，不显示在网站 |
updated | 可选 | 更新日期 |
⚠️ frontmatter 格式错误会导致构建失败（比如
published少写、---没配对）。写完不确定就先跑一次本地构建（见第五节）。
四、操作指南
A. 发布一篇新文章（最常用）
- 新建文件：在
src/content/posts/下新建一个英文文件名的.md，例如my-new-post.md - 填写 frontmatter + 写正文（参考上面第三节格式）
- 提交并推送：在项目根目录打开终端（PowerShell），依次执行：
npm run buildgit add .git add src/content/posts/my-new-post.mdgit commit -m "post: 新文章 标题"git push如果很久没推送，提示冲突：先执行
git pull --rebase origin main- 等待自动部署：推送后 EdgeOne 会自动拉取代码并构建，大约 5 分钟生效
- 刷新网站：打开 https://niezhenhaoblog.cc.cd/ 确认文章出现；没变化就按
Ctrl + F5强制刷新
一条命令也行（新文章+图片一起发）：
Terminal window
B. 给文章配封面图
- 把图片放进
public/assets/，命名为cover-<文章名>.jpg - 在文章 frontmatter 加一行：
image: /assets/cover-<文章名>.jpg - 图片和文章可以一起
git add .推送
C. 图库页添加照片
- 把照片放进
public/gallery/（目录没有就新建） - 打开
src/pages/gallery.astro，在顶部数组里照格式加一行：
const photos = [ { src: "/gallery/2026-09-01.jpg", title: "照片说明", date: "2026-09-01" },];- 推送后等自动部署
D. 修改网页内容 / 样式后的部署
- 直接修改对应的源码文件（改前建议备份或记住改了什么）
- （可选）本地预览确认效果：
npm run dev # 启动本地开发服务器，浏览器打开提示的 http://localhost:4321# 按 Ctrl + C 停止- 提交推送：
git add .; git commit -m "style: 改了什么简短说明"; git push- 等 EdgeOne 自动构建（约 5 分钟），
Ctrl + F5刷新网站验证
E. 常用命令速查
| 命令 | 作用 |
|---|---|
npm run dev | 本地实时预览（改代码即时生效，最推荐调试用） |
npm run build | 本地完整构建（验证能不能部署成功，产物在 dist/） |
npm run preview | 预览 dist/ 构建产物 |
git add . | 暂存所有改动 |
git commit -m "说明" | 创建提交 |
git push | 推送到远程 → 触发 EdgeOne 自动部署 |
F. 出问题了怎么办
| 现象 | 排查方法 |
|---|---|
| 推送后网站没更新 | 1. 等 5-8 分钟；2. Ctrl + F5 强刷；3. 登录 EdgeOne 控制台看构建状态 |
| 构建失败（EdgeOne 显示失败） | 本地跑 npm run build 复现真实报错（90% 是 frontmatter 写错或路径引用错） |
| 新文章没出现 | 检查文件是否在 src/content/posts/、frontmatter 是否有 title 和 published、是否写了 draft: true |
| 图片不显示 | 检查 frontmatter 里是否写成了 /assets/...（不能带 public）、文件名大小写是否完全一致 |
| 评论加载慢/不出 | 刷新一次（冷启动），还不行看Waline 服务状态 |
五、注意事项
- 文件名纪律：文章文件名、图片文件名一律小写英文 + 连字符；发布后的文章文件名不再修改
- 不要手动改：
dist/（构建产物）、pnpm-lock.yaml（依赖锁）、.astro/（缓存） - 敏感信息：不要把密钥、密码写进任何被提交的文件
- 站点基础信息（标题、建站日期、导航栏、横幅开关）集中在
src/config.ts，改完同样走「提交 → 推送 → 自动部署」流程 - 建站天数：页脚和首页仪表盘的「运行 X 天」由
config.ts的since字段计算，页面每次打开都会实时算，不会滞后
NieBlog 项目维护指南
https://niezhenhaoblog.cc.cd/posts/project-guide-fb/
阅读 ...
评论