Astro 静态博客搭建全攻略：从零到生产环境部署

my-blog/
├── astro.config.ts              # Astro 核心配置文件
├── tsconfig.json                # TypeScript 编译配置
├── package.json                 # 项目依赖与脚本
├── .env.example                 # 环境变量模板
├── public/                      # 静态资源（直接复制到构建输出）
│   ├── favicon.ico
│   ├── robots.txt
│   └── images/
├── src/
│   ├── config.ts                # 站点全局元信息
│   ├── content.config.ts        # Content Collections 架构定义
│   ├── data/
│   │   └── blog/                # 📝 博客文章存放目录
│   ├── pages/                   # 页面路由（基于文件系统路由）
│   │   ├── index.astro          # 首页
│   │   ├── posts/               # 文章详情页动态路由
│   │   ├── archives.astro       # 归档页
│   │   ├── tags/                # 标签聚合页
│   │   └── rss.xml.ts           # RSS 订阅生成端点
│   ├── layouts/                 # 页面布局组件
│   │   ├── BaseLayout.astro
│   │   └── PostLayout.astro
│   ├── components/              # 可复用 UI 组件
│   │   ├── Header.astro
│   │   ├── Footer.astro
│   │   ├── Search.astro
│   │   └── Card.astro
│   └── styles/                  # 全局样式
│       └── global.css
└── dist/                        # 构建输出目录（自动生成，不纳入 Git）

// src/config.ts
export const SITE = {
  website: "https://your-domain.com/",          // 站点根 URL（用于 SEO Canonical）
  author: "Your Name",                           // 作者署名
  profile: "https://github.com/yourname",        // 作者个人链接
  desc: "专注于前端工程化与性能优化的技术博客",     // 站点描述（用于 SEO）
  title: "Your Blog",                            // 站点标题
  lang: "zh",                                    // 语言代码（影响 HTML lang 属性）
  lightAndDarkMode: true,                        // 启用暗色/亮色切换
  showArchives: true,                            // 是否显示归档页
};

export const SOCIALS = [
  { name: "GitHub", url: "https://github.com/yourname" },
  { name: "Twitter", url: "https://twitter.com/yourname" },
];

// src/content.config.ts
import { defineCollection, z } from "astro:content";
import { glob } from "astro/loaders";

// 定义博客文章集合
const blog = defineCollection({
  // 加载器：扫描 src/data/blog/ 下所有 .md 文件（排除以下划线开头的文件）
  loader: glob({ 
    pattern: "**/[^_]*.md", 
    base: "./src/data/blog" 
  }),
  // Zod Schema：定义 frontmatter 的字段类型与校验规则
  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(), // Open Graph 图片（支持 Image 类型或 URL）
    }),
});

export const collections = { blog };

---
title: "Astro 4.0 新特性全面解读"
pubDatetime: 2026-04-03T10:00:00.000Z
modDatetime: 2026-04-05T14:30:00.000Z
description: "深度解析 Astro 4.0 的 View Transitions、Content Layer API 等核心更新"
author: "张三"
featured: true
tags:
  - Astro
  - 前端框架
  - 性能优化
ogImage: /images/posts/astro-4-preview.png
draft: false
---

## 引言

Astro 4.0 于 2026 年 3 月正式发布...

/* src/styles/global.css */
@import "tailwindcss";

/* 使用 @theme inline 定义设计令牌 */
@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-accent: var(--accent);
  --color-accent-hover: var(--accent-hover);
}

/* 暗色模式通过 data-theme 属性控制 */
[data-theme="dark"] {
  --background: #0d1117;
  --foreground: #e6edf3;
  --accent: #58a6ff;
}

// astro.config.ts
import { defineConfig } from "astro/config";
import { transformerNotationHighlight, transformerNotationDiff } from "@shikijs/transformers";

export default defineConfig({
  markdown: {
    shikiConfig: {
      // 为亮色/暗色模式分别指定主题
      themes: {
        light: "github-light",
        dark: "github-dark",
      },
      // 添加转换器增强语法高亮能力
      transformers: [
        transformerNotationHighlight(),  // 支持 [!code highlight] 标记
        transformerNotationDiff(),       // 支持 [!code ++] / [!code --] diff 标记
      ],
    },
  },
});

---
// src/components/Search.astro
---

<div id="search-container">
  <input type="text" id="search-input" placeholder="搜索文章..." />
  <ul id="search-results"></ul>
</div>

<script>
  document.addEventListener("astro:page-load", () => {
    // 动态加载 Pagefind 并初始化搜索
    const script = document.createElement("script");
    script.src = "/pagefind/pagefind.js";
    script.onload = async () => {
      const { search } = window.pagefind;
      const input = document.getElementById("search-input");
      const results = document.getElementById("search-results");

      input.addEventListener("input", async (e) => {
        const query = e.target.value.trim();
        if (query.length === 0) {
          results.innerHTML = "";
          return;
        }
        const response = await search(query);
        if (response.results) {
          results.innerHTML = response.results
            .map(r => `<li><a href="${r.url}">${r.title}</a></li>`)
            .join("");
        }
      });
    };
    document.head.appendChild(script);
  });
</script>

// src/pages/rss.xml.ts
import { getCollection } from "astro:content";
import { rss } from "@astrojs/rss";

export async function GET(context) {
  const posts = await getCollection("blog", ({ data }) => !data.draft);
  return rss({
    title: "My Blog",
    description: "My blog description",
    site: context.site,
    items: posts.map((post) => ({
      title: post.data.title,
      pubDate: post.data.pubDatetime,
      description: post.data.description,
      link: `/posts/${post.slug}/`,
    })),
  });
}

---
// src/components/Comments.astro
---

<div id="twikoo-container"></div>

<script>
  // 使用 astro:page-load 确保在 View Transitions 后重新初始化
  document.addEventListener("astro:page-load", () => {
    // 延迟加载 Twikoo 脚本
    const script = document.createElement("script");
    script.src = "https://cdn.jsdelivr.net/npm/twikoo@1.6.39/dist/twikoo.min.js";
    script.onload = () => {
      twikoo.init({
        envId: "https://your-twikoo-cloud-function.com/",
        el: "#twikoo-container",
        region: "ap-guangzhou",
        path: window.location.pathname,
      });
    };
    document.head.appendChild(script);
  });
</script>

# 多阶段构建：构建阶段 + 运行阶段
FROM node:20-alpine AS builder

# 启用 pnpm
RUN corepack enable && corepack prepare pnpm@latest --activate

WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile

COPY . .
RUN pnpm build

# 运行阶段：使用 Nginx 提供静态服务
FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html

# 自定义 Nginx 配置（可选）
COPY nginx.conf /etc/nginx/nginx.conf

EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]