echoes博客使用说明

文章 / echoes博客使用说明

echoes博客使用说明

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

功能特点

  1. 响应式设计:完美适配桌面端和移动端
  2. 深色模式:支持自动和手动切换深色/浅色主题
  3. 文章系统:支持 Markdown 写作,带有标签和分类
  4. 项目展示:支持展示 GitHub、Gitea 和 Gitee 的项目
  5. 观影记录:集成豆瓣观影数据
  6. 读书记录:集成豆瓣读书数据
  7. 旅行足迹:支持展示全球旅行足迹热力图,WebAssembly 解析地图数据,提高性能
  8. 丝滑页面过渡:使用 Swup 集成实现页面间无缝过渡动画,提供类似 SPA 的浏览体验,保留静态站点的所有优势
  9. 高效搜索与筛选:使用 Rust 构建二进制数据,WebAssembly 高效解析,提供快速精准的全文搜索体验
  10. 优化代码块样式:支持 Mermaid 图表解析,多主题代码高亮
  11. 优化 SEO:完整的元数据支持,内置性能优化
  12. 资源压缩:支持图片和静态资源压缩,提高加载速度

基础配置

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

TEXT
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
// 网站基本信息
export const SITE_URL = "https://your-domain.com";
export const SITE_NAME = "你的网站名称";
export const SITE_DESCRIPTION = "网站描述";

// 导航链接结构 - 支持分层导航
export const NAV_STRUCTURE = [
    {
        id: 'home',
        text: '首页',
        href: '/'
    },
    {
        id: 'douban',
        text: '豆瓣',
        items: [
            { id: 'movies', text: '观影', href: '/movies' },
            { id: 'books', text: '读书', href: '/books' }
        ]
    },
    {
        id: 'articles',
        text: '文章',
        items: [
            { id: 'filter', text: '筛选', href: '/filtered' },
            { id: 'path', text: '文章', href: '/articles' }
        ]
    },
    {
        id: 'others',
        text: '其他',
        items: [
            { id: 'other', text: '其他', href: '/other' },
            { id: 'projects', text: '项目', href: '/projects' }
        ]
    }
];

// 备案信息(如果需要)
export const ICP = "你的ICP备案号";
export const PSB_ICP = "你的公安备案号";
export const PSB_ICP_URL = "备案链接";

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

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

文章写作

创建新文章

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

1. 使用创建脚本(推荐)

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

TEXT
1
2
3
4
5
6
7
8
9
10
# 添加执行权限(首次使用时)
chmod +x create_post.sh

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

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

脚本会自动:

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

2. 手动创建

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

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

文章内容...

文章过期提醒

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

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

项目展示

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

GitProjectCollection 组件

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

基本用法:

TEXT
1
2
3
4
5
6
7
8
9
10
11
12
13
14
---
import GitProjectCollection from '@/components/GitProjectCollection';
import { GitPlatform } from '@/components/GitProjectCollection';
---

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

观影和读书记录

MediaGrid 组件

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

基本用法:

TEXT
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
---
import MediaGrid from '@/components/MediaGrid.astro';
---

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

// 展示读书记录
<MediaGrid
  type="book"
  title="我读过的书"
  doubanId={DOUBAN_ID}
/>

旅行足迹组件

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

基本用法:

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

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

然后在页面中使用:

TEXT
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
---
import Layout from "@/components/Layout.astro";
import WorldHeatmap from '@/components/WorldHeatmap';
import { VISITED_PLACES } from '@/consts';
---

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

代码块与 Mermaid 图表支持

博客系统现在支持丰富的代码块样式和 Mermaid 图表渲染:

Mermaid 图表支持

TEXT
1
2
3
4
5
6
7
```mermaid
graph TD;
    A[开始] -->|处理数据| B(处理结果);
    B --> C{判断条件};
    C -->|条件1| D[结果1];
    C -->|条件2| E[结果2];
```
graph TD;
    A[开始] -->|处理数据| B(处理结果);
    B --> C{判断条件};
    C -->|条件1| D[结果1];
    C -->|条件2| E[结果2];

SEO 优化

博客系统内置全面的SEO优化支持:

  1. 自动生成元标签:为每个页面生成适当的标题、描述和Open Graph标签
  2. 结构化数据:支持添加结构化数据,提高搜索引擎理解能力
  3. 站点地图:自动生成XML站点地图
  4. 性能优化:页面加载性能优化,提高搜索排名

资源压缩与优化

系统支持自动的资源压缩和优化:

  1. 图片优化:自动压缩和优化图片,支持WebP格式
  2. CSS/JS压缩:自动压缩CSS和JavaScript文件
  3. 预加载关键资源:识别并预加载关键资源
  4. 延迟加载非关键资源:非关键资源延迟加载,提高初始加载速度

主题切换

系统支持三种主题模式:

  1. 跟随系统
  2. 手动切换浅色模式
  3. 手动切换深色模式

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

高效搜索与筛选

博客系统使用 Rust 构建二进制数据,结合 WebAssembly 高效解析,提供快速的全文搜索和筛选功能。

搜索功能特点

  1. 高性能全文搜索:使用 Rust 编写的搜索引擎,编译为 WebAssembly 在浏览器中运行
  2. 智能搜索推荐:输入时提供智能搜索建议和自动补全
  3. 拼写纠正:当用户输入可能存在错误时,提供拼写纠正建议
  4. 结构化搜索结果:按标题、内容层次展示匹配内容
  5. 高亮显示匹配文本:直观显示匹配位置
  6. Tab键补全:支持使用Tab键快速补全搜索建议

搜索建议类型

  1. 自动补全(Completion):当您输入部分词语时,系统会提供以此开头的完整词语或短语

    • 例如:输入”reac”时,可能会建议”react”、“reactjs”等
  2. 拼写纠正(Correction):当您的输入可能有拼写错误时,系统会提供更可能的正确拼写

    • 例如:输入”javascritp”时,会提示”javascript”

搜索操作指南

  1. 键盘导航

    • 使用上下箭头键在搜索建议之间切换
    • 使用Tab键或右箭头键接受当前建议
    • 使用Enter键执行搜索
  2. 建议交互

    • 系统会实时显示最相关的建议
    • 建议会以淡色显示在您的输入文本后面
    • 补全建议使用灰色显示,拼写纠正建议使用琥珀色显示
  3. 结果导航

    • 搜索结果会按相关性排序
    • 滚动到底部自动加载更多结果
    • 匹配文本会使用黄色高亮显示

快速开始

环境要求

  • Node.js 18+
  • npm 或 pnpm
  • Rust (用于开发时修改WASM组件)

安装步骤

  1. 克隆项目

    TEXT
    1
    2
    git clone https://github.com/your-username/echoes.git
    cd echoes
  2. 安装依赖

    TEXT
    1
    npm install
  3. 修改配置

    编辑 src/consts.ts 文件,更新网站配置信息。

  4. 本地运行

    TEXT
    1
    npm run dev

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

部署说明

部署方式选择

  1. Vercel 部署(推荐)

    • 支持所有功能
    • 自动部署和 HTTPS
    • 支持 API 路由和动态数据
    • 可配合多吉云 CDN 实现自动刷新缓存
  2. 静态托管(如腾讯云)

    • 仅支持静态文件
    • 不支持的功能:
      • API 路由(豆瓣数据、Git 项目等)
      • 动态数据获取
    • 需要手动配置和上传

CDN 加速配置

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

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

部署步骤

Vercel 部署

  1. Fork 项目到 GitHub
  2. 在 Vercel 导入项目
  3. 配置环境变量(如果需要)
  4. 点击部署

静态托管部署

  1. 修改 astro.config.mjs

    TEXT
    1
    2
    3
    4
    5
    export default defineConfig({
      site: SITE_URL,
      output: "static",
      adapter: undefined,
    });
  2. 构建并上传:

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

常见问题

  1. 图片无法显示

    • 检查图片路径是否正确
    • 确保图片已放入 public 目录
  2. 豆瓣数据无法获取

    • 确认豆瓣 ID 配置正确
    • 检查豆瓣记录是否公开
  3. Git 项目无法显示

    • 验证用户名配置
    • 确认 API 访问限制
  4. 静态托管部署后功能异常

    • 确认是否使用了需要服务器端支持的功能
    • 检查是否已将动态数据改为静态数据
    • 确认构建输出目录是否为 dist/client
  5. WebAssembly相关功能无法使用

    • 确保浏览器支持WebAssembly
    • 检查是否启用了内容安全策略(CSP)限制