如何配置 AstroPaper 主题?

本文介绍 AstroPaper 的各项配置：astro-paper.config.ts 中的站点选项，以及布局宽度、Logo、社交链接、分享链接和字体的自定义方式。

目录

配置 astro-paper.config.ts

全站配置都集中在项目根目录的 astro-paper.config.ts 中。使用 defineAstroPaperConfig() 可以获得完整的编辑器智能提示：

import { defineAstroPaperConfig } from "./src/types/config";

export default defineAstroPaperConfig({
  site: {
    url: "https://your-site.com/", // 换成你实际部署的地址
    title: "AstroPaper",
    description: "A minimal, responsive and SEO-friendly Astro blog theme.",
    author: "Sat Naing",
    profile: "https://satnaing.dev",
    ogImage: "default-og.jpg",
    lang: "en",
    timezone: "Asia/Bangkok",
    dir: "ltr",
  },
  posts: {
    perPage: 4,
    perIndex: 4,
    scheduledPostMargin: 15 * 60 * 1000, // 15 分钟
  },
  features: {
    lightAndDarkMode: true,
    dynamicOgImage: true,
    showArchives: true,
    showBackButton: true,
    editPost: {
      enabled: true,
      url: "https://github.com/satnaing/astro-paper/edit/main/",
    },
    search: "pagefind",
  },
  socials: [
    { name: "github", url: "https://github.com/satnaing/astro-paper" },
    { name: "x", url: "https://x.com/username" },
    { name: "linkedin", url: "https://www.linkedin.com/in/username/" },
    { name: "mail", url: "mailto:yourmail@gmail.com" },
  ],
  shareLinks: [
    { name: "whatsapp", url: "https://wa.me/?text=" },
    { name: "facebook", url: "https://www.facebook.com/sharer.php?u=" },
    { name: "x", url: "https://x.com/intent/post?url=" },
    { name: "telegram", url: "https://t.me/share/url?url=" },
    { name: "mail", url: "mailto:?subject=See%20this%20post&body=" },
  ],
});astro-paper.config.ts

site 选项

posts 选项

features 选项

调整布局宽度

整个博客的默认 max-width 是 768px（max-w-3xl）。想改的话，修改 src/styles/global.css 中的 max-w-app 工具类：

@utility max-w-app {
  @apply max-w-3xl;
  @apply max-w-4xl xl:max-w-5xl;
}src/styles/global.css

更多可选的 max-width 取值见 Tailwind CSS 文档。

配置 Logo 或标题

有三种做法：

方式一：站点标题文字

这是最简单的做法。修改 astro-paper.config.ts 中的 site.title 即可。

方式二：Astro 的 SVG 组件

如果你想用 SVG 作为 Logo，可以选这种方式。

• 先把 SVG 放进 src/assets/ 目录（例如 src/assets/dummy-logo.svg）

• 然后在 Header.astro 中导入这个 SVG

  ---
  // ...
  import DummyLogo from "@/assets/dummy-logo.svg";
  ---src/components/Header.astro

• 最后，把 {config.site.title} 替换成导入的 Logo。

  <a
    href="/"
    class="absolute py-1 text-left text-2xl leading-7 font-semibold whitespace-nowrap sm:static"
  >
    <DummyLogo class="scale-75 dark:invert" />
    <!-- {config.site.title} -->
  </a>

这种方式的好处是可以按需自定义 SVG 样式。在上面的例子里就能看到，SVG Logo 的颜色可以在暗色模式下反相。

方式三：Astro 的 Image 组件

如果你的 Logo 是图片而非 SVG，可以用 Astro 的 Image 组件。

• 把 Logo 放进 src/assets/ 目录（例如 src/assets/dummy-logo.png）

• 在 Header.astro 中导入 Image 和你的 Logo

  ---
  // ...
  import { Image } from "astro:assets";
  import dummyLogo from "@/assets/dummy-logo.png";
  ---src/components/Header.astro

• 然后把 {config.site.title} 替换成导入的 Logo。

  <a
    href="/"
    class="absolute py-1 text-left text-2xl leading-7 font-semibold whitespace-nowrap sm:static"
  >
    <image src="{dummyLogo}" alt="我的博客" class="dark:invert" />
    <!-- {config.site.title} -->
  </a>

这种方式下你依然可以用 CSS 类调整图片外观，但未必总能满足需求。如果需要在明暗模式下显示不同的 Logo 图片，可以参考 Header.astro 组件中处理明暗图标的做法。

配置社交链接

社交链接在 astro-paper.config.ts 的 socials 数组中配置。每一项需要一个与 src/assets/icons/socials/ 下 SVG 文件名对应的 name，以及一个 url：

export default defineAstroPaperConfig({
  // ...
  socials: [
    { name: "github", url: "https://github.com/satnaing/astro-paper" },
    { name: "x", url: "https://x.com/username" },
    { name: "linkedin", url: "https://www.linkedin.com/in/username/" },
    { name: "mail", url: "mailto:yourmail@gmail.com" },
  ],
});astro-paper.config.ts

要添加默认没有的社交平台，把它的 SVG 图标放进 src/assets/icons/socials/，再往数组里加一项即可。name 必须与 SVG 文件名（不含 .svg 后缀）一致。

配置分享链接

分享链接在 shareLinks 数组中配置。每一项需要一个 name（与 src/assets/icons/socials/ 下的 SVG 对应）和一个基础 url，文章地址会被追加到该 url 之后：

export default defineAstroPaperConfig({
  // ...
  shareLinks: [
    { name: "whatsapp", url: "https://wa.me/?text=" },
    { name: "facebook", url: "https://www.facebook.com/sharer.php?u=" },
    { name: "x", url: "https://x.com/intent/post?url=" },
    { name: "telegram", url: "https://t.me/share/url?url=" },
    { name: "mail", url: "mailto:?subject=See%20this%20post&body=" },
  ],
});astro-paper.config.ts

配置字体

AstroPaper 使用 Astro 的 fonts API，默认字体为 Google Sans Code。它能在各平台上保持排版一致，并自动做预加载、缓存等字体优化。

使用默认字体

字体已在 astro.config.ts 中配置好，并由 Layout.astro 加载。使用默认的 Google Sans Code 无需任何额外配置。

更换字体

要换成别的字体，需要改三个地方：

1. 修改 astro.config.ts 中的字体配置：

import { defineConfig, fontProviders } from "astro/config";

export default defineConfig({
  // ...
  fonts: [
    {
      name: "你的字体名",
      cssVariable: "--font-your-font",
      provider: fontProviders.google(),
      fallbacks: ["monospace"],
      weights: [300, 400, 500, 600, 700],
      styles: ["normal", "italic"],
    },
  ],
});astro.config.ts

2. 修改 Layout.astro 中的 Font 组件：

---
import { Font } from "astro:assets";
// ...
---

<head>
  <!-- ... -->
  <Font
    cssVariable="--font-your-font"
    preload={[{ subset: "latin", weight: 400, style: "normal" }]}
  />
  <!-- ... -->
</head>src/layouts/Layout.astro

3. 修改 src/styles/theme.css 中的 CSS 变量映射：

@theme inline {
  --font-app: var(--font-your-font); 
  /* ... */
}src/styles/theme.css

主题各处都通过 Tailwind 的 font-app 工具类引用 --font-app 变量，所以只改这一个变量，自定义字体就会全站生效。

延伸阅读

• 自定义 AstroPaper 主题配色 —— 通过 src/styles/theme.css 修改或新增配色方案。
• 添加新文章 —— frontmatter 字段说明与文件约定。