站点配置详解

配置分成三层

云图札记配置分成三层：

层次	文件	职责
框架配置	astro.config.mjs	站点 URL、集成插件、适配器
站点配置	src/site.config.mjs	站名、博主、导航、社交链接
内容配置	src/content.config.ts	博文 Frontmatter 字段定义

另外还有几个数据文件：

文件	用途
src/changelog.json	版本更新日志
src/friends.json	友链数据
src/gear.json	装备页数据
src/steam_games.json	Steam 游戏时长榜数据

---

框架配置（astro.config.mjs）

import mdx from '@astrojs/mdx';
import sitemap from '@astrojs/sitemap';
import { defineConfig } from 'astro/config';

export default defineConfig({
  site: 'https://blog.lzplus.top',  // ⚠️ 必填，影响 RSS 和 sitemap
  integrations: [mdx(), sitemap()],
});

关键字段

• site：站点完整 URL，RSS feed 和 sitemap 依赖此值，务必与实际域名一致
• integrations：
• mdx() — 支持 .mdx 文件，可以在 Markdown 中使用组件
• sitemap() — 自动生成 sitemap-index.xml

当前未配置适配器字段。生产构建时如果部署到 Cloudflare Pages，框架会自动检测并使用 @astrojs/cloudflare。

---

站点配置（site.config.mjs）

这是最常修改配置文件，包含所有站点级信息。

SITE — 站点信息

export const SITE = {
  title: '云图札记',                      // 站名，显示在导航栏和标题
  subtitle: '记录云端与图景之间的思考',      // 副标题
  description: '关于技术、设计与生活的个人博客', // 站点描述，用于 SEO
  url: 'https://blog.lzplus.top',          // 站点 URL
  startYear: 2022,                         // 建站年份，用于版权和统计
};

AUTHOR — 博主信息

export const AUTHOR = {
  name: '公爵',                            // 博主昵称，显示在首页侧边栏和文章信息卡
  bio: 'P社战帅 / 游戏爱好者 / 写作者',     // 简短标签
  motto: '在云端俯瞰图景，在图景中寻找云的方向。', // 座右铭
  description: '一个在云端与图景之间探索的人...',  // 详细自我介绍
  location: '中国',                         // 所在地
};

NAV_LINKS — 导航菜单

export const NAV_LINKS = [
  { name: '首页', path: '/' },
  { name: '装备', path: '/gear' },
  { name: '归档', path: '/archive' },
  { name: '关于', path: '/about' }
];

增删导航项只需编辑这个数组。每个对象需要 name（显示文本）和 path（路由路径）。

SOCIAL_LINKS — 社交链接

export const SOCIAL_LINKS = [
  { name: 'GitHub', icon: 'github', url: 'https://github.com/gongjuecloak' },
  { name: 'B站', icon: 'bilibili', url: 'https://space.bilibili.com/3054324' },
  { name: '邮箱', icon: 'mail', url: 'mailto:763771418@qq.com' }
];

支持的 icon 名称：github、bilibili、mail、twitter、rss 等。社交链接显示在关于页和页脚。

FOOTER — 页脚

export const FOOTER = {
  copyright: `©${new Date().getFullYear()} By ${AUTHOR.name}`,
  powered: 'Astro & CloakBlog',
};

版本号自动从 changelog.json 读取最新条目，无需手动配置。

---

内容配置（content.config.ts）

定义博文 Frontmatter 字段和校验规则：

schema: ({ image }) =>
  z.object({
    title: z.string(),                         // 必填：文章标题
    description: z.string(),                   // 必填：文章简介
    pubDate: z.coerce.date(),                  // 必填：发布日期
    updatedDate: z.coerce.date().optional(),   // 可选：更新日期
    heroImage: z.optional(image()),            // 可选：封面图
    category: z.string().default('技术分享'),   // 分类，默认"技术分享"
    tags: z.array(z.string()).default([]),     // 标签数组
    pinned: z.boolean().default(false),         // 是否置顶
    series: z.string().optional(),             // 系列名称
    seriesOrder: z.number().optional(),        // 系列内排序
  }),

---

主题与样式

CSS 变量体系

全局样式定义在 src/styles/global.css，通过 CSS 变量控制主题：

:root {
  /* 主色调 */
  --color-primary: #C45209;

  /* 文字层级 */
  --text-primary: #1a1a1a;
  --text-secondary: #4a4a4a;
  --text-tertiary: #888;

  /* 边框 */
  --border-color: #e0e0e0;
  --border-color-strong: #bbb;

  /* 圆角 */
  --radius-sm: 4px;
  --radius-full: 9999px;

  /* 过渡 */
  --transition-fast: 0.1s linear;
}

修改主色调只需改 --color-primary，所有使用该变量组件会自动更新。

暗色模式

暗色模式通过 [data-theme="dark"] 选择器覆盖变量：

[data-theme="dark"] {
  --text-primary: #e8e8e8;
  --text-secondary: #a8a8a8;
  --border-color: #2a2a2a;
}

主题切换逻辑在 ThemeScript.astro 中，优先读取 localStorage 中的用户偏好。

分类颜色

分类颜色由 utils.ts 中的 getCategoryColor() 自动生成，基于分类名哈希映射到 15 色调色板：

const PALETTE = [
  '#C45209', '#57BD6A', '#E74C8B', '#F39C12', '#9B59B6',
  '#00BCD4', '#E67E22', '#1ABC9C', '#3498DB', '#E91E63',
  '#8E44AD', '#27AE60', '#D35400', '#2ECC71', '#C0392B',
];

不需要手动配置颜色，同名的分类永远映射到同一颜色。

---

排版系统

正文

• 字体：Instrument Sans（正文），17px
• 行高：2.0
• 首行缩进：2em
• 最佳阅读宽度：720px（--reading-width）
• 正文色：#1a1a1a（暗色模式 #e8e8e8）

UI 文字

• 字体：Instrument Sans
• 导航/标题/按钮均继承此字体
• 全局修复：button, input, select, textarea { font-family: inherit; }

代码

• 字体：JetBrains Mono
• 主题：gruvbox-dark-soft（Expressive Code）
• 行号：默认显示

---

常见定制

添加新导航项

编辑 src/site.config.mjs 的 NAV_LINKS，然后创建对应页面文件（如 src/pages/new-page.astro）。

修改主色调

编辑 src/styles/global.css 中的 --color-primary 值。搜索全站硬编码 #C45209 替换为新色值。

添加新分类

不需要任何配置，直接在博文 category 字段写新分类名即可。颜色会自动生成，首页侧边栏和归档页会自动显示。

修改字体

1. 编辑 src/styles/global.css 中的 font-family 声明
2. 确保字体能通过 Google Fonts CDN 加载或本地托管
3. 国内服务器需注意 CDN 可达性，建议在 CSS 中提供完整回退链

---

CSS 反模式提醒

• ❌ 不要用 transition: all：会让首次渲染属性初始化也产生动画，导致闪烁。应明确指定属性：transition: color 0.15s ease
• ❌ 不要只用 Astro scoped <style> 处理 JS 动态 DOM：scoped CSS 通过属性选择器匹配，JS 动态生成 DOM 无法匹配。改用 <style is:inline>
• ⚠️ <style is:inline> 放在 body 底部会导致 CSS 延迟加载：对需要初始隐藏元素（如搜索弹窗）必须加内联 style="opacity:0;visibility:hidden" 防 FOUC

MEDIA:/home/ubuntu/CloakBlog/src/content/blog/config-guide.md