Astro-Theme-Aither 使用指南

本指南涵盖从零开始到完成部署多语言博客的全部内容。你可以从头读到尾，也可以直接跳到需要的章节。

前置条件

• Node.js 22 LTS 或更高版本
• pnpm 10 或更高版本
• 一个 GitHub 账号
• 一个 Cloudflare 账号（用于部署）

安装

git clone https://github.com/YOUR_USERNAME/YOUR_REPO.git
cd YOUR_REPO
corepack enable
pnpm install
pnpm validate
pnpm dev

在浏览器中打开 http://localhost:4321，你会看到默认的博客页面。

项目结构

1
src/
2
├── components/        # Astro 和 React 组件
3
├── config/site.ts     # 站点名称、导航、页脚、社交链接
4
├── content/posts/     # 按语言组织的博客文章
5
│   ├── en/            # 英文文章
6
│   ├── zh-hans/       # 简体中文文章
7
│   └── .../           # 其他语言
8
├── i18n/              # UI 文本翻译
9
├── layouts/           # 页面布局 (Layout.astro)
10
├── lib/               # 工具函数 (posts, formatter 等)
11
├── pages/             # 路由页面
12
└── styles/global.css  # Tailwind v4 主题变量

配置

站点配置

编辑 src/config/site.ts——这是整个站点的唯一配置来源。

1
export const siteConfig = {
2
  name: '你的博客名称',
3
  title: '你的标语。',
4
  description: '你的站点描述，用于 SEO。',
5
  author: {
6
    name: '你的名字',
7
    avatar: '',
8
  },
9
  // ...
10
};

主要配置项：

环境变量

将 .env.example 复制为 .env 并填入你的值：

cp .env.example .env

留空即可禁用对应服务，无需修改代码。

站点 URL

站点 URL 只需在一处配置——astro.config.mjs：

1
import { defineConfig } from 'astro/config';
2
import aither from '@aither/astro';
3

4
export default defineConfig({
5
  site: 'https://your-domain.pages.dev',
6
  integrations: [aither()],
7
});

所有组件通过 import.meta.env.SITE 读取该值，无需在其他地方重复配置。

写文章

创建文章

在 src/content/posts/en/ 下创建一个新的 .mdx 文件：

1
---
2
title: 我的第一篇文章
3
date: "2026-03-14T16:00:00+08:00"
4
category: General
5
description: 用于 SEO 和社交预览的简短摘要。
6
tags: [Topic, Another]
7
pinned: false
8
---
9

10
正文从这里开始。使用标准 Markdown 语法。

Frontmatter 参考

MDX 组件

所有文章均使用 .mdx 格式，你可以直接在文章中导入和使用 React 组件：

1
import MyChart from '@/components/MyChart'
2

3
这是一个交互式图表：
4

5
<MyChart data={[10, 20, 30]} />

这是可选的——.mdx 文件中标准 Markdown 语法完全一样可用。

置顶文章

在 frontmatter 中设置 pinned: true。置顶文章会显示在列表顶部并带有置顶图标，置顶文章之间按日期排序。

国际化（i18n）

主题开箱即支持 11 种语言：英语、简体中文、繁体中文、韩语、法语、德语、意大利语、西班牙语、俄语、印度尼西亚语和巴西葡萄牙语。

添加翻译文章

在目标语言目录下创建同名文件：

1
src/content/posts/en/my-post.mdx      # 英文原文
2
src/content/posts/zh-hans/my-post.mdx  # 中文翻译
3
src/content/posts/fr/my-post.mdx       # 法文翻译

每个文件是独立的——frontmatter 字段也需要翻译。

翻译 UI 文本

UI 文本（导航、页脚、按钮）位于 src/i18n/messages/，每种语言有独立的文件：

1
src/i18n/messages/
2
├── en.ts
3
├── zh-hans.ts
4
├── fr.ts
5
└── ...

编辑对应文件即可更改任何 UI 文本。

浏览器语言检测

主题会检测访客的浏览器语言，并显示横幅建议切换语言。用户的偏好保存在 localStorage 中。

自定义内容分区

除了博客文章，你还可以创建自定义内容分区（译文、笔记、教程等），每个分区自动拥有独立的列表页、详情页和导航入口。

添加分区

第 1 步——在 src/content.config.ts 中注册集合：

1
const translations = defineCollection({
2
  loader: glob({ pattern: '**/*.mdx', base: './src/content/translations' }),
3
  schema: contentSchema,
4
});
5

6
export const collections = { posts, translations };

第 2 步——在 src/config/site.ts 中添加分区配置：

1
sections: [
2
  { id: 'translations', labelKey: 'translations' },
3
],

第 3 步——在 src/i18n/messages/ 的每个语言文件中添加导航标签：

1
nav: {
2
  blog: '博客',
3
  translations: '译文',  // 添加这一行
4
  about: '关于',
5
},

第 4 步——在 src/content/translations/en/ 中创建内容：

1
---
2
title: 我的翻译
3
date: "2026-03-14T16:00:00+08:00"
4
category: General
5
---
6

7
你的翻译内容。

列表页（/translations/）、详情页（/translations/slug/）和导航入口会自动为所有 11 种语言生成。

主题定制

模式与风格

主题现在分成两层：

• 显示模式：浅色、深色、系统（跟随操作系统偏好）
• 风格主题：default 或任意内置自定义风格，例如 evolution

默认值在 src/config/site.ts 中配置：

1
ui: {
2
  defaultMode: 'system', // 'light' | 'dark' | 'system'
3
  defaultStyle: 'default', // 'default' | 自定义风格 key
4
  showMoreThemesMenu: true, // true 表示显示自定义主题选择器
5
},

选择浅色、深色或系统时，会回到主模式；选择自定义风格时，会保留当前的模式偏好，方便后续切回。主题切换继续使用 View Transitions API，实现平滑的圆形展开动画。

如果你想让主题 UI 更简洁，可以保留模式切换，并把 showMoreThemesMenu 设为 false。这样会隐藏自定义风格列表，但仍保留浅色 / 深色 / 系统三档切换。

主题展示名和主题 key 是分开的：

• evolution、threebody 这类主题 key 保持稳定，只用于状态和 CSS 选择
• 面向用户的主题名称统一集中在 src/config/themes.ts
• 本地化时优先翻译通用描述词；品牌名或强 IP 名称可以按目标语言保留一部分原名

这样既能保证代码层稳定，也能让不同语言下的主题命名更自然。

颜色

编辑 src/styles/global.css 中的 CSS 自定义属性。主题使用 Tailwind CSS v4 的 @theme 变量：

1
:root {
2
  --color-link: ...;
3
  --color-link-hover: ...;
4
  --color-nav-text: ...;
5
  /* 等等 */
6
}

浅色和深色模式各有一套独立的颜色变量。

字体

主题默认使用系统无衬线字体栈，遵循 Apple Human Interface Guidelines 排版参数（17px / 1.47 / -0.022em）。如需使用自定义字体，请在 Tailwind 主题配置中更新 font-family 值。

SEO 和 AI

每个页面都针对搜索引擎和 AI 智能体进行了优化：

部署

Cloudflare Pages

最佳实践：先创建 Pages 项目。工作流默认使用仓库名；如果需要覆盖，请设置 CLOUDFLARE_PAGES_PROJECT_NAME。

设置这些 GitHub Secrets：

然后运行 pnpm validate，再推送到 main。

自定义域名

在 Cloudflare Pages 控制台的项目设置 → 自定义域名中添加。

技术栈

常用命令

版本规则

公开发布的 release tag 使用 CalVer 风格命名，例如 v2026.04.08。