博客使用说明#

1. 项目简介#

这是一个基于 Astro 和 astro-pure 主题搭建的静态博客。博客文章位于 src/content/blog/，网站配置位于 src/site.config.ts。

2. 安装与启动#

环境要求：Node.js 18 或更高版本。

cd "/Users/xxx/astro_blog/astro-theme-pure"
npm install
npm run dev

启动后访问 http://localhost:4321。停止服务器请按 Ctrl + C。

也可以使用 Bun：

bun install
bun dev

3. 创建文章#

npm run new-post -- "我的学习笔记"

命令会创建 src/content/blog/我的学习笔记/index.md 和默认封面图。如果不指定标题，则使用日期作为文章目录名。

4. 编辑文章#

文章使用 Markdown 编写，文件顶部必须包含 Frontmatter：

---
title: 我的学习笔记
publishDate: 2026-08-21 10:00:00
description: 文章摘要，用于文章列表和 SEO。
tags:
  - 技术
  - 学习
language: 中文
heroImage:
  src: ./thumbnail.jpg
  alt: 文章封面
---

## 二级标题

这里开始写正文。

字段说明：

添加图片#

图片建议放在当前文章目录的 images/ 文件夹：

src/content/blog/文章目录/
├── index.md
├── thumbnail.jpg
└── images/example.png

正文中引用：

![示例图片](images/example.png)

5. 文档内容#

文档放在 src/content/docs/，格式与博客文章相同，可以额外设置排序字段：

---
title: 使用指南
description: 网站使用指南
order: 1
---

# 使用指南

6. 修改网站配置#

编辑 src/site.config.ts 可以修改：

• 网站标题、作者和描述
• Logo、头像和 Favicon
• 顶部导航菜单
• GitHub、邮箱、RSS 等社交链接
• 博客分页数量
• Waline 评论系统
• 友情链接

正式域名还需要在 astro.config.ts 中修改：

site: 'https://你的域名.com'

7. 检查、构建与预览#

npm run check      # 检查 Astro 和类型错误
npm run format     # 格式化代码
npm run lint       # 检查并修复代码风格
npm run build      # 构建生产版本
npm run preview    # 预览构建结果

构建后的静态文件位于 dist/。

8. 部署到服务器#

项目提供 deploy.sh，它会在服务器上执行：

1. git pull 拉取最新代码
2. npm install 安装依赖
3. npm run build 构建网站
4. 将 dist/ 复制到宝塔网站根目录

使用前修改脚本中的目录：

WEB_ROOT="/www/wwwroot/my-blog"

然后在服务器执行：

./deploy.sh

9. 一键提交并推送#

npm run deploy

该命令会自动执行 git add、git commit 和 git push。确认内容、远程仓库和分支无误后再使用。

10. 日常写作流程#

1. npm run dev 启动本地博客
2. npm run new-post -- "文章标题" 创建文章
3. 使用 Markdown 编辑 index.md
4. 在浏览器检查页面和图片
5. npm run check 检查项目
6. npm run build 验证生产构建
7. 确认无误后提交并部署

11. 常用命令速查#