Mahiro-Blog 新手教程（十）：导航页/项目页 JSON 数据维护与提交流程

当你把站点搭起来后，下一步常见需求是：持续维护导航资源和项目展示。

Mahiro-Blog 已经把这部分做成 JSON 数据驱动，适合长期迭代。

1. 数据位置与结构

常见目录：

• 导航数据：src/data/navigation/*.json
• 项目数据：src/data/projects/*.json

每条数据都建议保持统一字段，便于自动审核与页面稳定渲染。

2. 导航数据建议字段

一个稳定的导航项，建议至少包含：

• 名称（name）
• 描述（description）
• 链接（url）
• 标签（可选）

字段统一后，后续检索、筛选、排序都会更好维护。

3. 项目数据建议字段

结合当前项目常用结构，建议包含：

• name
• avatar
• description
• url
• badge（可选）
• tags（可选）
• author（可选）
• github（可选）

新增字段前，先确认 schema 或页面是否支持。

4. 安全的更新流程

每次改 JSON 建议走这条线：

1. 新建分支
2. 小步编辑一个文件
3. 本地 pnpm check
4. 页面预览确认展示
5. 提交 PR

这样一旦格式错了，能快速定位到具体文件。

5. 常见报错与修复

5.1 页面不显示新项

• JSON 语法是否正确（逗号、引号）
• 文件是否放在正确目录
• 字段名是否与页面读取逻辑一致

5.2 卡片样式错位

通常是数据内容过长（标题/标签），可通过：

• 增加简短描述
• 控制标签数量
• 使用 tooltip 展示全称

5.3 CI 审核失败

重点看：

• 路径是否符合工作流规则
• 字段格式是否符合要求
• 外链可访问性是否通过

6. 新手长期维护建议

• 分类命名保持稳定
• JSON 文件按功能拆分，不要全塞一个文件
• 变更提交信息写清楚“新增/修复/下线”

数据维护要靠规范，不要靠记忆。

系列导航

新手专栏目录入口