Astro 博客模板

一个现代、高颜值，功能极简的个人博客模板，基于 Astro 与 Tailwind CSS 构建 —— 全静态、默认零客户端 JavaScript，只需修改一个配置文件即可完成个性化定制。 Astro 与 Tailwind CSS 构建后生成在dist/文件夹内

English | 简体中文

🌐 在线演示：https://ruijieking.github.io

✨ 功能特性

🌗 明暗主题切换 —— 防首屏闪烁（FOUC），自动记忆你的选择
🖼️ 壁纸系统 —— 明暗主题各配一套壁纸，交叉淡入淡出过渡，按主题分别记忆
📝 博客文章 —— 基于 Astro content collections（标题、描述、日期、分类、标签）
📚 归档时间轴 —— 按年份分组，支持即时搜索和多标签过滤
💬 今日说法 —— 轻量级碎碎念 / 短笔记板块
📷 照片相册 —— 文件夹即相册，三层叠加封面 + 灯箱（Lightbox） 大图查看
📑 文章目录 —— 从文章标题自动生成，点击平滑滚动
🔍 完整 SEO —— Open Graph、Twitter Cards、canonical 链接、JSON-LD 结构化数据
📡 RSS 订阅、sitemap、robots.txt
✨ 滚动入场动画 + 磨砂玻璃卡片设计
📱 完全响应式，移动端汉堡菜单
⚡ 图片自动优化（astro:assets + sharp，输出 WebP）
🚀 一键部署到 GitHub Pages（GitHub Actions 自动构建）

�🚀 快速开始

环境要求

Node.js >= 22.12.0
npm（或 pnpm / yarn）

1. 安装依赖

npm install

2. 本地开发

启动开发服务器，访问 http://localhost:4321：

npm run dev

3. 构建与预览

npm run build     # 输出到 dist/
npm run preview   # 预览生产构建

🎨 个性化配置

站点所有个性化配置都在一个文件里：src/site.config.ts。改一次，全站自动更新。

export const site = {
  name: '我的博客',                    // 网站名称（logo、页脚、页面标题、SEO）
  defaultTitle: '我的博客',            // 默认页面标题
  description: '写代码、拍照片、记录生活。',
  url: 'https://example.com',         // 你的站点域名⭐⭐⭐
  ogImage: '/og.png',                 // 社交分享图（public/目录下，建议 1200×630）
  ogSiteName: '我的博客',              // 分享卡片上显示的站点名
  author: {
    name: '你的名字',
    github: 'your-github-username',
    location: '你的城市',
  },
  about: '这是我的个人博客，用 Astro 构建。',
  nav: [
    { href: '/talk', label: '今日说法' },
    { href: '/blog', label: '文章' },
    { href: '/archive', label: '归档' },
    { href: '/photo', label: '照片' },
    { href: '/about', label: '关于我' },
  ],
};

📝 添加内容

博客文章

在 src/content/blog/ 下新建 Markdown 文件：

---
title: '你好，世界'           # 必填
description: '我的第一篇文章' # 必填
pubDate: '2026-01-01'         # 必填   
category: '生活'              # 可选
tags: ['astro', '博客']       # 可选
---

正文内容…

今日说法

在 src/content/talk/ 下新建 Markdown 文件（文件夹名字不参与配置）：

---
update: '2026-01-01-12:00'
---

短句内容…

照片相册

在 src/assets/album/ 下新建文件夹 —— 每个文件夹就是一个相册，文件夹名字就是照片的名字，里面的图片自动展示：

src/assets/album/
├── 旅行/          ← 相册：「旅行」
│   ├── photo1.jpg
│   └── photo2.png
└── 日常/
    └── photo3.jpg

壁纸

把壁纸放到 src/assets/wallpaper/ 下：

src/assets/wallpaper/
├── light/         ← 浅色主题显示的壁纸
└── dark/          ← 深色主题显示的壁纸

命名为 默认light.png / 默认dark.png 的文件（或每个文件夹里的第一张图）会被用作默认壁纸。

🗂️ 项目结构

├── public/                 # 静态资源（favicon、og.png）
├── src/
│   ├── assets/
│   │   ├── album/          # 照片相册（文件夹 = 相册）
│   │   └── wallpaper/      # 主题壁纸（light/ dark/）
│   ├── components/         # UI 组件
│   ├── content/
│   │   ├── blog/           # 博客文章（.md）
│   │   └── talk/           # 今日说法（.md）
│   ├── layouts/            # BaseLayout（主题、壁纸、SEO）
│   ├── pages/              # 页面路由
│   ├── styles/global.css   # Tailwind 入口
│   ├── content.config.ts   # 内容集合 schema
│   └── site.config.ts      # ⭐ 全局站点配置
├── astro.config.mjs
├── package.json
└── tsconfig.json

🚢 部署

GitHub Pages（不做后端非常推荐，因为部署简单免费）

项目自带的 .github/workflows/deploy.yml 会在每次 push 到 main 时自动构建并部署：

把这个模板推送到一个 GitHub 仓库；
打开 Settings → Pages，把 Source 设置为 GitHub Actions；
完成 —— 之后每次 push 到 main 都会自动重新构建并部署。

其他平台

这是一个纯静态站点 —— 执行 npm run build 后把 dist/ 文件夹部署到任意托管平台即可：

Netlify：构建命令 npm run build，发布目录 dist
Vercel：框架预设选择 Astro
Cloudflare Pages：构建命令 npm run build，输出目录 dist

💡 记得在 src/site.config.ts 里把 site.url 设为你的线上域名，canonical、sitemap、robots.txt 才会正确生成。

🛠️ 技术栈

工具	用途
Astro 7	静态站点框架
Tailwind CSS 4	样式（`@tailwindcss/vite`）
@tailwindcss/typography	文章排版
astro:assets + sharp	图片优化
@astrojs/sitemap	站点地图
@astrojs/rss	RSS 订阅源

例子