本博客使用教程 -

前言

本博客是一个基于现代Web技术栈构建的高性能静态博客系统，具有响应式设计、SEO优化、搜索功能等特色。本教程将详细介绍博客的技术架构、特色功能、配置方法和部署流程。

技术栈概览

核心框架

Astro 5.13.9 - 现代静态站点生成器，支持多框架组件
TypeScript - 类型安全的JavaScript超集
Node.js - 运行时环境

样式与UI

Tailwind CSS 3.4.17 - 实用优先的CSS框架
@tailwindcss/typography - 优化的排版样式
响应式设计 - 移动端优先的设计理念

内容管理

Markdown - 文章内容格式
Gray Matter - Front Matter解析
内容集合 - Astro的内容管理功能

部署与优化

多平台部署支持 - Netlify、Vercel、Node.js
图片优化 - Sharp图像处理
代码压缩 - Terser JavaScript压缩
SEO优化 - 自动生成sitemap和meta标签

博客特色功能

1. 响应式设计

移动端优化 - 针对移动设备的特殊优化
自适应布局 - 根据屏幕尺寸自动调整
触摸友好 - 移动端交互体验优化

2. 搜索功能

全文搜索 - 支持文章标题和内容搜索
实时搜索 - 输入即时显示搜索结果
搜索高亮 - 搜索结果关键词高亮显示

3. 导航系统

移动端抽屉菜单 - 侧滑式导航菜单
桌面端顶部导航 - 传统顶部导航栏
面包屑导航 - 文章页面路径导航

4. 文章功能

目录生成 - 自动生成文章目录
文章导航 - 上一篇/下一篇文章链接
标签系统 - 文章分类和标签管理
归档页面 - 按时间归档文章

5. SEO优化

自动sitemap - 搜索引擎站点地图
Meta标签 - 完整的SEO元数据
结构化数据 - JSON-LD格式的结构化数据
Open Graph - 社交媒体分享优化

6. 性能优化

图片懒加载 - 提升页面加载速度
代码分割 - 按需加载JavaScript
缓存策略 - 静态资源长期缓存
压缩优化 - Gzip/Brotli压缩

项目结构

Astro-blog/
├── public/                 # 静态资源
│   ├── images/            # 图片资源
│   ├── scripts/           # JavaScript文件
│   ├── fonts/             # 字体文件
│   └── search-data.json   # 搜索数据
├── src/
│   ├── components/        # Astro组件
│   │   ├── Header.astro   # 头部组件
│   │   ├── Hero.astro     # 首页英雄区
│   │   ├── ArticleCard.astro # 文章卡片
│   │   └── ...
│   ├── content/           # 内容文件
│   │   ├── posts/         # 文章目录
│   │   ├── about.md       # 关于页面
│   │   └── friends.json   # 友链数据
│   ├── pages/             # 页面文件
│   │   ├── index.astro    # 首页
│   │   ├── about.astro    # 关于页
│   │   ├── archive.astro  # 归档页
│   │   └── posts/[slug].astro # 文章详情页
│   ├── styles/            # 样式文件
│   │   └── global.css     # 全局样式
│   ├── config/            # 配置文件
│   │   └── site.ts        # 站点配置
│   └── integrations/      # 集成功能
│       └── search-data-updater.ts # 搜索数据更新
├── astro.config.mjs       # Astro配置
├── tailwind.config.js     # Tailwind配置
├── package.json           # 项目依赖
└── netlify.toml          # Netlify部署配置

配置方法

1. 基础配置

站点信息配置 (`src/config/site.ts`)

const site: SiteConfig = {
  avatarUrl: '/512x512.webp',           // 头像图片路径
  blogName: '| 爲 |',                  // 博客名称
  homeHero: {
    title: '| 爲 |',                   // 首页标题
    subtitle: '路上皆吾师，万事皆学问',  // 首页副标题
    image: '/images/hero-bg.webp',     // 首页背景图
  },
  archiveHero: { image: '/images/hero-bg.webp' }, // 归档页背景
  linksHero: { image: '/images/hero-bg.webp' },   // 友链页背景
  aboutHero: { image: '/images/hero-bg.webp' },   // 关于页背景
  social: {
    github: 'https://github.com/yourname',  // GitHub链接
    email: 'your@email.com',                // 邮箱地址
  },
  footer: { year: new Date().getFullYear() }, // 页脚年份
};

主题色彩配置 (`tailwind.config.js`)

theme: {
  extend: {
    colors: {
      'dark-bg': '#1a1a1a',        // 深色背景
      'header-bg': 'rgba(52, 50, 50, 0.7)', // 头部背景
      'search-bg': '#404040',       // 搜索框背景
      'border-gray': '#525252',     // 边框颜色
      'text-gray': '#9ca3af',       // 文本灰色
      'text-light': '#d1d5db',      // 浅色文本
    },
  },
}

2. 文章配置

创建新文章

在 src/content/posts/ 目录下创建 .md 文件：

---
title: "文章标题"
date: "2025-01-27"
tags: ["标签1", "标签2", "标签3"]
backgroundImage: "/images/hero-bg.webp"
slug: "article-slug"
description: "文章描述，用于SEO"
---

# 文章内容

这里是文章的正文内容...

Front Matter 字段说明

title: 文章标题
date: 发布日期 (YYYY-MM-DD格式)
tags: 文章标签数组
backgroundImage: 文章背景图片路径
slug: 文章URL别名
description: 文章描述，用于SEO

3. 友链配置

编辑 src/content/friends.json 文件：

[
  {
    "name": "友链名称",
    "url": "https://example.com",
    "description": "友链描述",
    "avatar": "/images/friend-avatar.webp"
  }
]

4. 搜索功能配置

搜索功能会自动生成，无需手动配置。搜索数据存储在 public/search-data.json 中，会在构建时自动更新。

开发环境搭建

1. 环境要求

Node.js >= 18.0.0
npm >= 8.0.0 或 yarn >= 1.22.0

2. 安装依赖

# 克隆项目
git clone <your-repo-url>
cd Astro-blog

# 安装依赖
npm install
# 或
yarn install

3. 启动开发服务器

# 启动开发服务器（支持局域网访问）
npm run dev

# 服务器将在 http://localhost:4321 启动
# 局域网访问：http://[your-ip]:4321

4. 可用脚本

# 开发模式
npm run dev

# 构建生产版本
npm run build

# 本地预览构建结果
npm run preview

# 生成搜索数据
npm run generate-search

# 性能测试（需要先启动开发服务器）
npm run lh:desktop  # 桌面端性能测试
npm run lh:mobile   # 移动端性能测试
npm run lh:all      # 全部性能测试

部署方法

1. Netlify 部署

自动部署

将代码推送到 GitHub/GitLab
在 Netlify 中连接仓库
配置构建设置：
- Build command: npm run build
- Publish directory: dist
部署完成

手动部署

# 构建项目
npm run build

# 将 dist 目录上传到 Netlify

2. Vercel 部署

自动部署

将代码推送到 GitHub
在 Vercel 中导入项目
自动检测 Astro 项目并部署

手动部署

# 安装 Vercel CLI
npm i -g vercel

# 部署
vercel

3. 传统服务器部署

使用 Node.js 适配器

# 构建项目
npm run build

# 启动服务器
npm run preview

静态文件部署

# 构建项目
npm run build

# 将 dist 目录内容上传到服务器
# 配置 Web 服务器（Nginx/Apache）指向 dist 目录

4. 环境变量配置

生产环境变量

# 设置站点URL
SITE_ORIGIN=https://yourdomain.com

# 本地预览模式
LOCAL_PREVIEW=1

自定义指南

1. 修改主题色彩

编辑 tailwind.config.js 文件中的颜色配置：

colors: {
  'dark-bg': '#your-color',      // 修改背景色
  'header-bg': 'rgba(r,g,b,a)',  // 修改头部背景
  // ... 其他颜色
}

2. 添加新页面

在 src/pages/ 目录下创建 .astro 文件
使用现有的组件和样式
参考现有页面的结构

3. 自定义组件

在 src/components/ 目录下创建 .astro 文件
使用 TypeScript 定义 Props 接口
在页面中导入并使用组件

4. 修改布局

头部: 编辑 src/components/Header.astro
页脚: 编辑 src/components/Footer.astro
全局样式: 编辑 src/styles/global.css

性能优化建议

1. 图片优化

使用 WebP 格式图片
设置合适的图片尺寸
启用图片懒加载

2. 代码优化

使用 TypeScript 进行类型检查
启用代码压缩和混淆
移除未使用的代码

3. 缓存策略

设置静态资源长期缓存
使用 CDN 加速
启用 Gzip/Brotli 压缩

4. SEO 优化

完善 meta 标签
生成 sitemap
添加结构化数据
优化页面加载速度

常见问题

1. 搜索功能不工作

检查 public/search-data.json 是否存在
运行 npm run generate-search 重新生成搜索数据

2. 图片不显示

检查图片路径是否正确
确认图片文件存在于 public/images/ 目录

3. 样式不生效

检查 Tailwind CSS 配置
确认样式类名拼写正确
清除浏览器缓存

4. 构建失败

检查 TypeScript 类型错误
确认所有依赖已正确安装
查看构建日志中的错误信息

更新日志

v1.0.0 (2025-01-27)

初始版本发布
基础博客功能
响应式设计
搜索功能
SEO 优化

技术支持

如果您在使用过程中遇到问题，可以通过以下方式获取帮助：

GitHub Issues: 在项目仓库中提交问题
邮箱: 862832617@qq.com
GitHub: https://github.com/wesson2775

结语

本博客系统采用现代化的技术栈，注重性能和用户体验。通过本教程，您应该能够快速上手并自定义您的博客。如有任何问题或建议，欢迎反馈！

最后更新：2025年1月27日

本博客使用教程

前言

技术栈概览

核心框架

样式与UI

内容管理

部署与优化

博客特色功能

1. 响应式设计

2. 搜索功能

3. 导航系统

4. 文章功能

5. SEO优化

6. 性能优化

项目结构

配置方法

1. 基础配置

站点信息配置 (src/config/site.ts)

主题色彩配置 (tailwind.config.js)

2. 文章配置

创建新文章

Front Matter 字段说明

3. 友链配置

4. 搜索功能配置

开发环境搭建

1. 环境要求

2. 安装依赖

3. 启动开发服务器

4. 可用脚本

部署方法

1. Netlify 部署

自动部署

手动部署

2. Vercel 部署

自动部署

手动部署

3. 传统服务器部署

使用 Node.js 适配器

静态文件部署

4. 环境变量配置

生产环境变量

自定义指南

1. 修改主题色彩

2. 添加新页面

3. 自定义组件

4. 修改布局

性能优化建议

1. 图片优化

2. 代码优化

3. 缓存策略

4. SEO 优化

常见问题

1. 搜索功能不工作

2. 图片不显示

3. 样式不生效

4. 构建失败

更新日志

v1.0.0 (2025-01-27)

技术支持

结语

站点信息配置 (`src/config/site.ts`)

主题色彩配置 (`tailwind.config.js`)