Go back

使用astro-paper模版搭建个人博客

Updated:

Table of contents

Open Table of contents

前言

搭建个人博客有很多选择，最初我被 tailwind-nextjs-starter-blog 所吸引。它基于 Next.js 和 Tailwind CSS，功能强大，社区活跃。然而，在深入研究后，我偶然发现了 astro-paper 这个 Astro 模版。它的设计简洁、优雅，瞬间就抓住了我的眼球。

虽然 Next.js 是一个非常优秀的框架，但 Astro 在构建内容驱动的网站（如博客）方面有着独特的优势。Astro 会尽可能地将动态组件在构建时渲染成静态 HTML，从而实现极快的加载速度。这种“默认静态”的理念，对于希望为读者提供最佳访问体验的博客来说，至关重要。

最终，在“功能”和“颜值”的权衡中，我选择了后者。事实证明，astro-paper 不仅美观，功能也同样强大且易于扩展。

Astro-Paper 安装与配置

1. 初始化项目

首先，你需要一个 astro-paper 项目的副本。你可以通过 git clone 或者直接使用 create-astro 命令来初始化。

# 使用 create-astro (推荐)
npm create astro@latest -- --template satnaing/astro-paper

2. 安装依赖

进入项目目录并安装依赖。

cd your-blog-name
npm install

3. 本地开发

启动本地开发服务器，你就可以在 http://localhost:4321 看到你的博客了。

npm run dev

4. 基础配置

主要的配置文件是 src/config.ts。你可以在这里配置网站标题、作者、描述、社交链接等基本信息。

// src/config.ts
export const SITE = {
  website: "https://your-domain.com/",
  author: "Your Name",
  desc: "A minimal, responsive and SEO-friendly Astro blog theme.",
  title: "AstroPaper",
  ogImage: "astropaper-og.jpg",
  lightAndDarkMode: true,
  postPerPage: 3,
};

添加 Giscus 评论功能

astro-paper 默认支持 Giscus，一个基于 GitHub Discussions 的开源评论系统。它免费、无广告、无跟踪，并且评论数据存储在你的 GitHub 仓库中，非常适合技术博客。

与 astro-paper 默认提供的简单集成方式不同，我更推荐使用官方的 giscus-react 组件库。这种方法提供了更灵活的配置和更清晰的集成路径。

第一步：Giscus 前置准备

在开始集成之前，请确保你已经完成了以下准备工作：

  1. 创建一个公开的 GitHub 仓库: Giscus 将会把评论存储在这个仓库的 Discussions 中。
  2. 开启仓库的 Discussions 功能: 进入你的仓库 “Settings” -> “General”，找到 “Features” 部分，勾选 “Discussions”。
  3. 安装 Giscus App: 访问 Giscus App 官网，点击 “Install”，然后授权它访问你刚刚准备好的仓库。

第二步：获取 Giscus 配置信息

访问 Giscus 官网，按照页面上的指引填写你的信息：

  1. 仓库: 输入你的 用户名/仓库名，例如 test/blog。
  2. Discussion 分类: 选择一个用于存放评论的 Discussion 分类，推荐使用 Announcements。
  3. 映射关系: 选择一种页面与 Discussion 的映射关系，推荐使用 pathname。

完成填写后，页面下方会自动生成你的配置信息，包括 data-repo, data-repo-id, data-category, data-category-id 等。请妥善保管这些信息，我们马上会用到它们。

第三步：安装 giscus-react

在你的 Astro 项目根目录下，使用你的包管理器安装 giscus-react。

npm install @giscus/react

第四步：创建 Giscus 组件

先在src/constants.ts文件中添加Gis的配置信息

export const GISCUS: GiscusProps = {
  repo: "<你的用户名>/<你的仓库名>", // 替换成你的仓库
  repoId: "<你的仓库 ID>", // 替换成你的 Repo ID
  category: "Announcements", // 替换成你的 Discussion 分类
  categoryId: "<你的分类 ID>", // 替换成你的分类 ID
  mapping: "pathname",
  reactionsEnabled: "1",
  emitMetadata: "0",
  inputPosition: "bottom",
  lang: "zh-CN",
  loading: "lazy",
};

为了方便管理和复用，我们将在 src/components/ 目录下创建一个专门的 React 组件来承载 Giscus。

  1. 创建文件 src/components/Comments.tsx。
  2. 将以下代码粘贴到文件中，并替换成你在第二步获取到的配置信息。
// src/components/Comments.tsx
import Giscus, { type Theme } from "@giscus/react";
import { GISCUS } from "@/constants";
import { useEffect, useState } from "react";

interface CommentsProps {
  lightTheme?: Theme;
  darkTheme?: Theme;
}

export default function Comments({
  lightTheme = "light",
  darkTheme = "dark",
}: CommentsProps) {
  const [theme, setTheme] = useState(() => {
    const currentTheme = localStorage.getItem("theme");
    const browserTheme = window.matchMedia("(prefers-color-scheme: dark)")
      .matches
      ? "dark"
      : "light";

    return currentTheme || browserTheme;
  });

  useEffect(() => {
    const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
    const handleChange = ({ matches }: MediaQueryListEvent) => {
      setTheme(matches ? "dark" : "light");
    };

    mediaQuery.addEventListener("change", handleChange);

    return () => mediaQuery.removeEventListener("change", handleChange);
  }, []);

  useEffect(() => {
    const themeButton = document.querySelector("#theme-btn");
    const handleClick = () => {
      setTheme(prevTheme => (prevTheme === "dark" ? "light" : "dark"));
    };

    themeButton?.addEventListener("click", handleClick);

    return () => themeButton?.removeEventListener("click", handleClick);
  }, []);

  return (
    <div className="mt-8">
      <Giscus theme={theme === "light" ? lightTheme : darkTheme} {...GISCUS} />
    </div>
  );
}

注意: 上述代码中，我们通过 localStorage 获取了当前的主题状态，并将其传递给 Giscus，实现了评论区主题的自动切换。你需要根据你项目中实际的主题管理方式进行调整。如果你的博客没有深色模式，可以将 theme 属性硬编码为 'light'。

第五步：在文章页面中引入 Giscus 组件

最后一步，我们需要在文章详情页中引入并渲染 Comments 组件。astro-paper 的文章布局文件通常是 src/layouts/PostDetails.astro。

打开该文件，在文章内容的末尾、页脚之前的位置，添加以下代码：

---
// src/layouts/PostDetails.astro
// ... 其他 imports
import Comments from "@/components/Comments";
---

<!-- ... 文章内容 ... -->

<Comments client:only="react" />

<!-- ... 页脚 ... -->

现在，重新启动你的开发服务器，访问任意一篇非草稿的文章，你应该就能在页面底部看到 Giscus 评论区了。

添加 RSS 订阅功能

RSS 订阅对于博客来说是一个非常重要的功能，它可以让读者通过 RSS 阅读器来订阅你的最新文章。astro-paper 已经内置了 RSS 功能，你只需要确保配置正确即可。

Astro 的 @astrojs/rss 包会自动根据你的文章生成 RSS feed。你可以在 src/pages/rss.xml.js 文件中查看和修改 RSS 的生成逻辑。通常情况下，你不需要做任何修改。

你的 RSS 订阅链接将会是 https://your-domain.com/rss.xml。

开启 Google Analytics 网站分析

为了更好地了解你的博客读者，例如他们来自哪里、喜欢哪些文章，集成 Google Analytics (GA) 是一个非常好的选择。它可以为你提供宝贵的网站流量和用户行为数据。

第一步：获取 Google Analytics Measurement ID

  1. 登录 Google Analytics: 使用你的 Google 账号登录 Google Analytics 官网。
  2. 创建媒体资源 (Property):
    • 进入“管理” (Admin) 页面。
    • 点击“创建媒体资源” (Create Property)。
    • 填写你的博客名称、选择时区和货币。
  3. 设置数据流 (Data Stream):
    • 在“数据收集” (Data Collection) 部分，选择“网站” (Web)。
    • 输入你的博客域名，并为数据流命名。
    • 点击“创建数据流” (Create stream)。
  4. 复制衡量 ID (Measurement ID): 创建成功后，你会看到一个以 G- 开头的“衡量 ID”。复制这个 ID，我们稍后会用到它。

第二步：在 Astro 中创建 GA 组件

为了保持代码的整洁和模块化，我们为 Google Analytics 创建一个专门的 Astro 组件。

  1. 创建文件 src/components/GoogleAnalytics.astro。
  2. 将以下代码粘贴到文件中。这段代码会向你的网站头部注入 Google Analytics 的 gtag.js 脚本。
---
// src/components/GoogleAnalytics.astro
import { SITE } from '@/config';

const { googleAnalyticsId } = SITE;
---

{
 googleAnalyticsId && (
    <>
      <script is:inline async src={`https://www.googletagmanager.com/gtag/js?id=${googleAnalyticsId}`}></script>
      <script is:inline define:vars={{ googleAnalyticsId }}>
        window.dataLayer = window.dataLayer || [];
        function gtag() {
          dataLayer.push(arguments);
        }
        gtag("js", new Date());
        gtag("config", googleAnalyticsId);
      </script>
    </>
  )
}

第三步：配置并引入 GA 组件

  1. 添加配置: 打开 src/config.ts 文件，在 SITE 对象中添加你的 googleAnalyticsId。
// src/config.ts
export const SITE = {
  // ... 其他配置
  googleAnalyticsId: "G-XXXXXXXXXX", // 替换成你的 Measurement ID
};
  1. 引入组件: 打开你项目的基础布局文件，通常是 src/layouts/BaseLayout.astro (文件名可能因你的项目结构而异)。在 <head> 标签的末尾，添加我们刚刚创建的 GoogleAnalytics 组件。
---
// src/layouts/BaseLayout.astro
import GoogleAnalytics from '@/components/GoogleAnalytics.astro';
// ... 其他 imports
---
<html lang="en">
  <head>
    <!-- ... 其他 head 内容 ... -->
    <GoogleAnalytics />
  </head>
  <body>
    <!-- ... body 内容 ... -->
  </body>
</html>

完成以上步骤后，当你将网站编译并部署到生产环境时，Google Analytics 就会开始自动收集访问数据了。你可以在 GA 的报告中查看详细信息。

编译与部署到 Cloudflare

1. 编译项目

运行以下命令来编译你的博客。

npm run build

这个命令会生成一个 dist/ 目录，里面包含了所有可以部署的静态文件。

2. 部署到 Cloudflare Pages

Cloudflare Pages 是一个非常适合部署静态网站的平台，它提供免费的额度、自动的 HTTPS 和全球 CDN 加速。

  1. 登录 Cloudflare: 登录你的 Cloudflare 账号。
  2. 创建项目: 在 “Workers & Pages” 菜单中，选择 “Create application” -> “Pages” -> “Connect to Git”。
  3. 连接仓库: 选择你的博客所在的 GitHub 仓库。
  4. 配置构建:
    • Production branch: 选择你的主分支 (通常是 main 或 master)。
    • Framework preset: 选择 “Astro”。
    • Build command: npm run build
    • Build output directory: dist
  5. 保存并部署: 点击 “Save and Deploy”。Cloudflare 会自动拉取代码、编译并部署你的网站。

部署完成后，你就可以通过 Cloudflare 提供的域名访问你的博客了。你也可以绑定自己的域名。

至此，一个基于 astro-paper 的、功能完善的个人博客就搭建完成了。享受写作和分享的乐趣吧！

Share this post on:
Share this post via WhatsAppShare this post on FacebookShare this post on XShare this post via TelegramShare this post on PinterestShare this post via email