Astro 博客搭建全过程：从零到上线

你会得到什么

跟完这篇教程，你会拥有一个：

• 构建速度快、页面零 JS 的静态博客
• 支持暗色模式、全文搜索、RSS 订阅
• Markdown 写作 + 类型安全的内容管理
• Docker 一键部署，或直接丢到 Vercel/Netlify

整个过程大概需要 Node.js 基础和一点命令行经验。

一、环境准备

开始之前，确保本地装好了这些工具：

# 检查 Node.js 版本（需要 18.17.1 或更高）
node -v

# 推荐使用 pnpm 作为包管理器
npm install -g pnpm

# 检查 Git
git --version

如果你还没有 Node.js，去 nodejs.org 下载 LTS 版本。macOS 用户也可以用 Homebrew：

brew install node

编辑器推荐 VS Code，装上 Astro 官方扩展 获得语法高亮和智能提示。

二、创建项目

方式一：使用官方 CLI

Astro 提供了交互式脚手架：

pnpm create astro@latest my-blog

按提示选择模板、是否安装依赖、是否初始化 Git 仓库。如果你想从最简结构开始学习，选 “Empty” 模板。

方式二：使用社区主题模板（推荐）

如果你不想从零搭 UI，直接用成熟的博客主题。以 AstroPaper 为例：

pnpm create astro@latest my-blog -- --template satnaing/astro-paper

AstroPaper 开箱即用，自带暗色模式、SEO、搜索、标签系统、OG 图片生成等功能。后面的教程以这个模板为基础。

创建完成后：

cd my-blog
pnpm install
pnpm dev

打开 http://localhost:4321，你应该能看到博客首页了。

三、理解项目结构

my-blog/
├── astro.config.ts        # Astro 核心配置
├── src/
│   ├── config.ts           # 站点元信息（标题、描述、语言等）
│   ├── content.config.ts   # Content Collections 定义
│   ├── data/blog/          # 文章 Markdown 文件
│   ├── pages/              # 路由页面
│   ├── layouts/            # 页面布局
│   ├── components/         # UI 组件
│   └── styles/             # 全局样式
├── public/                 # 静态资源（favicon、图片等）
├── package.json
└── tsconfig.json

几个关键文件：

• astro.config.ts — 集成插件、Markdown 配置、Vite 设置都在这里
• src/config.ts — 博客标题、描述、作者、语言等元信息
• src/content.config.ts — 定义文章的 frontmatter 结构和校验规则

四、配置站点信息

打开 src/config.ts，修改成你自己的信息：

export const SITE = {
  website: "https://your-domain.com/",
  author: "Your Name",
  profile: "https://github.com/yourname",
  desc: "你的博客描述",
  title: "Your Blog",
  lang: "zh",           // 设置为中文
  lightAndDarkMode: true,
  showArchives: true,
};

lang 设为 "zh" 后，HTML 的 lang 属性会自动更新，对 SEO 和无障碍访问都有帮助。

五、Content Collections：类型安全的内容管理

这是 Astro 最强大的功能之一。在 src/content.config.ts 中，用 Zod schema 定义文章结构：

import { defineCollection, z } from "astro:content";
import { glob } from "astro/loaders";

const blog = defineCollection({
  loader: glob({ pattern: "**/[^_]*.md", base: "./src/data/blog" }),
  schema: ({ image }) =>
    z.object({
      title: z.string(),
      description: z.string(),
      pubDatetime: z.date(),
      modDatetime: z.date().optional().nullable(),
      author: z.string().default("Your Name"),
      featured: z.boolean().optional(),
      draft: z.boolean().optional(),
      tags: z.array(z.string()).default(["others"]),
      ogImage: image().or(z.string()).optional(),
    }),
});

export const collections = { blog };

这段代码做了几件事：

1. 用 glob loader 扫描 src/data/blog/ 下所有 .md 文件（排除 _ 开头的）
2. 用 Zod 校验每篇文章的 frontmatter，写错字段名或类型时构建阶段直接报错
3. 支持图片类型的 OG 图，Astro 会自动优化

六、写第一篇文章

在 src/data/blog/ 下创建 Markdown 文件。推荐按年月组织：

src/data/blog/
└── 2026/
    └── 04/
        └── hello-world.md

文章内容：

---
title: Hello World
pubDatetime: 2026-04-03T10:00:00.000Z
description: 我的第一篇博客文章。
tags:
  - 技术
---

## 开始写作

这是我的第一篇文章。Astro 的 Markdown 支持非常好，
代码块、表格、图片都能正常渲染。

​```bash
echo "Hello from my blog!"
​```

保存后刷新页面，文章就出现了。draft: true 可以标记草稿，构建时会自动排除。

七、样式定制：Tailwind CSS v4

AstroPaper 使用 Tailwind CSS v4，采用 CSS-first 的配置方式。全局样式在 src/styles/global.css：

@import "tailwindcss";

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-accent: var(--accent);
}

修改主题色只需要改 CSS 变量。暗色模式通过 data-theme="dark" 属性切换，Tailwind 的 dark: 前缀自动生效。

想改某个组件的样式？直接找到对应的 .astro 文件，Astro 组件的 <style> 标签默认是 scoped 的，不会影响其他组件。

八、Markdown 增强

语法高亮

Astro 内置 Shiki，在 astro.config.ts 中配置主题和增强功能：

markdown: {
  shikiConfig: {
    themes: {
      light: "min-light",
      dark: "night-owl",
    },
    transformers: [
      transformerNotationHighlight(),  // 行高亮
      transformerNotationDiff(),       // diff 标记 // [!code ++]
    ],
  },
},

目录生成

通过 remark 插件自动生成文章目录：

remarkPlugins: [
  remarkToc,
  [remarkCollapse, { test: "Table of contents" }],
],

在文章中写 ## Table of contents，构建时会自动替换为目录列表。

九、集成功能

搜索：Pagefind

AstroPaper 集成了 Pagefind 静态搜索。构建流程：

# package.json 中的 build 脚本
astro check && astro build && pagefind --site dist && cp -r dist/pagefind public/

Pagefind 在构建后扫描 HTML，生成搜索索引。零运行时依赖，搜索完全在客户端完成。

RSS 订阅

@astrojs/rss 已经集成好了，访问 /rss.xml 即可获取订阅源。配置在 src/pages/rss.xml.ts 中。

Sitemap

@astrojs/sitemap 自动生成站点地图，构建后在 /sitemap-index.xml。在 astro.config.ts 中已经配置好了。

评论系统

如果需要评论功能，可以集成 Twikoo、Giscus 等。以 Twikoo 为例，创建一个评论组件：

---
// src/components/Comments.astro
---
<div id="twikoo-comment"></div>

<script>
  document.addEventListener("astro:page-load", () => {
    twikoo.init({
      envId: "https://your-twikoo-server.com/",
      el: "#twikoo-comment",
    });
  });
</script>

注意用 astro:page-load 事件而不是 DOMContentLoaded，这样在 View Transitions 页面切换后评论区也能正确初始化。

十、部署上线

方案一：Docker + Nginx

创建 Dockerfile：

# 构建阶段
FROM node:lts AS build
RUN corepack enable && corepack prepare pnpm@latest --activate
COPY . /app
WORKDIR /app
RUN pnpm install --frozen-lockfile && pnpm build

# 运行阶段
FROM nginx:alpine
COPY --from=build /app/dist /usr/share/nginx/html
EXPOSE 80

配合 docker-compose.yml：

services:
  blog:
    build: .
    ports:
      - "80:80"
    restart: unless-stopped

一行命令启动：

docker compose up -d

方案二：Vercel / Netlify

更简单的方式——把代码推到 GitHub，然后：

1. 登录 Vercel 或 Netlify
2. 导入 GitHub 仓库
3. 框架会自动识别为 Astro
4. 点击部署

零配置，自动 CI/CD，每次 push 自动更新。

方案三：Cloudflare Pages

# 安装 Wrangler CLI
pnpm add -g wrangler

# 登录并部署
wrangler pages deploy dist

Cloudflare Pages 提供免费的全球 CDN，速度很快。

十一、日常写作流程

部署完成后，日常写文章的流程很简单：

1. 在 src/data/blog/ 下新建 .md 文件
2. 填写 frontmatter（标题、日期、标签、描述）
3. 用 Markdown 写正文
4. pnpm dev 本地预览
5. 提交代码，自动部署

写在最后

Astro 的设计哲学是”内容优先”——把 JavaScript 的复杂度留在构建阶段，给用户一个纯净快速的阅读体验。对于个人博客这个场景，这个取舍非常合理。

整个搭建过程不复杂，真正花时间的是后续的内容定制和持续写作。工具只是起点，内容才是博客的核心。