le0p.top 博客日常维护与发布指南 • le0p

这个博客使用 Astro Theme Pure 搭建，源码保存在 GitHub，并由 Vercel 自动部署。

整个发布流程是：

在 WSL 中修改文章
→ 本地预览
→ Git 提交
→ 推送到 GitHub main 分支
→ Vercel 自动构建
→ 发布到 www.le0p.top

text

一、进入博客项目#

打开 WSL，进入项目：

cd ~/projects/le0p-blog

bash

确认当前目录：

pwd

bash

正常情况下会显示：

/home/k/projects/le0p-blog

text

查看 Git 状态：

git status

bash

如果可能在其他设备上修改过代码，可以先同步远程仓库：

git pull --rebase origin main

bash

二、新建一篇普通文章#

博客文章统一保存在：

src/content/blog/

text

文章文件名建议使用小写英文和连字符，例如：

my-first-post.md
astro-learning-notes.md
how-to-use-git.md

text

例如创建：

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

text

填写：

---
title: '我的第一篇文章'
description: '这里填写文章摘要，建议清楚说明文章讨论的内容。'
publishDate: '2026-08-17 10:30:00'
tags:
  - blog
  - 随笔
language: '简体中文'
draft: true
comment: false
---

这里是文章正文。

## 第一部分

这里填写第一部分内容。

## 第二部分

这里填写第二部分内容。

## 总结

这里填写总结。

markdown

这个文件对应的网址是：

https://www.le0p.top/blog/my-first-post/

text

文章没有写完时使用：

draft: true

yaml

准备发布时改成：

draft: false

yaml

三、新建带图片的文章#

如果文章包含封面或多张图片，建议为文章建立独立目录：

src/content/blog/my-trip/
├── index.md
├── thumbnail.jpg
├── photo-1.jpg
└── photo-2.jpg

text

index.md 示例：

---
title: '一次旅行记录'
description: '记录这次旅行中的照片、见闻和思考。'
publishDate: '2026-08-17 10:30:00'
heroImage:
  src: './thumbnail.jpg'
  alt: '旅行途中拍摄的风景'
tags:
  - 旅行
  - 生活
language: '简体中文'
draft: true
comment: false
---

这是文章正文。

## 第一站

![第一站的风景](./photo-1.jpg)

这里填写正文。

## 第二站

![第二站的风景](./photo-2.jpg)

markdown

图片文件名区分大小写。Photo.jpg 和 photo.jpg 在线上服务器中是两个不同文件。

图片也必须添加到 Git，否则本地能显示、线上可能无法显示。

四、文章配置字段#

每篇文章开头由两个 --- 包围的部分叫作 Frontmatter。

常用字段如下：

字段	是否必需	说明
`title`	是	文章标题，最长60个字符
`description`	是	文章摘要，最长160个字符
`publishDate`	是	发布时间
`updatedDate`	否	最后更新时间
`heroImage`	否	文章封面
`tags`	否	文章标签
`language`	否	文章语言
`draft`	否	是否为草稿
`comment`	否	是否允许评论

修改旧文章时，可以增加更新时间：

updatedDate: '2026-08-17 15:30:00'

yaml

五、常用 Markdown 语法#

标题#

## 二级标题

### 三级标题

markdown

文章的一级标题已经由 title 生成，因此正文通常从二级标题开始。

列表#

- 第一项
- 第二项
- 第三项

markdown

链接#

[GitHub](https://github.com/)

markdown

图片#

![图片说明](./photo.jpg)

markdown

引用#

> 这里是一段引用内容。

markdown

行内代码#

使用 `npm run build` 构建博客。

markdown

代码块#

Markdown 代码块由三个反引号包围，还可以在开头指定编程语言：

```javascript
console.log('Hello, world!')
```

text

显示效果如下：

console.log('Hello, world!')

javascript

六、本地预览文章#

完成文章编辑后，进入项目目录：

cd ~/projects/le0p-blog

bash

启动后台开发服务器：

npm run astro -- dev --background

bash

查看服务器状态：

npm run astro -- dev status

bash

在浏览器中打开博客首页：

http://localhost:4321

text

打开文章列表：

http://localhost:4321/blog/

text

如果文章目录是：

src/content/blog/blog-maintenance-guide/index.md

text

对应的本地地址就是：

http://localhost:4321/blog/blog-maintenance-guide/

text

本地预览时重点检查：

文章标题和摘要是否正确
目录是否完整
代码块是否正常闭合
表格是否正常显示
图片是否正常加载
链接能否打开
页面在手机宽度下是否正常
是否包含不希望公开的信息

查看开发服务器日志：

npm run astro -- dev logs

bash

检查完成后停止服务器：

npm run astro -- dev stop

bash

如果后台模式不能正常工作，也可以运行：

npm run dev

bash

这种方式需要保持终端窗口开启。预览结束后按 Ctrl+C 停止。

七、把草稿改成正式文章#

文章尚未写完时应设置：

draft: true

yaml

准备正式发布时改为：

draft: false

yaml

如果是修改已经发布的文章，可以增加更新时间：

updatedDate: '2026-08-17'

yaml

完整的文章头部示例：

---
title: 'le0p.top 博客日常维护与发布指南'
description: '记录如何在 WSL 中新建和修改 Astro 博客文章，并通过 GitHub 和 Vercel 自动发布到 le0p.top。'
publishDate: '2026-08-17 12:00:00'
updatedDate: '2026-08-17'
tags:
  - astro
  - blog
  - git
  - vercel
language: '简体中文'
draft: false
comment: false
---

yaml

保存文件。

八、执行发布前检查#

进入项目：

cd ~/projects/le0p-blog

bash

查看修改状态：

git status

bash

查看这篇文章具体修改了什么：

git diff -- src/content/blog/blog-maintenance-guide/index.md

bash

检查 Markdown 是否存在多余空格或格式问题：

git diff --check

bash

然后执行完整的生产构建：

npm run build

bash

正常构建通常会依次执行：

astro-pure check
astro check
astro build

text

重点确认：

Astro 检查没有错误
内容字段验证通过
页面能够正常生成
命令最终以成功状态退出
日志末尾出现 Complete

Fontshare 等外部服务偶尔会因为网络问题显示超时警告。只要构建命令最终成功完成，就不会阻止发布。

如果构建失败，不要继续提交。根据第一条实际错误修改文章，然后重新运行：

npm run build

bash

九、提交到 Git 仓库#

生产构建成功后，添加这篇文章：

git add src/content/blog/blog-maintenance-guide/index.md

bash

查看准备提交的文件：

git status

bash

应该看到类似：

modified: src/content/blog/blog-maintenance-guide/index.md

text

创建 Git 提交：

git commit -m "Complete blog maintenance guide"

bash

确认提交已经生成：

git log --oneline -3

bash

十、推送到 GitHub#

把最新提交推送到 main 分支：

git push origin main

bash

推送成功后，终端通常会显示：

main -> main

text

可以打开 GitHub 仓库检查：

https://github.com/ule0p/le0p-blog

text

确认：

最新提交是 Complete blog maintenance guide
main 分支包含最新修改
文章文件内容完整

如果 SSH 连接失败，先测试：

ssh -T git@github.com

bash

认证成功时会显示：

Hi ule0p! You've successfully authenticated

text

如果显示连接超时，需要检查当前网络、代理或 SSH 的443端口配置。

十一、等待 Vercel 自动部署#

GitHub 推送成功后，不需要手动上传文件到 Vercel。

Vercel 已连接 GitHub 的 main 分支，会自动完成：

检测新提交
→ 安装依赖
→ 执行 npm run build
→ 生成部署
→ 更新生产域名

text

进入 Vercel 项目，打开：

Deployments

text

找到提交：

Complete blog maintenance guide

text

部署状态会依次变化：

Queued
→ Building
→ Ready

text

只有状态变成 Ready，新文章才算正式上线。

如果状态变成 Error：

点击失败的部署。
打开 Build Logs。
找到第一条真正的错误。
回到本地修复。
再次执行 npm run build。
创建新的 Git 提交并推送。

失败的部署通常不会覆盖上一个正常的生产版本。

十二、验证线上文章#

部署变成 Ready 后，打开主站文章：

https://www.le0p.top/blog/blog-maintenance-guide/

text

也可以打开 Vercel 默认域名：

https://le0p-blog.vercel.app/blog/blog-maintenance-guide/

text

应当优先使用自定义域名对外分享：

https://www.le0p.top/blog/blog-maintenance-guide/

text

检查以下内容：

页面能够正常打开
HTTPS 正常
文章没有在中途结束
所有章节都存在
代码块没有吞掉后续内容
图片和链接正常
博客列表中显示了该文章
标签页面可以找到文章
搜索功能能够搜索到文章内容

如果仍显示旧内容：

等待一两分钟。
按 Ctrl+F5 强制刷新。
使用浏览器无痕窗口。
检查 Vercel 最新部署是否为 Ready。
确认访问的是最新生产域名。
确认 GitHub 的 main 分支包含修改。

十三、以后修改已发布文章#

直接编辑原来的文件：

src/content/blog/blog-maintenance-guide/index.md

text

更新文章头部：

updatedDate: '2026-08-17'

yaml

然后重复完整发布流程：

cd ~/projects/le0p-blog

npm run astro -- dev --background
# 在浏览器中检查文章
npm run astro -- dev stop

npm run build

git diff
git add src/content/blog/blog-maintenance-guide/index.md
git commit -m "Update blog maintenance guide"
git push origin main

bash

等待 Vercel 部署变成 Ready 后，再检查线上页面。

十四、暂时下架文章#

如果只是暂时不想展示文章，不必删除文件。

将：

draft: false

yaml

改为：

draft: true

yaml

然后发布：

npm run build
git add src/content/blog/blog-maintenance-guide/index.md
git commit -m "Unpublish blog maintenance guide"
git push origin main

bash

Vercel重新部署后，文章就不会继续出现在正式网站中。

十五、永久删除文章#

确认不再需要文章后，可以删除整个文章目录：

src/content/blog/blog-maintenance-guide/

text

删除后查看 Git 状态：

git status

bash

提交删除操作：

git add -A
git commit -m "Remove blog maintenance guide"
git push origin main

bash

部署完成后，对应文章网址会变成404。

十六、撤销错误发布#

如果最新提交导致文章或网站出错，先查看最近提交：

git log --oneline -5

bash

安全撤销最新提交：

git revert HEAD

bash

Git 会创建一条新的撤销提交。然后推送：

git push origin main

bash

Vercel收到撤销提交后会自动恢复并重新部署。

不要轻易使用：

git reset --hard

bash

它可能永久删除尚未保存的本地修改。

十七、常见问题排查#

文章没有出现在正式网站#

检查文章是否仍然是草稿：

draft: false

yaml

检查文件是否已经提交：

git status
git log --oneline -3

bash

检查提交是否已经推送：

git push origin main

bash

检查 Vercel 的最新部署是否为 Ready。

文章网址返回404#

检查：

文章是否设置了 draft: true
文件是否位于 src/content/blog/
文件是否已经推送到 GitHub
Vercel部署是否成功
网址中的文件名是否正确

例如：

src/content/blog/my-post.md

text

对应：

/blog/my-post/

text

而：

src/content/blog/my-post/index.md

text

同样对应：

/blog/my-post/

text

图片本地正常、线上不显示#

检查：

图片是否已经添加到 Git
Markdown 中的路径是否正确
图片文件名大小写是否一致
图片是否位于文章目录
文件扩展名是否正确

查看尚未提交的文件：

git status

bash

构建提示文章字段错误#

检查 Frontmatter：

title: '标题'
description: '摘要'
publishDate: '2026-08-17 12:00:00'

yaml

当前限制：

title 最长60个字符
description 最长160个字符
publishDate 必须存在
日期必须是有效格式
Frontmatter 前后必须有 ---

Vercel没有自动部署#

检查：

GitHub 仓库是否仍连接 Vercel
Production Branch 是否为 main
最新提交是否已经出现在 GitHub
Vercel是否有构建失败记录
推送的是否为其他分支

页面显示旧内容#

依次执行：

确认 GitHub main 分支
→ 确认 Vercel 最新部署为 Ready
→ 等待一两分钟
→ Ctrl+F5 强制刷新
→ 使用无痕窗口访问

text

十八、完整发布流程速查#

以后每次新增或修改文章，可以执行：

cd ~/projects/le0p-blog

git status
git pull --rebase origin main

# 新建或修改 src/content/blog/ 中的文章

npm run astro -- dev --background
# 浏览器打开 http://localhost:4321 检查
npm run astro -- dev stop

npm run build
git diff --check
git status

git add src/content/blog/
git commit -m "Add or update blog post"
git push origin main

bash

然后：

打开 Vercel Deployments
→ 等待最新部署变成 Ready
→ 打开 www.le0p.top 检查

text

整个发布链路可以总结为：

编辑 Markdown
→ 本地预览
→ 生产构建
→ Git 提交
→ 推送 GitHub
→ Vercel 自动部署
→ 检查线上页面

text

不需要单独向 le0p.top 上传文件，也不需要每次修改阿里云 DNS。域名解析只需要在第一次部署时配置。