Mahiro-Blog 新手教程（一）：从 0 到 1 改配置文件（mahiro.config.yaml）

如果你是第一次二开 Mahiro-Blog，最容易卡住的不是写组件，而是“配置改了但页面没变化”。

这篇就专门解决这个问题：先教你改对，再教你扩展。

1. 配置系统的核心思路

先记住这句话：

• mahiro.config.yaml 负责“写数据”
• src/config.ts 负责“导出数据”
• 页面/组件负责“消费数据”

只改了 YAML 但没导出，组件拿不到。
只改了导出但 YAML 没值，组件可能拿到 undefined。

所以你每次新增配置，都要走完整链路。

2. 新手优先改这 6 类字段

建议按收益排序：

1. site.title：站点标题
2. site.description：站点描述
3. site.menu：导航栏菜单
4. site.banner：Banner 图和默认模式
5. user.name / user.avatar / user.site：个人信息
6. user.sidebar.social / user.footer.social：社交链接

这些配置改完，站点“像你自己的”程度会立刻提升。

3. 一套稳定的修改流程（照做就不容易翻车）

每次改配置，固定 5 步：

1. 新建分支（或先备份）
2. 只改一组字段
3. 运行 pnpm check
4. 本地 pnpm dev 看页面
5. 最后 pnpm build 做发布前验证

这套流程能把问题定位到很小范围。

4. 新增一个配置项的完整示例

目标：新增 site.noticeText，在页面中显示公告文案。

第一步：在 mahiro.config.yaml 加字段

site:
  noticeText: "欢迎来到我的博客 👋"

第二步：在 src/config.ts 导出（要兜底）

export const SITE_NOTICE_TEXT = config.site.noticeText || ""

第三步：组件里消费

{SITE_NOTICE_TEXT && <p>{SITE_NOTICE_TEXT}</p>}

注意点：

• 一定要有默认值
• 组件使用前判断空值
• 不要直接假设配置永远存在

5. YAML 最常见错误（90% 新手会遇到）

5.1 缩进不一致

YAML 对缩进很严格，建议统一 2 空格。

5.2 布尔值写成字符串

错误：

draft: "false"

正确：

draft: false

5.3 数组写成逗号字符串

错误：

tags: "Astro, 教程"

正确：

tags:
  - Astro
  - 教程

6. 改了配置但不生效？按这个顺序查

1. YAML 是否可解析（缩进、冒号、列表）
2. 字段名是否和 src/config.ts 一致
3. 组件是否真的用了这个导出
4. 运行 pnpm check 是否报错
5. 重新启动 dev 再看

这条链路排查下来，基本都能定位到根因。

7. 给新手的配置改造建议

• 先改“已有字段”，再新增字段
• 先追求可用，再追求优雅
• 一次只改一个区域（站点信息 / 导航 / banner）

你会发现：配置系统其实是你二开的“控制台”，用得越熟，改站越快。

系列导航

新手专栏目录入口