echoes博客使用说明

这是一个基于 Astro + React 构建的个人博客系统，具有文章管理、项目展示、观影记录、读书记录等功能。本文将详细介绍如何使用和配置这个博客系统。

功能特点

响应式设计：完美适配桌面端和移动端
深色模式：支持自动和手动切换深色/浅色主题
文章系统：支持 Markdown 写作，带有标签和分类
项目展示：支持展示 GitHub、Gitea 和 Gitee 的项目
观影记录：集成豆瓣观影数据
读书记录：集成豆瓣读书数据
旅行足迹：支持展示全球旅行足迹热力图
丝滑页面过渡：使用 Swup 集成实现页面间无缝过渡动画，提供类似 SPA 的浏览体验，保留静态站点的所有优势

基础配置

主要配置文件位于 src/consts.ts，你需要修改以下内容：

1
// 网站基本信息
2
export const SITE_URL = "https://your-domain.com";
3
export const SITE_NAME = "你的网站名称";
4
export const SITE_DESCRIPTION = "网站描述";
5

6
// 导航链接
7
export const NAV_LINKS = [
8
  { href: "/", text: "首页" },
9
  { href: "/articles", text: "文章" },
10
  { href: "/movies", text: "观影" },
11
  { href: "/books", text: "读书" },
12
  { href: "/projects", text: "项目" },
13
  { href: "/other", text: "其他" },
14
];
15

16
// 备案信息（如果需要）
17
export const ICP = "你的ICP备案号";
18
export const PSB_ICP = "你的公安备案号";
19
export const PSB_ICP_URL = "备案链接";
20

21
// 豆瓣配置
22
export const DOUBAN_ID = "你的豆瓣ID";
23

24
// 旅行足迹
25
export const VISITED_PLACES = ["中国-北京", "中国-上海", "美国-纽约"];

文章写作

创建新文章

你可以通过以下两种方式创建新文章：

1. 使用创建脚本（推荐）

项目根目录下提供了 create_post.sh 脚本来快速创建文章：

1
# 添加执行权限（首次使用时）
2
chmod +x create_post.sh
3

4
# 方式1：交互式创建
5
./create_post.sh
6
# 按提示输入文章标题和路径
7

8
# 方式2：命令行参数创建
9
./create_post.sh "文章标题" "目录/文章路径"
10
# 例如：./create_post.sh "我的新文章" "web/my-post"

脚本会自动：

在指定位置创建文章文件
添加必要的 frontmatter（标题、日期、标签）
检查文件是否已存在
显示文件的绝对路径

2. 手动创建

在 src/content/articles 目录下创建 .md 或 .mdx 文件。文章需要包含以下前置信息：

1
---
2
title: "文章标题"
3
date: YYYY-MM-DD
4
tags: ["标签1", "标签2"]
5
---
6

7
文章内容...

文章过期提醒

博客系统支持文章过期提醒功能，可以在 src/consts.ts 中配置：

1
export const ARTICLE_EXPIRY_CONFIG = {
2
  enabled: true, // 是否启用文章过期提醒
3
  expiryDays: 365, // 文章过期天数
4
  warningMessage: "这篇文章已经发布超过一年了，内容可能已经过时，请谨慎参考。", // 提醒消息
5
};

文章列表展示

文章列表页面会自动获取所有文章并按日期排序展示，支持：

文章标题和摘要
发布日期
标签系统
阅读时间估算

项目展示

项目展示页面支持从 GitHub、Gitea 和 Gitee 获取和展示项目信息。

GitProjectCollection 组件

用于展示 Git 平台的项目列表。

基本用法：

1
---
2
import GitProjectCollection from '@/components/GitProjectCollection';
3
import { GitPlatform } from '@/components/GitProjectCollection';
4
---
5

6
<GitProjectCollection
7
  platform={GitPlatform.GITEA}   // 平台类型：GITHUB、GITEA、GITEE
8
  username="your-username"       // 必填：用户名
9
  title="Git 项目"               // 可选：显示标题
10
  url="https://your-gitea.com"   // 可选：Gitea 实例 URL（Gitea 必填，GitHub/Gitee 无需填写）
11
  token="your-token"             // 可选：访问令牌，用于访问私有仓库
12
  perPage={10}                   // 可选：每页显示数量，默认 10
13
  client:load                    // Astro 指令：客户端加载
14
/>

观影和读书记录

MediaGrid 组件

MediaGrid 组件用于展示豆瓣的观影和读书记录。

基本用法

1
---
2
import MediaGrid from '@/components/MediaGrid.astro';
3
---
4

5
// 展示电影记录
6
<MediaGrid
7
  type="movie"              // 类型：movie 或 book
8
  title="我看过的电影"      // 显示标题
9
  doubanId={DOUBAN_ID}     // 使用配置文件中的豆瓣ID
10
/>
11

12
// 展示读书记录
13
<MediaGrid
14
  type="book"
15
  title="我读过的书"
16
  doubanId={DOUBAN_ID}
17
/>

旅行足迹

WorldHeatmap 组件

WorldHeatmap 组件用于展示你去过的地方，以热力图的形式在世界地图上显示。

基本用法

在 src/consts.ts 中配置你去过的地方：

1
// 配置你去过的地方
2
export const VISITED_PLACES = [
3
  // 国内地区格式：'中国-省份/城市'
4
  "中国-黑龙江",
5
  "中国-北京",
6
  "中国-上海",
7
  // 国外地区直接使用国家名
8
  "马来西亚",
9
  "泰国",
10
  "美国",
11
];

然后在页面中使用：

1
---
2
import Layout from "@/components/Layout.astro";
3
import WorldHeatmap from '@/components/WorldHeatmap';
4
import { VISITED_PLACES } from '@/consts';
5
---
6

7
<Layout title="旅行足迹">
8
  <section>
9
    <h2 class="text-3xl font-semibold text-center mb-6">我的旅行足迹</h2>
10
    <div class="mx-auto bg-white dark:bg-gray-800 rounded-xl shadow-lg p-6">
11
      <WorldHeatmap
12
        client:only="react"
13
        visitedPlaces={VISITED_PLACES}
14
      />
15
    </div>
16
  </section>
17
</Layout>

主题切换

系统支持三种主题模式：

跟随系统
手动切换浅色模式
手动切换深色模式

主题设置会被保存在浏览器的 localStorage 中。

快速开始

环境要求

Node.js 18+
npm 或 pnpm

安装步骤

克隆项目

1
git clone https://github.com/your-username/echoes.git
2
cd echoes

安装依赖
Terminal window
```
1
npm install
```
修改配置

编辑 src/consts.ts 文件，更新网站配置信息。
本地运行
Terminal window
```
1
npm run dev
```

访问 http://localhost:4321 查看效果。

部署说明

部署方式选择

Vercel 部署（推荐）
- 支持所有功能
- 自动部署和 HTTPS
- 支持 API 路由和动态数据
- 可配合多吉云 CDN 实现自动刷新缓存
静态托管（如腾讯云）
- 仅支持静态文件
- 不支持的功能：
  - API 路由（豆瓣数据、Git 项目等）
  - 动态数据获取
- 需要手动配置和上传

CDN 加速配置

博客支持通过多吉云 CDN 进行加速，并可通过 GitHub Actions 实现自动刷新缓存：

按照CDN 配置指南配置多吉云 CDN
按照GitHub Actions 自动刷新 CDN 缓存指南配置自动刷新
配置完成后，每次博客更新时，CDN 缓存将自动刷新

部署步骤

Vercel 部署

Fork 项目到 GitHub
在 Vercel 导入项目
配置环境变量（如果需要）
点击部署

静态托管部署

修改 astro.config.mjs：

1
export default defineConfig({
2
  site: SITE_URL,
3
  output: "static",
4
  adapter: undefined,
5
});

构建并上传：

1
npm run build
2
# 上传 dist/client 目录到静态托管服务

常见问题

图片无法显示
- 检查图片路径是否正确
- 确保图片已放入 public 目录
豆瓣数据无法获取
- 确认豆瓣 ID 配置正确
- 检查豆瓣记录是否公开
Git 项目无法显示
- 验证用户名配置
- 确认 API 访问限制
静态托管部署后功能异常
- 确认是否使用了需要服务器端支持的功能
- 检查是否已将动态数据改为静态数据
- 确认构建输出目录是否为 dist/client