如何配置 astro-minimax 主题

astro-minimax 是一个高度可定制的 Astro 博客主题。使用 astro-minimax，你可以根据个人喜好定制一切。本文将解释如何通过配置文件轻松进行一些自定义设置。

路径提示： 如果你使用 GitHub Template 方式，配置文件位于 apps/blog/src/config.ts。如果使用 NPM 包集成方式，则位于你项目的 src/config.ts。

配置 SITE

主要配置位于 src/config.ts 文件的 SITE 对象中。以下是完整的配置示例：

export const SITE = {
  website: "https://your-domain.com/",
  author: "Your Name",
  profile: "https://your-portfolio.com/",
  desc: "A minimal, responsive and SEO-friendly Astro blog theme.",
  title: "My Blog",
  ogImage: "astro-minimax-og.jpg",
  postPerIndex: 4,
  postPerPage: 4,
  scheduledPostMargin: 15 * 60 * 1000,
  showBackButton: true,
  startDate: "2020-01-01",
  editPost: {
    enabled: true,
    text: "Edit page",
    url: "https://github.com/your-user/your-repo/edit/main/",
  },
  dynamicOgImage: true,
  dir: "ltr",
  lang: "zh",
  timezone: "Asia/Shanghai",

  features: {
    tags: true,
    categories: true,
    series: true,
    archives: true,
    friends: true,
    projects: true,
    search: true,
  },

  darkMode: true,
};

基础配置

选项	说明
`website`	部署后的网站 URL。对 SEO、规范链接和社交卡片至关重要
`author`	你的名字
`profile`	个人/作品集网站 URL，用于 SEO。没有可设为 `""`
`desc`	网站描述，用于 SEO 和社交分享
`title`	站点名称
`ogImage`	默认 OG 图片（放在 `public/` 目录下或使用外部 URL）
`postPerIndex`	首页”最近文章”显示数量
`postPerPage`	分页每页显示的文章数
`scheduledPostMargin`	定时发布的宽限时间（毫秒），默认 15 分钟
`showBackButton`	文章详情页是否显示返回按钮
`startDate`	博客起始日期，用于归档页面的时间线
`dynamicOgImage`	是否自动生成动态 OG 图片（未指定 `ogImage` 的文章）
`dir`	文本方向：`ltr`（从左到右）/ `rtl`（从右到左）/ `auto`
`lang`	默认语言代码（`zh`、`en` 等）
`timezone`	时区（IANA 格式），确保不同环境下时间戳一致

编辑链接配置

editPost: {
  enabled: true,
  text: "Edit page",
  url: "https://github.com/your-user/your-repo/edit/main/",
},

选项	说明
`enabled`	是否在文章标题下显示编辑链接
`text`	编辑链接显示文本
`url`	编辑链接的基础 URL（拼接文件路径）

配置功能开关

features 对象控制各功能模块的启用/禁用：

features: {
  tags: true,        // 标签系统
  categories: true,  // 分类系统
  series: true,      // 系列文章
  archives: true,    // 归档页面
  friends: true,     // 友链页面
  projects: true,    // 项目展示页面
  search: true,      // 全文搜索（Pagefind）
},

深色模式

darkMode: true,    // 明暗主题切换

关闭深色模式将隐藏 UI 中的主题切换按钮。

AI 聊天

AI 聊天由 SITE.ai.enabled 控制。先启用 @astro-minimax/ai 包，然后配置：

ai: {
  enabled: true,
  mockMode: true,
  apiEndpoint: "/api/chat",
  model: "@cf/zai-org/glm-4.7-flash",
},

Waline 评论

Waline 评论由 SITE.waline.enabled 控制：

waline: {
  enabled: true,
  serverURL: "https://your-waline-server.vercel.app/",
  // ...
},

赞助打赏

赞助打赏由 SITE.sponsor.enabled 控制：

sponsor: {
  enabled: true,
  methods: [
    { name: "微信支付", icon: "wechat", image: "/images/wechat-pay.svg" },
    { name: "支付宝", icon: "alipay", image: "/images/alipay.svg" },
  ],
  sponsors: [],
},

禁用某个功能后，对应的菜单项和页面将自动隐藏。

配置导航菜单

nav 对象控制导航栏显示哪些菜单项：

nav: {
  items: [
    { key: "home", enabled: true },
    { key: "posts", enabled: true },
    { key: "tags", enabled: true },
    { key: "categories", enabled: true },
    { key: "series", enabled: true },
    { key: "projects", enabled: true },
    { key: "about", enabled: true },
    { key: "friends", enabled: true },
    { key: "archives", enabled: true },
  ],
},

设置 enabled: false 可隐藏特定菜单项。菜单项的显示还受 features 开关影响——如果对应功能已禁用，菜单项也会自动隐藏。

配置项目展示

在 SITE.projects 中列出你的 GitHub 项目：

projects: [
  { repo: "souloss/astro-minimax", featured: true },
  { repo: "withastro/astro" },
  { repo: "your-user/your-project", description: "自定义描述" },
],

选项	说明
`repo`	GitHub 仓库名，格式为 `owner/name`
`featured`	是否标记为精选项目
`description`	自定义描述（不填则自动获取 GitHub 仓库描述）

更新布局宽度

整个博客的默认 max-width 是 768px（max-w-3xl）。如果你想更改它，可以在 global.css 中更新 max-w-app 工具类：

@utility max-w-app {
  @apply max-w-3xl;
  @apply max-w-4xl xl:max-w-5xl;
}

css

你可以在 Tailwind CSS 文档中探索更多值。

配置 Logo 或标题

选项 1：SITE 标题文本

最简单的选项。只需更新 SITE.title。

选项 2：Astro 的 SVG 组件

如果你想使用 SVG logo：

在 src/assets 目录中添加 SVG 文件
在 Header.astro 中导入并替换标题文本

---
import DummyLogo from "@/assets/dummy-logo.svg";
---

<a href="/" class="...">
  <DummyLogo class="scale-75 dark:invert" />
</a>

astro

选项 3：Astro 的 Image 组件

如果 logo 是位图（非 SVG）：

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

<a href="/" class="...">
  <Image src={dummyLogo} alt="My Blog" class="dark:invert" />
</a>

astro

配置社交链接

在 src/constants.ts 的 SOCIALS 对象中配置社交链接：

import IconGitHub from "@/assets/icons/IconGitHub.svg";
import IconBrandX from "@/assets/icons/IconBrandX.svg";
import IconMail from "@/assets/icons/IconMail.svg";

export const SOCIALS = [
  {
    name: "GitHub",
    href: "https://github.com/your-username",
    linkTitle: "My Blog on GitHub",
    icon: IconGitHub,
  },
  {
    name: "X",
    href: "https://x.com/your-username",
    linkTitle: "My Blog on X",
    icon: IconBrandX,
  },
  {
    name: "Mail",
    href: "mailto:your@email.com",
    linkTitle: "Send me an email",
    icon: IconMail,
  },
];

可用的内置图标：IconGitHub、IconBrandX、IconLinkedin、IconFacebook、IconTelegram、IconMail、IconWhatsapp、IconPinterest、IconRss。

配置分享链接

在 src/constants.ts 的 SHARE_LINKS 对象中配置文章分享按钮：

export const SHARE_LINKS = [
  {
    name: "X",
    href: "https://x.com/intent/post?url=",
    linkTitle: "Share on X",
    icon: IconBrandX,
  },
  // ...
];

配置 Waline 评论

astro-minimax 内置 Waline 评论系统。在 SITE.waline 中配置：

waline: {
  enabled: true,
  serverURL: "https://your-waline-server.vercel.app/",
  emoji: [
    "https://unpkg.com/@waline/emojis@1.2.0/weibo",
    "https://unpkg.com/@waline/emojis@1.2.0/bilibili",
  ],
  lang: "zh-CN",
  pageview: true,
  reaction: true,
  login: "enable",
  wordLimit: [0, 1000],
  imageUploader: false,
  requiredMeta: ["nick", "mail"],
  copyright: true,
  recaptchaV3Key: "",
  turnstileKey: "",
},

选项	说明
`enabled`	是否启用评论系统
`serverURL`	Waline 服务端地址（需自行部署）
`emoji`	表情包配置
`lang`	评论组件语言
`pageview`	是否显示页面浏览量
`reaction`	是否启用表情互动
`login`	登录模式：`enable` / `disable` / `force`
`wordLimit`	评论字数限制 `[min, max]`
`imageUploader`	是否允许上传图片
`requiredMeta`	必填字段
`copyright`	是否显示 Waline 版权信息
`recaptchaV3Key`	Google reCAPTCHA v3 密钥（可选）
`turnstileKey`	Cloudflare Turnstile 密钥（可选）

需要先部署 Waline 服务端。详见 Waline 官方文档。

配置搜索

astro-minimax 支持两种搜索方案。默认使用 Pagefind，无需额外配置。

Pagefind（默认）

内置的静态搜索引擎，构建时自动生成索引。无需任何配置即可使用。

Algolia DocSearch

如需使用 Algolia DocSearch 云搜索，在 SITE.search 中配置：

search: {
  provider: 'docsearch',
  docsearch: {
    appId: 'YOUR_ALGOLIA_APP_ID',
    apiKey: 'YOUR_ALGOLIA_SEARCH_API_KEY',
    indexName: 'YOUR_INDEX_NAME',
    placeholder: '搜索文档...',
  },
},

选项	说明
`provider`	搜索方案：`'pagefind'`（默认）或 `'docsearch'`
`docsearch.appId`	Algolia Application ID
`docsearch.apiKey`	Algolia Search-Only API Key
`docsearch.indexName`	Algolia 索引名称
`docsearch.placeholder`	搜索框占位文本

使用 DocSearch 需要申请或自建 Algolia 索引。DocSearch 组件会替换 Header 中的默认 Pagefind 搜索入口。

配置 AI 聊天

astro-minimax 内置 AI 聊天助手，基于 @astro-minimax/ai 包实现。在 SITE.ai 中配置：

ai: {
  enabled: true,
  mockMode: true,
  apiEndpoint: "/api/chat",
  model: "@cf/zai-org/glm-4.7-flash",
  welcomeMessage: undefined,
  placeholder: undefined,
},

选项	说明
`enabled`	是否启用 AI 聊天（设置为 `true`）
`mockMode`	Mock 模式下返回预设回复，不调用真实 API，适合开发调试
`apiEndpoint`	API 端点地址。使用 Cloudflare Pages Functions 时为 `/api/chat`
`model`	使用的模型 ID。默认使用 Cloudflare Workers AI 的 GLM-4.7 Flash
`welcomeMessage`	自定义欢迎消息
`placeholder`	自定义输入框占位文本

AI 聊天功能使用 Cloudflare Pages Functions 作为后端。需要在 Cloudflare 上部署并配置 AI Binding。详见 apps/blog/functions/ 目录和 wrangler.toml。

配置赞助

在 SITE.sponsor 中配置打赏功能：

sponsor: {
  enabled: true,
  methods: [
    { name: "微信支付", icon: "wechat", image: "/images/wechat-pay.svg" },
    { name: "支付宝", icon: "alipay", image: "/images/alipay.svg" },
  ],
  sponsors: [
    { name: "张三", amount: 50, date: "2026-01-15" },
  ],
},

选项	说明
`enabled`	是否启用赞助功能
`methods`	支付方式列表：`name`（名称）、`icon`（图标标识）、`image`（收款码图片路径）
`sponsors`	赞助者列表：`name`、`amount`（金额）、`date`（日期）、`platform`（平台，可选）

将收款码图片放到 public/images/ 目录下。

配置版权声明

在 SITE.copyright 中配置版权协议：

copyright: {
  license: "CC BY-NC-SA 4.0",
  licenseUrl: "https://creativecommons.org/licenses/by-nc-sa/4.0/",
},

配置 Umami 统计

在 SITE.umami 中配置 Umami 隐私友好的访问统计：

umami: {
  enabled: false,
  websiteId: "your-website-id",
  src: "https://your-umami-instance.com/script.js",
},

选项	说明
`enabled`	是否启用 Umami 统计
`websiteId`	Umami 中的网站 ID
`src`	Umami 脚本地址

需要先部署 Umami 服务。详见 Umami 官方文档。

配置字体

astro-minimax 使用 Astro 的实验性字体 API，默认使用 Google Sans Code 字体。

自定义字体

要使用不同的字体，需要更新三个地方：

astro.config.ts 中的字体配置：

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

export default defineConfig({
  experimental: {
    fonts: [
      {
        name: "Your Font Name",
        cssVariable: "--font-your-font",
        provider: fontProviders.google(),
        fallbacks: ["monospace"],
        weights: [300, 400, 500, 600, 700],
        styles: ["normal", "italic"],
      },
    ],
  },
});

Layout.astro 中的 Font 组件：

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

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

astro

global.css 中的 CSS 变量：

@theme inline {
  --font-app: var(--font-your-font);
}

css

--font-app 通过 font-app Tailwind 工具类在全站使用。

结语

这是关于如何自定义此主题的完整说明。更多功能介绍请参考功能特性总览。

如何配置 astro-minimax 主题

配置 SITE

基础配置

编辑链接配置

配置功能开关

深色模式

AI 聊天

Waline 评论

赞助打赏

配置导航菜单

配置项目展示

更新布局宽度

配置 Logo 或标题

选项 1：SITE 标题文本

选项 2：Astro 的 SVG 组件

选项 3：Astro 的 Image 组件

配置社交链接

配置分享链接

配置 Waline 评论

配置搜索

Pagefind（默认）

Algolia DocSearch

配置 AI 聊天

配置赞助

配置版权声明

配置 Umami 统计

配置字体

自定义字体

结语

评论区

偏好设置

如何配置 astro-minimax 主题

配置 SITE

基础配置

编辑链接配置

配置功能开关

深色模式

AI 聊天

Waline 评论

赞助打赏

配置导航菜单

配置项目展示

更新布局宽度

配置 Logo 或标题

选项 1：SITE 标题文本

选项 2：Astro 的 SVG 组件

选项 3：Astro 的 Image 组件

配置社交链接

配置分享链接

配置 Waline 评论

配置搜索

Pagefind（默认）

Algolia DocSearch

配置 AI 聊天

配置赞助

配置版权声明

配置 Umami 统计

配置字体

自定义字体

结语

相关推荐

设置面板与偏好设置

Cloudflare Pages 环境变量配置指南

配置 Umami 网站统计：Vercel 免费部署方案

评论区

偏好设置