用Astro搭建个人博客：从零到上线全记录

想搭个个人博客，这个念头在心里转了挺久。市面上的方案太多，Hexo、Hugo 这类静态生成器，WordPress 这种动态 CMS，各有各的好。最终选了 Astro，主要就三个原因：快、灵活、写起来舒服。

这篇文章把搭建过程从头到尾记下来，给想自己搭博客的人做个参考。

为什么是 Astro

先说说为什么不是别的。

Hexo 和 Hugo 是老牌的静态博客生成器，生态成熟、模板也多，但定制起来挺费劲，想改点东西得先搞懂它的主题系统。WordPress 功能强大但太重，一个小博客配数据库加 PHP，维护成本不低。Next.js 适合做复杂应用，纯博客场景有点杀鸡用牛刀。

Astro 做了几个很对的选择：

默认输出静态 HTML。Astro 虽然是前端框架，但默认是静态站点生成器（SSG），构建出来就是一堆 HTML 加 CSS 加 JS，直接往服务器一丢就行，不需要 Node.js 运行时。

岛屿架构（Islands Architecture）。页面上大部分静态内容直接用 HTML 渲染，只有需要交互的部分才加载 JavaScript。结果是首屏加载极快，几乎不跑 JS。

组件生态灵活。你可以在 Astro 文件里直接写 Vue、React、Svelte 组件，混着用也没问题。不过我的博客全是纯 Astro 组件，没用其他框架。

Markdown/MDX 一等的支持。在 src/content/posts/ 下放 .md 或 .mdx 文件，Astro 自动收集成文章集合，你只需要写 frontmatter 和内容，不需要手动配置路由。

项目初始化

我用的是开源主题 AstroPaper 作为基础。设计简洁、功能完整，支持明暗切换、标签分类、RSS、搜索。我没有完全照搬，做了一些修改来适配自己的需求。

# 我是从已有的模板仓库 fork 下来改的
# 你也可以直接用 create astro 开始
npm create astro@latest my-blog -- --template satnaing/astro-paper

核心配置

内容集合

Astro 的内容集合（Content Collections）是它的杀手锏。在 src/content.config.ts 里定义文章 schema：

const posts = defineCollection({
  loader: glob({ pattern: "**/[^_]*.{md,mdx}", base: "./src/content/posts" }),
  schema: ({ image }) =>
    z.object({
      author: z.string().default(config.site.author),
      pubDatetime: z.date(),
      title: z.string(),
      description: z.string(),
      tags: z.array(z.string()).default(["others"]),
      // 其他可选字段
    }),
});

每篇文章就是一个 .mdx 文件，写好 frontmatter 就行：

---
title: "文章标题"
description: "简短描述"
pubDatetime: 2026-08-11
tags: ["技术教程"]
---

Frontmatter 字段

前端开发者应该很眼熟，就是 YAML 格式的元数据：

• title: 文章标题
• description: 文章摘要，会用在 SEO meta 和卡片展示
• pubDatetime: 发布日期，必填
• modDatetime: 修改日期，可选
• tags: 标签数组，默认 ["others"]
• draft: 草稿标记，设为 true 不会构建出来
• featured: 是否置顶
• author: 作者名，默认取 config 中的 site.author
• ogImage: 自定义 OG 图片

图片与静态资源

博客图片统一放在 src/assets/images/ 目录下，Astro 会自动优化图片（压缩、生成多种尺寸），引用方式：

---
import blogImage from "@/assets/images/some-image.png";
---
<img src={blogImage} alt="描述" />

路径别名 @/ 指向 src/，在 tsconfig.json 里配置。

部署

Astro 的部署方式很简单。构建完的产物在 dist/ 目录，一堆静态文件：

npm run build

然后把 dist/ 里的东西扔到任意 Web 服务器就行。

我的做法是在 Linux 服务器上用 Nginx 托管：

server {
    listen 80;
    server_name qihanx.cn;
    root /var/www/myblog/dist;
    index index.html;
    
    location / {
        try_files $uri $uri.html $uri/ =404;
    }
}

没有数据库、没有后端进程、没有环境变量——就是静态文件，挂了也就挂了（其实不太可能挂）。配置 HTTPS 用 certbot 自动申请 Let’s Encrypt 证书，一条命令搞定：

certbot --nginx -d qihanx.cn

日常写文章

写文章就是本地写 .mdx 文件，然后通过 GitHub API 上传到仓库。流程大概是这样：

1. 写 .mdx 文章内容
2. 提交到 GitHub 仓库触发 CI 自动构建
3. CI 构建完把 dist/ 部署到服务器

本地网络访问 GitHub 有时候不稳定，所以用 gh CLI 走 API 上传文件，最稳。

# 查看现有文章
gh api repos/用户名/仓库名/contents/src/content/posts --jq '.[].name'

# 创建新文章
CONTENT=$(cat /tmp/article.mdx | base64 -w0)
gh api repos/用户名/仓库名/contents/src/content/posts/文件名.mdx \
  -X PUT \
  -f message="add: 文章标题" \
  -f content="$CONTENT" \
  -f branch="main"

# 更新已有文章（需要先获取 SHA）
SHA=$(gh api repos/... --jq '.sha')
gh api repos/.../文件名.mdx \
  -X PUT \
  -f message="update: xxx" \
  -f content="$CONTENT" \
  -f sha="$SHA" \
  -f branch="main"

SEO 与搜索引擎收录

静态博客对搜索引擎很友好，页面内容一开始就在 HTML 里，不需要 JS 渲染。但有些东西还是得自己配。

自动生成的 SEO 要素

• RSS Feed：AstroPaper 自带 /rss.xml，搜索引擎和 RSS 阅读器都能自动发现
• Sitemap：Astro 官方 @astrojs/sitemap 插件，构建后生成 sitemap-index.xml
• Meta 标签：每篇文章的 title 和 description 自动生成 OG 和 Twitter Card

提交搜索引擎

文章发布后，要让搜索引擎尽快知道。我用的是 IndexNow 协议：

curl -s -X POST "https://api.indexnow.org/IndexNow" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "host": "你的域名",
    "key": "你的密钥",
    "keyLocation": "https://你的域名/密钥.txt",
    "urlList": ["https://你的域名/posts/文章链接/"]
  }'

IndexNow 返回 HTTP 202 表示成功。另外也可以通过 Bing Webmaster Tools 的 SubmitUrl API 补充提交。两者配合，新文章基本当天就能被收录。

不用主动提交 sitemap，Bing 会自动爬取的。

一些小细节

插入追踪统计

我用了 Microsoft Clarity 来看访问情况。在 Astro 里插入脚本需要用 is:inline 属性，让 Astro 跳过对脚本的类型推断：

<script is:inline>
  // Clarity 追踪代码
  (function(c,l,a,r,i,t,y){ ... })();
</script>

不加 is:inline 的话，Astro 会把脚本当成模块处理，TypeScript 类型检查会报 Clarity 变量未定义的错误。

域名配置

域名解析用 CNAME 记录指向服务器 IP 或 CDN。免费的 Cloudflare CDN 能提供基本的 DDoS 保护和缓存加速。不想套 CDN 的话，直接 A 记录解析到服务器 IP 也行，速度更快但缺少防护。

总结

从搭建到上线，Astro 给我的感觉是，该有的都有，不该有的都没有。

不复杂，不写前端也能配置出好看的博客。不臃肿，生成的就是 HTML，没额外负担。不锁死，哪天想换主题、加功能，Astro 的组件化架构让这些事情都很自然。

想搭博客的话，不妨试试 Astro。不需要会 React、不需要后端经验，MDX 写文章就够了。剩下的交给框架。

这篇文章记录了我搭建博客的做法。如果你也在折腾博客或者遇到什么问题，欢迎留言交流。