VitePress 构建时数据加载Data Loaders完整指南从基本用法到 createContentLoader 源码解析【免费下载链接】vitepressVite Vue powered static site generator.项目地址: https://gitcode.com/gh_mirrors/vi/vitepress本文基于 VitePress 仓库中 docs/ja/guide/data-loading.md同主题亦见 docs/zh/guide/data-loading.md展开。VitePress 的数据加载器data loaders允许在构建时加载任意数据并以 JSON 的形式序列化进最终的 JavaScript 包中供.md页面与.vue组件直接导入使用。读完本文你将掌握数据加载器的完整 APIload/watch/createContentLoader/defineLoader学会用它生成博客归档、API 索引、RSS 等元数据并理解其背后的插件实现原理。数据加载器解决了什么问题VitePress 是一个以内容为中心的静态站点生成器页面数据通常来自 Markdown 的 frontmatter。但很多场景需要程序化地生成元数据例如抓取远程 API 数据在构建时渲染进页面扫描本地所有 API 文档页面自动生成入口索引读取 CSV、JSON 等数据文件转换为结构化数据供页面展示为博客生成文章归档列表标题、日期、作者、摘要。这些需求如果靠手写 frontmatter 维护既繁琐又容易出错。数据加载器的核心思路是把收集与加工数据的代码放在构建期执行运行时只消费序列化好的 JSON从而兼顾灵活性、类型安全与页面体积控制。从源码看数据加载器是 VitePress 内置 Vite 插件vitepress:data的能力定义于 src/node/plugins/staticDataPlugin.ts对.data.m?[jt]s后缀的文件匹配正则/\.data\.m?(j|t)s($|\?)/见 staticDataPlugin.ts#L15进行拦截处理。基本用法一个.data.js文件数据加载器文件必须以.data.js或.data.ts结尾并默认导出一个包含load()方法的对象export default { load() { return { hello: world } } }加载器模块只在 Node.js 环境中执行因此可以自由使用 Node API 与任意 npm 依赖比如文件系统、CSV 解析器、数据库客户端这些代码不会进入客户端包。然后在.md页面或.vue组件中通过名为data的具名导出导入script setup import { data } from ./example.data.js /script pre{{ data }}/pre页面渲染输出{ hello: world }细心的读者会发现加载器本身并没有导出data。这是因为 VitePress 在后台调用load()并把结果隐式地暴露为data具名导出。其实现位于 staticDataPlugin.ts#L143return export const data JSON.parse(${JSON.stringify(JSON.stringify(data))})也就是说插件把load()的返回值先序列化再反序列化最终以export const data ...的形式注入模块数据以 JSON 文本形式内联在客户端包中。这也解释了为什么文档强调要谨慎控制数据体积。load()也支持异步例如抓取远程数据export default { async load() { // 获取远程数据 return (await fetch(...)).json() } }插件在loadhookstaticDataPlugin.ts#L61-L67中调用loadData(id)再异步执行你定义的load因此async load()完全可行。从本地文件生成数据watch选项当需要基于本地文件生成数据时应在加载器中使用watch选项这样当这些文件发生变化时能触发热更新HMR。watch支持使用 glob 模式 匹配多个文件模式相对于加载器文件自身定位load()函数会收到匹配文件的绝对路径数组。以下示例读取 CSV 文件并用csv-parse转换为 JSONimport fs from node:fs import { parse } from csv-parse/sync export default { watch: [./data/*.csv], load(watchedFiles) { // watchedFiles 是所匹配文件的绝对路径数组 return watchedFiles.map((file) { return parse(fs.readFileSync(file, utf-8), { columns: true, skip_empty_lines: true }) }) } }因为该代码只在构建时执行CSV 解析器永远不会被发送到客户端。HMR 机制与测试佐证watch的 HMR 行为由 staticDataPlugin.ts#L69-L99 的hotUpdatehook 实现当被监听文件包括通过依赖图传递的依赖变化时插件用picomatch匹配watch模式命中则触发对应加载器模块的热更新。仓库的 e2e 测试tests/e2e/data-loading/data.test.ts 对这一行为做了完整验证修改a.json、删除b.json、再创建b.json页面内容均能通过 HMR 即时刷新。对应的加载器示例在tests/e2e/data-loading/basic.data.mts它使用defineLoader声明watch: [./data/*]在load()中过滤并解析 JSON 文件import fs from node:fs import { defineLoader } from vitepress type Data Recordstring, boolean[] export declare const data: Data export default defineLoader({ watch: [./data/*], async load(files: string[]): PromiseData { const data: Data [] for (const file of files.sort().filter((file) file.endsWith(.json))) { data.push(JSON.parse(fs.readFileSync(file, utf-8))) } return data } })createContentLoader内容型站点的归档利器对于内容为主的站点经常需要创建归档/索引页面来列出所有条目博客文章、API 页面等。直接用数据加载 API 可以实现但这是过于常见的需求因此 VitePress 提供了createContentLoader辅助函数import { createContentLoader } from vitepress export default createContentLoader(posts/*.md, /* options */)该辅助函数接收一个相对于源目录的 glob 模式源目录即 Markdown 源文件所在目录默认与项目根目录相同可通过srcDir配置项修改见 docs/zh/reference/site-config.md返回一个{ watch, load }形式的数据加载器对象可直接作为加载器文件的默认导出。它还基于文件的修改时间戳实现了缓存以提升开发性能。注意createContentLoader仅处理 Markdown 文件匹配到的其他类型文件会被跳过。ContentData类型与默认字段加载到的数据是ContentData[]类型数组interface ContentData { // 页面映射后的 URL如 /posts/hello.html不含 base // 如需标准化路径可手动处理或使用自定义 transform url: string // 页面 frontmatter 数据 frontmatter: Recordstring, any // 仅当启用对应选项时才会出现下面会介绍 src: string | undefined html: string | undefined excerpt: string | undefined }默认情况下只提供url和frontmatter。原因如前所述加载的数据会作为 JSON 内联在客户端 bundle 中必须谨慎控制体积。下面的示例用数据构建一个最简博客索引页script setup import { data as posts } from ./posts.data.js /script template h1All Blog Posts/h1 ul li v-forpost of posts a :hrefpost.url{{ post.frontmatter.title }}/a spanby {{ post.frontmatter.author }}/span /li /ul /template选项includeSrc/render/excerpt/transform默认数据未必满足所有需求可以通过选项对数据进行转换import { createContentLoader } from vitepress export default createContentLoader(posts/*.md, { includeSrc: true, // 包含原始 markdown 源码? render: true, // 包含渲染后的整页 HTML? excerpt: true, // 包含摘要? transform(rawData) { // 按需对原始数据进行 map、sort 或 filter // 最终结果即发送给客户端的内容 return rawData.sort((a, b) { return new Date(b.frontmatter.date) - new Date(a.frontmatter.date) }).map((page) { page.src // 原始 markdown 源码 page.html // 渲染后的整页 HTML page.excerpt // 渲染后的摘要 HTML第一个 --- 之前的内容 return {/* ... */} }) } })各选项的完整类型定义对应 contentLoader.ts#L17-L65 的实现interface ContentOptionsT ContentData[] { /** * 是否包含 src * default false */ includeSrc?: boolean /** * 是否将 src 渲染为 HTML 并包含在数据中 * default false */ render?: boolean /** * 若为 boolean是否解析并包含摘要渲染为 HTML * * 若为 function控制如何从内容中提取摘要 * * 若为 string定义用于提取摘要的自定义分隔符 * 当 excerpt 为 true 时默认分隔符为 --- * * default false */ excerpt?: | boolean | ((file: { data: { [key: string]: any }; content: string; excerpt?: string }, options?: any) void) | string /** * 转换数据。注意若从组件或 Markdown 文件导入 * 数据将以 JSON 形式内联到客户端包中 */ transform?: (data: ContentData[]) T | PromiseT }关于excerpt的取值从源码注释可以看出其语义布尔值控制是否提取函数可自定义提取逻辑字符串则作为gray-matter的自定义excerpt_separator分隔符。该参数最终透传给 gray-matter 处理。在构建钩子中使用createContentLoaderAPI 也可以在构建钩子中使用例如在buildEnd中基于文章元数据生成 RSS 订阅源export default { async buildEnd() { const posts await createContentLoader(posts/*.md).load() // 根据 posts 元数据生成文件如 RSS 订阅源 } }源码级实现细节createContentLoader的实现在 src/node/contentLoader.ts#L79-L184理解它能帮你更好地把握该 API 的行为边界必须处于 VitePress 进程内函数通过(global as any).VITEPRESS_CONFIG读取当前站点配置若在无活动 VitePress 进程或配置尚未解析完成时调用会直接抛错contentLoader.ts#L86-L92。缓存策略内部维护Mapfile, { data, timestamp }以文件的mtimeMs作为缓存键开发时命中缓存可显著提速contentLoader.ts#L94-L125。URL 计算对每个 Markdown 文件先求其相对源目录的路径再应用rewrites重写规则随后将index.md映射为目录根、按cleanUrls决定是否去掉.html后缀contentLoader.ts#L137-L144。渲染一致性渲染 HTML 与摘要时传入带frontmatter、cleanUrls、localeIndex等信息的 Markdown env使内部链接等插件的行为与正常页面渲染保持一致contentLoader.ts#L146-L165。并发控制使用p-map按config.buildConcurrency并发处理文件contentLoader.ts#L117-L179。e2e 中有一个完整的createContentLoader使用示例位于tests/e2e/data-loading/contentLoader.data.ts它同时开启includeSrc、excerpt、render并通过transform给每条数据追加标记字段import { createContentLoader } from vitepress export default createContentLoader(data-loading/content/*.md, { includeSrc: true, excerpt: true, render: true, transform(data) { return data.map((item) ({ ...item, transformed: true })) } })对应的断言data.test.ts#L20-L43验证了src、html、frontmatter、excerpt、url以及transform后的自定义字段均正确输出页面消费方式见tests/e2e/data-loading/data.md。类型化数据加载器defineLoader使用 TypeScript 时可以为加载器与data导出声明类型并获得加载器选项的类型检查import { defineLoader } from vitepress export interface Data { // data 的类型 } declare const data: Data export { data } export default defineLoader({ // 对加载器选项进行类型检查 watch: [...], async load(): PromiseData { // ... } })defineLoader的定义在 staticDataPlugin.ts#L46-L48它只是一个恒等函数用于让 TypeScript 根据LoaderModuleT接口推断watch、load、options的类型export function defineLoaderT(loader: LoaderModuleT): LoaderModuleT { return loader }LoaderModule接口staticDataPlugin.ts#L37-L41定义了watch、load(watchedFiles)与可选的options.globOptions。defineLoader与LoaderModule类型均从 VitePress 主入口导出见 src/node/index.ts#L13。在加载器中获取站点配置如果加载器内部需要读取配置信息如base、title、themeConfig等可以访问全局注入的VITEPRESS_CONFIGimport type { SiteConfig } from vitepress const config: SiteConfig (globalThis as any).VITEPRESS_CONFIG这也是createContentLoader内部读取配置的方式从侧面说明该全局变量在 VitePress 进程启动并解析完配置后即已就绪。结合 src/node/contentLoader.ts#L86 的抛错逻辑可知在构建钩子、数据加载器文件等进程已就绪的位置使用它是安全的。小结数据加载器的适用边界数据加载器只在构建时执行产物是内联在客户端包中的 JSON适合元数据、索引、归档等静态化数据不适合在运行时动态变化的数据那应走远程请求或 SSR 方案。.data.js/.data.ts是约定后缀load()的返回值自动暴露为data具名导出。本地文件驱动的场景务必使用watch glob 模式以享受开发期的 HMR。内容型站点优先考虑createContentLoader并善用includeSrc、render、excerpt与transform在体积与信息量之间做取舍——默认只带url与frontmatter正是出于体积考量。TypeScript 项目推荐defineLoader获得完整的类型推断与检查。如需继续深入建议阅读 src/node/contentLoader.ts 与 src/node/plugins/staticDataPlugin.ts 的完整实现并结合tests/e2e/data-loading/data.test.ts 的 HMR 断言理解其运行机制。【免费下载链接】vitepressVite Vue powered static site generator.项目地址: https://gitcode.com/gh_mirrors/vi/vitepress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考