导航栏配置完全指南
点击按钮,AI 将为你生成这篇文章的摘要
导航栏配置完全指南
本文档梳理 Firefly 博客导航栏的完整配置流程,涵盖目录结构、两种添加方式和常见问题排查。
目录
- 目录结构总览
- 当前导航栏结构
- 方式一:使用内置预设(LinkPreset)
- 方式二:添加自定义导航项(NavBarLink)
- 完整操作流程(以”说说”为例)
- 快速添加自定义页面(以”书架”为例)
- 页面开关配置
- 导航栏样式配置
- 图标资源参考
- 常见问题排查
- 完整检查清单
目录结构总览
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,请使用方式二。
方式二:添加自定义导航项(NavBarLink)
适用于预设列表中没有的页面,需要创建页面文件和内容文件。共 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.ts 的 SiteConfig.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.ts → pages 对象
pages: { friends: true, // 友链 sponsor: true, // 赞助 guestbook: false, // 留言板(关闭) bangumi: true, // 番组计划 gallery: true, // 相册 talks: true, // 说说}true= 导航栏显示 + 页面可访问false= 导航栏隐藏 + 访问返回 404
导航栏样式配置
文件:src/config/siteConfig.ts → navbar 对象
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:github | GitHub |
搜索更多图标
访问 https://icon-sets.iconify.design/ 搜索,复制图标名即可使用。
常见问题排查
导航栏显示空白文字
原因:i18n 枚举键名大小写不一致。
// ❌ 错误:枚举名大写,引用小写export enum I18nKey { Talks = "talks", // 大写 T}name: i18n(I18nKey.talks), // 找不到 → 空白
// ✅ 正确:统一使用小写 camelCaseexport 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.ts中LinkPreset添加了Talk = 8 -
src/config/siteConfig.ts中pages.talks = true -
src/config/navBarConfig.ts中添加了菜单项 -
src/constants/link-presets.ts中添加了预设映射 -
src/i18n/i18nKey.ts中添加了talks和talksDescription -
src/i18n/languages/zh_CN.ts(及其他语言)添加了翻译 -
src/pages/talks.astro页面文件已创建 - 重启开发服务器验证
添加自定义 NavBarLink 页面(如”书架”)
-
src/content/spec/books.md已创建 -
src/pages/books.astro已创建 -
src/config/navBarConfig.ts中添加了导航链接 - 重启开发服务器验证
通用检查
-
src/content.config.ts中spec集合已定义 - 所有 import 路径包含
.astro扩展名 - 枚举值无重复
- 所有语言文件都添加了翻译
两种方式对比
| 对比项 | LinkPreset 预设 | NavBarLink 自定义 |
|---|---|---|
| 需要修改的文件 | 8 个 | 3 个 |
| 需要 i18n | 是 | 否 |
| 需要枚举值 | 是 | 否 |
| 名称/URL 可自定义 | 否 | 是 |
| 适用场景 | 主题内置页面 | 自定义新页面 |
| 适合初学者 | 推荐 | 推荐 |
支持与分享
如果这篇文章对你有帮助,欢迎分享给更多人或赞助支持!