导航栏配置完全指南

2655 字
13 分钟
导航栏配置完全指南
AI 概括

点击按钮,AI 将为你生成这篇文章的摘要

导航栏配置完全指南#

本文档梳理 Firefly 博客导航栏的完整配置流程,涵盖目录结构、两种添加方式和常见问题排查。


目录#

  1. 目录结构总览
  2. 当前导航栏结构
  3. 方式一:使用内置预设(LinkPreset)
  4. 方式二:添加自定义导航项(NavBarLink)
  5. 完整操作流程(以”说说”为例)
  6. 快速添加自定义页面(以”书架”为例)
  7. 页面开关配置
  8. 导航栏样式配置
  9. 图标资源参考
  10. 常见问题排查
  11. 完整检查清单

目录结构总览#

src/
├── content/
│ ├── content.config.ts # 内容集合定义(spec 集合)
│ ├── spec/ # 特殊页面的 Markdown 内容
│ │ ├── about.md # 关于我
│ │ ├── friends.mdx # 友链
│ │ ├── talks.md # 说说
│ │ ├── books.md # 书架
│ │ ├── movies-games.md # 影视与游戏
│ │ ├── music.md # 音乐
│ │ ├── changelog.md # 更新日志
│ │ ├── routines.md # 规划
│ │ ├── places.md # 足迹
│ │ └── projects.md # 网站导航
│ └── posts/ # 博客文章
├── types/
│ └── config.ts # LinkPreset 枚举 + 类型定义
├── constants/
│ └── link-presets.ts # LinkPreset → NavBarLink 映射表
├── i18n/
│ ├── i18nKey.ts # 国际化键值枚举
│ └── languages/
│ ├── zh_CN.ts # 中文翻译
│ ├── en.ts # 英文翻译
│ ├── ja.ts # 日文翻译
│ ├── zh_TW.ts # 繁体中文翻译
│ └── ru.ts # 俄文翻译
├── config/
│ ├── siteConfig.ts # 站点配置(含页面开关)
│ └── navBarConfig.ts # ⭐ 导航栏链接配置(核心文件)
├── pages/ # 页面路由
│ ├── about.astro
│ ├── friends.astro
│ ├── talks.astro
│ ├── books.astro
│ ├── movies-games.astro
│ ├── music.astro
│ ├── changelog.astro
│ ├── projects.astro
│ └── life/
│ ├── routines.astro
│ └── places.astro
└── components/layout/
└── Navbar.astro # 导航栏组件(通常无需修改)

当前导航栏结构#

主页 (/) ← LinkPreset.Home
归档 (/archive/) ← LinkPreset.Archive
网站导航 (/projects/) ← 自定义 NavBarLink
留言板 (/guestbook/) ← LinkPreset.Guestbook(受开关控制)
动态 (下拉菜单 icon:local-cafe)
├── 说说 (/talks/) ← LinkPreset.Talk(受开关控制)
├── 相册 (/gallery/) ← LinkPreset.Gallery(受开关控制)
└── 留言板 (/guestbook/) ← LinkPreset.Guestbook(受开关控制)
记录 (下拉菜单 icon:camera-outdoor)
├── 书架 (/books/) ← 自定义 NavBarLink
├── 影视与游戏 (/movies-games/) ← 自定义 NavBarLink
├── 音乐 (/music/) ← 自定义 NavBarLink
├── 更新日志 (/changelog/) ← 自定义 NavBarLink
├── 规划 (/life/routines/) ← 自定义 NavBarLink
└── 足迹 (/life/places/) ← 自定义 NavBarLink
关于 (下拉菜单 icon:info)
├── 关于我 (/about/) ← LinkPreset.About
├── 友链 (/friends/) ← LinkPreset.Friends(受开关控制)
└── 赞助 (/sponsor/) ← LinkPreset.Sponsor(受开关控制)

方式一:使用内置预设(LinkPreset)#

适用于主题已提供的常用页面,只需 3 步。

可用预设列表#

预设枚举显示名称URL所需开关
LinkPreset.Home主页/-
LinkPreset.Archive归档/archive/-
LinkPreset.About关于我/about/-
LinkPreset.Friends友链/friends/pages.friends
LinkPreset.Sponsor赞助/sponsor/pages.sponsor
LinkPreset.Guestbook留言/guestbook/pages.guestbook
LinkPreset.Bangumi番组计划/bangumi/pages.bangumi
LinkPreset.Gallery相册/gallery/pages.gallery
LinkPreset.Talk说说/talks/pages.talks

操作步骤#

Step 1 — 在 src/config/navBarConfig.ts 中添加预设:

// 作为顶级菜单
links.push(LinkPreset.Gallery);
// 作为下拉子菜单(放在 children 数组中)
links.push({
name: "动态",
url: "/my/",
icon: "material-symbols:local-cafe",
children: [
...(siteConfig.pages.talks ? [LinkPreset.Talk] : []),
...(siteConfig.pages.gallery ? [LinkPreset.Gallery] : []),
],
});

Step 2 — 确保 src/config/siteConfig.ts 中对应开关为 true

pages: {
talks: true,
gallery: true,
// ...
}

Step 3 — 重启开发服务器生效。

注意:预设的名称和 URL 由主题控制,无法自定义。如需自定义名称或 URL,请使用方式二。


适用于预设列表中没有的页面,需要创建页面文件和内容文件。共 2 步(精简版),如需开关控制则 4 步。

精简版(2 步)— 无需开关控制#

Step 1 — 创建页面文件 src/pages/xxx.astro

---
import MainGridLayout from "@/layouts/MainGridLayout.astro";
import { getEntry, render } from "astro:content";
import Markdown from "@components/common/Markdown.astro";
const pagePost = await getEntry("spec", "xxx");
if (!pagePost) {
throw new Error("Page content not found");
}
const { Content } = await render(pagePost);
---
<MainGridLayout title="页面标题" description="页面描述">
<div class="flex w-full rounded-(--radius-large) overflow-hidden relative min-h-32">
<div class="card-base z-10 px-9 py-6 relative w-full">
<Markdown class="mt-2">
<Content />
</Markdown>
</div>
</div>
</MainGridLayout>

Step 2 — 创建内容文件 src/content/spec/xxx.md

---
title: 页面标题
date: 2026-05-27
---
# 页面内容
在这里写 Markdown 内容...

然后在 src/config/navBarConfig.ts 中添加导航链接(见下方代码)。

完整版(4 步)— 需要开关控制#

在精简版基础上,额外修改 2 个文件:

Step 3 — 在 src/types/config.tsSiteConfig.pages 中添加开关字段:

pages: {
// ...已有开关
xxx: true, // 新增
}

Step 4 — 在 src/config/siteConfig.ts 中设置开关值:

pages: {
// ...已有配置
xxx: true, // 新增
}

在导航栏中添加链接#

无论精简版还是完整版,都需要在 src/config/navBarConfig.ts 中添加:

// 顶级菜单
links.push({
name: "书架",
url: "/books/",
icon: "material-symbols:book-5",
});
// 下拉子菜单
links.push({
name: "记录",
url: "/records/",
icon: "material-symbols:camera-outdoor",
children: [
{ name: "书架", url: "/books/", icon: "material-symbols:book-5" },
{ name: "音乐", url: "/music/", icon: "material-symbols:music-note" },
],
});
// 外部链接(新标签页打开)
links.push({
name: "GitHub",
url: "https://github.com/yourname",
external: true,
icon: "fa7-brands:github",
});

完整操作流程(以”说说”为例)#

演示使用 LinkPreset 方式添加”说说”功能的完整 8 步流程。

Step 1:确认内容集合#

文件src/content.config.ts

确认 spec 集合已定义(通常已存在,无需修改):

const specCollection = defineCollection({
loader: glob({ pattern: "**/*.{md,mdx}", base: "./src/content/spec" }),
schema: z.object({}),
});

Step 2:创建内容文件#

文件src/content/spec/talks.md

---
title: 说说
date: 2026-05-27
---
# 我的说说
- 2026-05-27:导航栏配置完成!
- 2026-05-25:开始搭建博客。

Step 3:添加枚举值#

文件src/types/config.ts

export enum LinkPreset {
Home = 0,
Archive = 1,
About = 2,
Friends = 3,
Sponsor = 4,
Guestbook = 5,
Bangumi = 6,
Gallery = 7,
Talk = 8, // ✅ 新增(数值不能重复)
}

Step 4:添加页面开关#

文件src/config/siteConfig.ts

pages: {
// ...其他开关
talks: true, // ✅ 新增
}

Step 5:添加导航栏配置#

文件src/config/navBarConfig.ts

links.push({
name: "动态",
url: "/my/",
icon: "material-symbols:local-cafe",
children: [
...(siteConfig.pages.talks ? [LinkPreset.Talk] : []), // ✅ 新增
...(siteConfig.pages.gallery ? [LinkPreset.Gallery] : []),
],
});

Step 6:添加预设映射#

文件src/constants/link-presets.ts

[LinkPreset.Talk]: { // ✅ 新增
name: i18n(I18nKey.talks),
url: "/talks/",
icon: "material-symbols:chat",
},

Step 7:添加国际化键值#

文件src/i18n/i18nKey.ts

export enum I18nKey {
// ...其他键值
talks = "talks", // ✅ 新增(小写 camelCase)
talksDescription = "talksDescription", // ✅ 新增
}

文件src/i18n/languages/zh_CN.ts(及其他语言文件)

[Key.talks]: "说说",
[Key.talksDescription]: "我的日常动态和碎碎念",

Step 8:创建页面路由#

文件src/pages/talks.astro

---
import MainGridLayout from "@/layouts/MainGridLayout.astro";
import { getEntry, render } from "astro:content";
import Markdown from "@components/common/Markdown.astro";
import I18nKey from "@/i18n/i18nKey";
import { i18n } from "@/i18n/translation";
const talksPost = await getEntry("spec", "talks");
if (!talksPost) {
throw new Error("Talks page content not found");
}
const { Content } = await render(talksPost);
---
<MainGridLayout title={i18n(I18nKey.talks)} description={i18n(I18nKey.talksDescription)}>
<div class="flex w-full rounded-(--radius-large) overflow-hidden relative min-h-32">
<div class="card-base z-10 px-9 py-6 relative w-full">
<Markdown class="mt-2">
<Content />
</Markdown>
</div>
</div>
</MainGridLayout>

快速添加自定义页面(以”书架”为例)#

使用 NavBarLink 方式,只需 3 步(无需枚举、i18n、预设映射)。

Step 1:创建内容文件#

文件src/content/spec/books.md

---
title: 书架
date: 2026-05-27
---
# 我的书架
## 正在读
- 《深入理解 TypeScript》
## 已读完
- 《JavaScript 高级程序设计》

Step 2:创建页面文件#

文件src/pages/books.astro

---
import MainGridLayout from "@/layouts/MainGridLayout.astro";
import { getEntry, render } from "astro:content";
import Markdown from "@components/common/Markdown.astro";
const booksPost = await getEntry("spec", "books");
if (!booksPost) {
throw new Error("Books page content not found");
}
const { Content } = await render(booksPost);
---
<MainGridLayout title="书架" description="我读过的和正在读的书籍">
<div class="flex w-full rounded-(--radius-large) overflow-hidden relative min-h-32">
<div class="card-base z-10 px-9 py-6 relative w-full">
<Markdown class="mt-2">
<Content />
</Markdown>
</div>
</div>
</MainGridLayout>

Step 3:在导航栏添加链接#

文件src/config/navBarConfig.ts

// 方式 A:作为顶级菜单
links.push({
name: "书架",
url: "/books/",
icon: "material-symbols:book-5",
});
// 方式 B:作为下拉子菜单
links.push({
name: "记录",
url: "/records/",
icon: "material-symbols:camera-outdoor",
children: [
{ name: "书架", url: "/books/", icon: "material-symbols:book-5" },
// ...其他子菜单
],
});

如果需要嵌套目录(如 /life/routines/)#

src/pages/life/routines.astro ← 页面文件
src/content/spec/routines.md ← 内容文件
url: "/life/routines/" ← 导航栏中使用的 URL

页面开关配置#

文件src/config/siteConfig.tspages 对象

pages: {
friends: true, // 友链
sponsor: true, // 赞助
guestbook: false, // 留言板(关闭)
bangumi: true, // 番组计划
gallery: true, // 相册
talks: true, // 说说
}
  • true = 导航栏显示 + 页面可访问
  • false = 导航栏隐藏 + 访问返回 404

导航栏样式配置#

文件src/config/siteConfig.tsnavbar 对象

navbar: {
logo: {
type: "image", // icon | image | url
value: "assets/images/logo.webp", // 图标/图片路径
alt: "Logo",
},
title: "我的博客", // 导航栏标题
widthFull: false, // false=居中, true=全宽
menuAlign: "center", // left | center
followTheme: false, // 是否跟随主题色
stickyNavbar: true, // 是否固定顶部
},

文件src/config/backgroundWallpaper.ts → 导航栏透明效果

common: {
navbar: {
transparentMode: "semi", // semi | full | semifull
enableBlur: true, // 毛玻璃效果
blur: 10, // 模糊度
},
},

图标资源参考#

导航栏图标使用 Iconify,格式为 图标库:图标名

常用图标#

图标名说明
material-symbols:home首页
material-symbols:archive归档
material-symbols:person关于
material-symbols:group友链
material-symbols:favorite赞助
material-symbols:chat留言板
material-symbols:chat-bubble说说
material-symbols:photo-library相册
material-symbols:movie电影/影视
material-symbols:music-note音乐
material-symbols:book-5书架
material-symbols:history更新日志
material-symbols:location-on足迹
material-symbols:list-alt规划
material-symbols:camera-outdoor记录
material-symbols:local-cafe动态
material-symbols:public网站导航
material-symbols:info信息/关于
fa7-brands:githubGitHub

搜索更多图标#

访问 https://icon-sets.iconify.design/ 搜索,复制图标名即可使用。


常见问题排查#

导航栏显示空白文字#

原因:i18n 枚举键名大小写不一致。

// ❌ 错误:枚举名大写,引用小写
export enum I18nKey {
Talks = "talks", // 大写 T
}
name: i18n(I18nKey.talks), // 找不到 → 空白
// ✅ 正确:统一使用小写 camelCase
export enum I18nKey {
talks = "talks", // 小写 t
}
name: i18n(I18nKey.talks), // 匹配成功

页面 404#

可能原因排查方法
页面文件不存在检查 src/pages/xxx.astro
内容文件不存在检查 src/content/spec/xxx.md
getEntry 参数错误第二个参数是文件名(不含扩展名)
嵌套目录未创建/life/routines/ 需要 src/pages/life/ 目录

导航栏不显示菜单项#

可能原因排查方法
页面开关为 false检查 siteConfig.pages.xxx
LinkPreset 枚举值未添加检查 types/config.ts
预设映射未添加检查 constants/link-presets.ts
navBarConfig 中未添加检查 config/navBarConfig.ts

Cannot read properties of undefined (reading 'data')#

原因getEntry("spec", "xxx") 返回 undefined,说明内容文件不存在或文件名拼写错误。

import 路径报错#

// ❌ 缺少扩展名
import Markdown from "@components/common/Markdown";
// ✅ 加上 .astro 扩展名
import Markdown from "@components/common/Markdown.astro";

完整检查清单#

添加 LinkPreset 预设页面(如”说说”)#

  • src/content/spec/talks.md 已创建
  • src/types/config.tsLinkPreset 添加了 Talk = 8
  • src/config/siteConfig.tspages.talks = true
  • src/config/navBarConfig.ts 中添加了菜单项
  • src/constants/link-presets.ts 中添加了预设映射
  • src/i18n/i18nKey.ts 中添加了 talkstalksDescription
  • src/i18n/languages/zh_CN.ts(及其他语言)添加了翻译
  • src/pages/talks.astro 页面文件已创建
  • 重启开发服务器验证
  • src/content/spec/books.md 已创建
  • src/pages/books.astro 已创建
  • src/config/navBarConfig.ts 中添加了导航链接
  • 重启开发服务器验证

通用检查#

  • src/content.config.tsspec 集合已定义
  • 所有 import 路径包含 .astro 扩展名
  • 枚举值无重复
  • 所有语言文件都添加了翻译

两种方式对比#

对比项LinkPreset 预设NavBarLink 自定义
需要修改的文件8 个3 个
需要 i18n
需要枚举值
名称/URL 可自定义
适用场景主题内置页面自定义新页面
适合初学者推荐推荐

支持与分享

如果这篇文章对你有帮助,欢迎分享给更多人或赞助支持!

赞助
导航栏配置完全指南
https://f3f3.top/posts/p6a81f28c/
作者
lyf
发布于
2026-05-27
许可协议
CC BY-NC-SA 4.0

评论区

Profile Image of the Author
lyf
Hello, I'm LyF.
公告
欢迎来到一飞的博客!。
音乐
封面

音乐

暂未播放

0:00 0:00
暂无歌词
分类
标签
站点统计
文章
14
分类
5
标签
16
总字数
48,064
运行时长
0
最后活动
0 天前

文章目录

🤖 AI 助手

👋 你好!

我可以帮你解答关于这篇文章的问题