JSON 文件用途说明

本文档列出了项目中所有 JSON 文件的生成方式、存储位置和用途。

📁 文件目录结构

docs/public/data/
├── meta.json                    # 完整元数据（所有文章）
├── meta-pages/                  # 按页面切分的元数据
│   ├── index.json              # 页面索引映射表
│   └── page-{hash}.json        # 每个页面的元数据（约 5KB）
├── meta-dirs/                   # 按目录切分的元数据
│   ├── meta-{目录名}.json      # 目录完整数据
│   ├── meta-{目录名}-index.json # 目录分页索引
│   └── meta-{目录名}-page-{N}.json # 目录分页数据
├── categories.json              # 分类统计数据
├── tags.json                    # 标签统计数据
└── backlinks.json               # 反向链接数据（如果生成）

构建输出目录：
.vitepress/dist/
├── search-index.json            # 搜索索引
└── heatmap-data.json            # 热力图数据

📄 详细说明

1. meta.json

位置: docs/public/data/meta.json
生成脚本: .vitepress/scripts/genMeta.mjs
大小: 约 200-500 KB（取决于文章数量）
用途:

包含所有 Markdown 文件的完整元数据
包含 tree（文章列表）、map（路径映射）、统计信息等
用于标签过滤、分类统计等需要完整数据的场景
被 useMetaPosts.ts 作为回退方案使用

数据结构:

json

{
  "tree": [...],      // 所有文章的数组
  "map": {...},      // URL 到文章的映射
  "categoryStats": {...},
  "tagStats": {...}
}

2. meta-pages/page-{hash}.json

位置: docs/public/data/meta-pages/page-{hash}.json
生成脚本: .vitepress/scripts/splitMeta.mjs
大小: 约 5 KB（每个文件）
用途:

按页面切分的元数据，每个页面只包含自己需要的相关数据
大幅减少首屏加载时间（从 200KB+ 降到 5KB）
用于普通文章页面的元数据加载
被 useMetaPosts.ts 优先使用

文件名规则:

hash 是基于页面 URL 计算的 8 位十六进制字符串
例如：/pages/tags → page-a1b2c3d4.json

数据结构:

json

{
  "current": {...},    // 当前页面的元数据
  "related": [...],    // 相关文章（可选）
  "tree": [...],       // 统计页面的完整数据（Categories/Tags）
  "categoryStats": {...},
  "tagStats": {...}
}

3. meta-pages/index.json

位置: docs/public/data/meta-pages/index.json
生成脚本: .vitepress/scripts/splitMeta.mjs
用途:

页面 URL 到文件名的映射表
用于 Service Worker 预缓存
帮助快速查找页面对应的 meta 文件

数据结构:

json

{
  "/pages/tags": "a1b2c3d4",
  "/pages/categories": "e5f6g7h8",
  ...
}

4. meta-dirs/meta-{目录名}.json

位置: docs/public/data/meta-dirs/meta-{目录名}.json
生成脚本: .vitepress/scripts/genDirMeta.mjs
大小: 取决于目录下的文章数量
用途:

按目录组织的文章列表
用于目录页面的文章展示
被 IndexPage.vue 用于加载目录文章

文件名规则:

目录路径转换为文件名（特殊字符替换为 -）
例如：50.编程/30.Python → meta-50-30-60Python.json

数据结构:

json

[
  {
    "title": "...",
    "url": "...",
    "filePath": "...",
    ...
  },
  ...
]

5. meta-dirs/meta-{目录名}-index.json

位置: docs/public/data/meta-dirs/meta-{目录名}-index.json
生成脚本: .vitepress/scripts/genDirMeta.mjs
用途:

目录分页的索引信息
包含总页数、每页大小等信息
用于分页导航

数据结构:

json

{
  "totalPages": 3,
  "pageSize": 24,
  "total": 65
}

6. meta-dirs/meta-{目录名}-page-{N}.json

位置: docs/public/data/meta-dirs/meta-{目录名}-page-{N}.json
生成脚本: .vitepress/scripts/genDirMeta.mjs
大小: 约 20-50 KB（取决于每页文章数）
用途:

目录的分页数据
用于首页、分类页等需要分页的场景
被 IndexPage.vue 用于分页加载

数据结构:

json

{
  "posts": [...],      // 当前页的文章列表
  "pageSize": 24,
  "totalPages": 3,
  "page": 1
}

7. categories.json

位置: docs/public/data/categories.json
生成脚本: .vitepress/scripts/genCategoriesTags.mjs
大小: 约 5-10 KB
用途:

分类统计数据（分类名称和文章数量）
用于 WidgetCategories.vue 和 CategoryList.vue 组件
避免从 meta.json 加载完整数据

数据结构:

json

{
  "categories": [
    ["分类名", 文章数量],
    ...
  ],
  "filteredCategories": [...],  // 过滤后的分类（向后兼容）
  "categoryUrlMap": {...},      // 分类到 URL 的映射
  "total": 20,
  "filteredTotal": 15,
  "filterSize": 2,
  "excludeDirs": ["Pages"]
}

8. tags.json

位置: docs/public/data/tags.json
生成脚本: .vitepress/scripts/genCategoriesTags.mjs
大小: 约 10-20 KB
用途:

标签统计数据（标签名称和文章数量）
用于 WidgetTags.vue 和 KeywordCloud.vue 组件
用于标签页的统计显示
避免从 meta.json 加载完整数据

数据结构:

json

{
  "tags": [
    ["标签名", 文章数量],
    ...
  ],
  "filteredTags": [...],  // 过滤后的标签（向后兼容）
  "total": 150,
  "filteredTotal": 120,
  "filterSize": 2,
  "excludeDirs": ["Pages"]
}

9. search-index.json

位置: .vitepress/dist/search-index.json（构建输出）
生成插件: .vitepress/plugins/searchIndex.ts
大小: 约 50-200 KB（取决于文章数量）
用途:

全文搜索索引
用于客户端搜索功能
包含文章标题、内容、URL 等信息

数据结构:

json

[
  {
    "title": "...",
    "content": "...",
    "url": "...",
    ...
  },
  ...
]

10. heatmap-data.json

位置: .vitepress/dist/heatmap-data.json（构建输出）
生成插件: .vitepress/plugins/heatmapData.ts
大小: 约 5-20 KB
用途:

文章发布/更新日期热力图数据
用于 HotMap.vue 组件
显示文章的时间分布

数据结构:

json

[
  {
    "date": "2024-01-01",
    "count": 5
  },
  ...
]

11. backlinks.json（可选）

位置: docs/public/data/backlinks.json
生成脚本: .vitepress/scripts/gen-backlinks.mjs
用途:

反向链接数据（哪些文章链接到当前文章）
用于 Backlinks.vue 组件
显示文章之间的关联关系

数据结构:

json

{
  "/article/url": [
    {
      "title": "...",
      "url": "...",
      ...
    },
    ...
  ],
  ...
}

🔄 生成流程

构建时自动生成

genMeta.mjs → 生成 meta.json
splitMeta.mjs → 切分 meta.json 为 meta-pages/*.json
genDirMeta.mjs → 生成 meta-dirs/*.json
genCategoriesTags.mjs → 生成 categories.json 和 tags.json
searchIndex.ts → 生成 search-index.json
heatmapData.ts → 生成 heatmap-data.json

手动生成

bash

# 生成所有元数据
node .vitepress/scripts/genMeta.mjs

# 只生成分类和标签
node .vitepress/scripts/genCategoriesTags.mjs

# 只生成目录元数据
node .vitepress/scripts/genDirMeta.mjs

📊 使用场景

JSON 文件	使用组件	加载时机	数据大小
`meta.json`	`useMetaPosts`	回退方案、标签过滤	~200-500 KB
`meta-pages/page-*.json`	`useMetaPosts`	普通页面加载	~5 KB
`meta-dirs/meta-*.json`	`IndexPage`	目录页面	~20-50 KB
`categories.json`	`WidgetCategories`, `CategoryList`	组件初始化	~5-10 KB
`tags.json`	`WidgetTags`, `KeywordCloud`	组件初始化	~10-20 KB
`search-index.json`	`useSearch`	搜索时	~50-200 KB
`heatmap-data.json`	`HotMap`	组件初始化	~5-20 KB

⚡ 性能优化策略

按需加载: 优先加载小文件（meta-pages/page-*.json），回退到完整数据（meta.json）
分页加载: 目录数据按页加载，减少首屏数据量
缓存机制: 使用 useJsonLoader 统一缓存，避免重复请求
预生成: 所有 JSON 在构建时生成，运行时无需计算

🔍 调试技巧

查看 JSON 文件内容

bash

# 查看 meta.json 结构
cat docs/public/data/meta.json | jq '.tree | length'

# 查看标签统计
cat docs/public/data/tags.json | jq '.tags[:10]'

# 查看某个页面的 meta
cat docs/public/data/meta-pages/page-*.json | jq '.current.title'

检查文件大小

bash

# 查看所有 JSON 文件大小
find docs/public/data -name "*.json" -exec ls -lh {} \; | awk '{print $5, $9}'

📝 注意事项

文件更新: 修改 Markdown 文件后需要重新生成 JSON（构建时自动）
路径一致性: 确保 splitMeta.mjs 和 useMetaPosts.ts 的 hash 算法一致
排除规则: genCategoriesTags.mjs 的排除规则需与 IndexPage.vue 的过滤逻辑一致
缓存清理: 开发时如果 JSON 未更新，可能需要清理浏览器缓存

JSON文件用途说明

JSON 文件用途说明 ​

📁 文件目录结构 ​

📄 详细说明 ​

1. meta.json ​

2. meta-pages/page-{hash}.json ​

3. meta-pages/index.json ​

4. meta-dirs/meta-{目录名}.json ​

5. meta-dirs/meta-{目录名}-index.json ​

6. meta-dirs/meta-{目录名}-page-{N}.json ​

7. categories.json ​

8. tags.json ​

9. search-index.json ​

10. heatmap-data.json ​

11. backlinks.json（可选） ​

🔄 生成流程 ​

构建时自动生成 ​

手动生成 ​

📊 使用场景 ​

⚡ 性能优化策略 ​

🔍 调试技巧 ​

查看 JSON 文件内容 ​

检查文件大小 ​

📝 注意事项 ​

JSON 文件用途说明

📁 文件目录结构

📄 详细说明

1. meta.json

2. meta-pages/page-{hash}.json

3. meta-pages/index.json

4. meta-dirs/meta-{目录名}.json

5. meta-dirs/meta-{目录名}-index.json

6. meta-dirs/meta-{目录名}-page-{N}.json

7. categories.json

8. tags.json

9. search-index.json

10. heatmap-data.json

11. backlinks.json（可选）

🔄 生成流程

构建时自动生成

手动生成

📊 使用场景

⚡ 性能优化策略

🔍 调试技巧

查看 JSON 文件内容

检查文件大小

📝 注意事项