以前改主页要手动改 HTML、手动上传。现在这套流程只有一个动作:git push。
整体流程
src/content/blog/*.md
│ git push
▼
GitHub Actions
│ npm ci && npm run build
▼
dist/ ← 纯静态 HTML
│
▼
mc-lhz.github.io
关键点:访客打开页面时没有任何请求。文章标题、日期这些在构建阶段就已经写死在 HTML 里了,不是运行时 fetch 的。
为什么不用前端 fetch
常见做法是主页写一段 JS 去请求一个 JSON 接口。问题是:
- 多一次网络往返,首屏要等
- 接口挂了就是白屏
- 有跨域和SEO 问题
构建时生成则没有这些问题 —— 生成的HTML 里内容本来就在。
构建时 vs 运行时
- 构建时:零 JS、零接口、可缓存、SEO 友好 —— 静态站点的正确选择
- 运行时:内容实时,但代价是多一次请求和一堆失败场景
核心就四行
---
import { getCollection } from 'astro:content';
const latest = (await getCollection('blog'))
.filter((p) => !p.data.draft)
.sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf())
.slice(0, 5);
---
后面就是一个循环:
{latest.map((post, i) => (
<a href={`/blog/${post.id}/`}>
<h3>{post.data.title}</h3>
<span>{post.data.pubDate.toISOString().slice(0, 10)}</span>
</a>
))}
为什么排序是 b - a?
Array.sort() 默认按升序(a - b)。我们想要新的在前,所以把两个参数反过来写成 b - a。这个错误很常见——写反了就会变成「最旧的文章排在最前面」。
workflow 配置
name: Deploy to GitHub Pages
on:
push:
branches: [ master ]
workflow_dispatch:
permissions:
contents: read
pages: write
id-token: write
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- uses: withastro/action@v5
deploy:
needs: build
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- uses: actions/deploy-pages@v4
id: deployment
踩过的坑
1. Pages 的 Source 必须选 GitHub Actions
在仓库 Settings → Pages 里,Source 要选 GitHub Actions,不是 Deploy from a branch。选错了 workflow 会跑但没效果。
2. 用户站不需要 base
mc-lhz.github.io 属于 *.github.io 顶级路径,仓库名就是站点根。所以 astro.config.mjs 里不用配 base。如果是 mc-lhz.github.io/my-blog 这种项目站,就必须配 base: '/my-blog',且所有内部链接都要带这个前缀。
3. frontmatter 写错会在构建时炸
内容集合用 zod 定义 schema,字段名或类型不对会直接让构建失败,而不是静默发到线上。这是比运行时校验可靠得多的一层。
| 情况 | 运行时校验 | Astro 构建时校验 |
|---|---|---|
少写 pubDate |
页面上显示 undefined | ✅ 构建失败,看得到报错 |
tags 写成字符串 |
可能正常渲染 | ✅ 构建失败 |
以后写文章的流程
# 1. 新建文件
vim src/content/blog/hello.md
# 2. 本地预览(保存即热更新)
npm run dev
# 3. 提交上线
git add . && git commit -m "add: hello" && git push
没有后台、没有数据库、没有管理界面。一个 .md 文件就是一篇完整的文章。