VitePress Site Config 完全指南站点级配置项全解与源码级原理剖析【免费下载链接】vitepressVite Vue powered static site generator.项目地址: https://gitcode.com/gh_mirrors/vi/vitepressSite Config 是 VitePress 站点全局配置的入口它定义了独立于主题的通用设置——从站点标题、head标签、多语言到构建产物路径与 CDN 资源分发再到构建钩子与页面数据变换。本文以官方参考文档为主体结合当前仓库的 配置解析源码 与 类型声明逐项讲解每个配置选项的类型、默认值、可覆盖层级并给出可直接复制的实战示例帮助你完全掌握 VitePress 的站点级配置体系。配置解析机制配置文件从哪来VitePress 的配置文件始终从root/.vitepress/config.[ext]解析其中root是你的 VitePress 项目根目录[ext]是受支持的扩展名之一。在 src/node/config.ts 中可以看到受支持的配置文件扩展名被硬编码为const supportedConfigExtensions [js, ts, mjs, mts]也就是说 TypeScript 开箱即用无需任何额外配置。此外config/index.[ext]与config.[ext]两种形态都会被识别解析顺序是先index目录形态再顶层文件形态见 resolveUserConfig。配置解析发生在resolveConfig中它会读取用户配置、归一化root、srcDir、assetsDir、outDir、cacheDir等路径解析站点数据并最终构建出完整的SiteConfig对象包含pages、rewrites、dynamicRoutes等派生信息同时把配置挂到全局VITEPRESS_CONFIG上供内容加载器共享。推荐使用 ES Modules 语法配置文件的入口应该默认导出一个对象export default { // app level config options lang: en-US, title: VitePress, description: Vite Vue powered static site generator., ... }从源码看resolveConfigExtends会先判断配置是否为函数并调用它typeof config function ? config() : config因此以下两种“动态配置”写法都被支持可用于从 CMS、远程接口等动态生成配置方式一默认导出 async 函数import { defineConfig } from vitepress export default async () { const posts await (await fetch(https://my-cms.com/blog-posts)).json() return defineConfig({ // app level config options lang: en-US, title: VitePress, description: Vite Vue powered static site generator., // theme level config options themeConfig: { sidebar: [ ...posts.map((post) ({ text: post.name, link: /posts/${post.name} })) ] } }) }方式二顶层await需要 ESM 环境import { defineConfig } from vitepress const posts await (await fetch(https://my-cms.com/blog-posts)).json() export default defineConfig({ // app level config options lang: en-US, title: VitePress, description: Vite Vue powered static site generator., // theme level config options themeConfig: { sidebar: [ ...posts.map((post) ({ text: post.name, link: /posts/${post.name} })) ] } })配置继承extendsUserConfig还提供了extends选项见 siteConfig.ts用于继承一份基础配置其值会被递归合并并被当前配置覆盖。resolveConfigExtends会递归解析extends链并调用mergeConfig完成合并——数组会拼接对象会递归合并其中vite与markdown走专门的合并逻辑。这非常适合多个站点共享一份公共主题基座配置的场景。配置智能提示与类型化主题配置Config IntellisensedefineConfig使用defineConfig辅助函数即可获得基于 TypeScript 的配置项智能提示。在 JavaScript 与 TypeScript 中均可用前提是 IDE 支持import { defineConfig } from vitepress export default defineConfig({ // ... })源码层面的实现非常简单config.tsexport function defineConfigThemeConfig DefaultTheme.Config( config: UserConfigNoInferThemeConfig ) { return config }它本身不改变运行时行为纯粹提供类型约束与提示。Typed Theme ConfigdefineConfigWithTheme默认情况下defineConfig期望的themeConfig类型来自默认主题DefaultTheme.Configimport { defineConfig } from vitepress export default defineConfig({ themeConfig: { // Type is DefaultTheme.Config } })如果你使用自定义主题并希望themeConfig获得类型检查需要使用defineConfigWithTheme并通过泛型参数传入自定义主题的配置类型import { defineConfigWithTheme } from vitepress import type { ThemeConfig } from your-theme export default defineConfigWithThemeThemeConfig({ themeConfig: { // Type is ThemeConfig } })从源码注释可以看到该函数已被标记为deprecatedconfig.ts官方推荐改用泛型化的defineConfig但该 API 仍被保留以兼容自定义主题场景。Vite、Vue 与 Markdown 的配置入口Site Config 提供了三个“透传”选项让你无需创建独立的 Vite 配置文件Vite使用配置中的vite选项配置底层 Vite 实例无需单独的 Vite 配置文件VueVitePress 已内置官方 Vue 插件vitejs/plugin-vue可通过vue选项配置其参数Markdown可通过markdown选项配置底层的 Markdown-It 解析器实例。页面级与目录级覆盖页面级覆盖Frontmatter部分设置可以通过页面 frontmatter 覆盖详见 Frontmatter 配置。目录级覆盖additionalConfig部分配置可以在目录层级覆盖使该目录下所有页面共享设置而无需在每个页面的 frontmatter 中重复声明。实现方式是在相关目录中添加一个名为config.ts或.js、.mjs、.mts的文件用export default导出配置对象与主配置文件类似。嵌套目录会继承父目录的设置覆盖项会被合并。defineAdditionalConfig辅助函数可为可用选项提供 TypeScript 智能提示与defineConfig一样使用是可选的。例如对于一个多语言站点我们希望每种语言有各自的description可以在es/config.ts中写入import { defineAdditionalConfig } from vitepress export default defineAdditionalConfig({ description: Generador de Sitios Estáticos desarrollado con Vite y Vue. })这样es目录下所有页面都会使用该description。源码实现细节目录级配置的收集在 gatherAdditionalConfig 中完成——它通过 glob 模式**/config.{js,mjs,ts,mts}在srcDir下扫描所有config.*文件受srcExclude过滤逐个加载并按键目录路径聚合成additionalConfig字典。合并发生在resolveSiteDataByRoute见 shared.ts它会按“additionalConfig 栈 → locale 配置 → 根配置”的顺序叠加目录越深优先级越高配置按目录路径排序深层目录覆盖浅层。该功能由UserConfig.additionalConfig选项控制可显式设置为{}来关闭自动收集。另外使用内置 i18n 功能时语言目录的设置也可以通过主配置文件中的locales设置覆盖详见 国际化指南。站点元数据Site Metadatatitle类型string默认值VitePress可通过 frontmatter 或目录级配置覆盖站点的标题。使用默认主题时它会显示在导航栏中。同时它也是所有页面标题的默认后缀除非定义了titleTemplate。页面最终标题由页面第一个h1的文本内容加上全局title后缀组成。例如export default { title: My Awesome Site }# Hello页面标题将是Hello | My Awesome Site。源码实现默认值在 resolveSiteData 中体现userConfig.title || VitePress标题拼接逻辑在 createTitle 中实现true/undefined模板默认拼| ${siteTitle}后缀。titleTemplate类型string | boolean可通过 frontmatter 或目录级配置覆盖用于自定义每个页面的标题后缀或整个标题。例如export default { title: My Awesome Site, titleTemplate: Custom Suffix }# Hello页面标题将是Hello | Custom Suffix。要完全自定义标题的渲染方式可以在titleTemplate中使用:title符号export default { titleTemplate: :title - Custom Suffix }:title会被替换为从页面第一个h1推断出的文本。上面的示例页面标题将是Hello - Custom Suffix。将该选项设为false可以禁用标题后缀。description类型string默认值A VitePress site可通过 frontmatter 或目录级配置覆盖站点的描述会渲染为页面 HTML 中的meta标签export default { description: A VitePress site }head类型HeadConfig[]默认值[]可通过 frontmatter 或目录级配置追加额外的head标签元素。用户添加的标签会渲染在 VitePress 自带标签之后、/head闭合标签之前。类型定义为见 types/shared.d.tstype HeadConfig | [string, Recordstring, string] | [string, Recordstring, string, string]即[标签名, 属性对象]或[标签名, 属性对象, 内联内容]的元组。合并与去重规则来自站点配置、locale 配置、目录级配置、frontmatter 和transformHead的 head 条目按此顺序合并。后出现的条目会替换而非追加同 key 的先前条目带有id属性的元素以id为 key没有id的meta元素以content之外的第一个属性如name、property、http-equiv及其值为 key。其他元素永不参与去重。如果想渲染多个会共享 key 的meta标签比如多个meta nameauthor请给每个标签一个唯一的id。去重逻辑的具体实现见 mergeHead 与 getHeadKeygetHeadKey正是按上述规则提取 keymergeHead通过Mapkey, index实现“同 key 替换、无 key 追加”。示例添加 faviconexport default { head: [[link, { rel: icon, href: /favicon.ico }]] } // put favicon.ico in public directory, if base is set, use /base/favicon.ico /* Would render: link relicon href/favicon.ico */示例添加 Google Fontsexport default { head: [ [ link, { rel: preconnect, href: https://fonts.googleapis.com } ], [ link, { rel: preconnect, href: https://fonts.gstatic.com, crossorigin: } ], [ link, { href: https://fonts.googleapis.com/css2?familyRobotodisplayswap, rel: stylesheet } ] ] } /* Would render: link relpreconnect hrefhttps://fonts.googleapis.com link relpreconnect hrefhttps://fonts.gstatic.com crossorigin link hrefhttps://fonts.googleapis.com/css2?familyRobotodisplayswap relstylesheet */示例注册 service workerexport default { head: [ [ script, { id: register-sw }, ;(() { if (serviceWorker in navigator) { navigator.serviceWorker.register(/sw.js) } })() ] ] } /* Would render: script idregister-sw ;(() { if (serviceWorker in navigator) { navigator.serviceWorker.register(/sw.js) } })() /script */示例接入 Google Analyticsexport default { head: [ [ script, { async: , src: https://www.googletagmanager.com/gtag/js?idTAG_ID } ], [ script, {}, window.dataLayer window.dataLayer || []; function gtag(){dataLayer.push(arguments);} gtag(js, new Date()); gtag(config, TAG_ID); ] ] } /* Would render: script async srchttps://www.googletagmanager.com/gtag/js?idTAG_ID/script script window.dataLayer window.dataLayer || []; function gtag(){dataLayer.push(arguments);} gtag(js, new Date()); gtag(config, TAG_ID); /script */lang类型string默认值en-US可在目录级配置覆盖站点的lang属性渲染为html langen-USexport default { lang: en-US }dir类型ltr | rtl | auto默认值ltr可在目录级配置覆盖也可通过 frontmatter 按页覆盖站点的文本方向渲染为html dirrtl。默认主题会为从右到左的语言镜像其布局。参见 RTL 支持。export default { dir: rtl }base类型string默认值/站点部署的基础 URL。如果你的站点部署在子路径下例如 GitHub Pages需要设置此项。若部署到https://foo.github.io/bar/则应设置base为/bar/。它应该始终以斜杠开头和结尾。唯一的例外是./它会产生可搬迁构建relative base页面以自身位置为基准引用所有资源因此同一份构建产物可以从任意子路径IPFS 网关、归档等直接使用无需重新构建也能在从文件系统直接打开时正常浏览。base会自动前置到其他选项中所有以/开头的 URL 上所以只需指定一次export default { base: /base/ }也可以通过命令行按构建指定vitepress build --base /base/。源码实现归一化逻辑在 normalizeSiteBase 中——自动补全结尾斜杠、非/开头时补前缀同时校验相对 base 必须是精确的./否则抛错。另外相对 base 与cleanUrls同时开启时构建会给出警告因为file://浏览与干净 URL 不兼容见 config.ts。路由RoutingcleanUrls类型boolean默认值false设为true时VitePress 会从 URL 中移除.html后缀。参见 生成干净 URL。⚠️ 需要服务器支持启用此功能可能需要宿主平台做额外配置服务器必须能在访问/foo时不经过重定向直接返回/foo.html的内容。rewrites类型Recordstring, string定义自定义的目录 ↔ URL 映射。参见 路由重写export default { rewrites: { source/:page: destination/:page } }从类型定义看siteConfig.tsrewrites也支持函数形式(id: string) string用于以编程方式计算目标路径。解析后SiteConfig会同时维护map源路径 → 重写路径与inv反向两张表siteConfig.ts。构建BuildsrcDir类型string默认值.存放 Markdown 页面的目录相对于项目根目录。参见 根目录与源目录export default { srcDir: ./src }srcExclude类型string[]默认值undefined用于匹配应从源内容中排除的 Markdown 文件的 glob 模式export default { srcExclude: [**/README.md, **/TODO.md] }outDir类型string默认值./.vitepress/dist站点构建输出位置相对于项目根目录export default { outDir: ../public }assetsDir类型string默认值assets指定生成的静态资源所嵌套的目录。该路径应在outDir内部并相对于它解析export default { assetsDir: static }源码校验resolveConfig会计算resolvedAssetsDir outDir/assetsDir若该路径不在outDir之内会直接抛错见 config.ts确保assetsDir不能指向outDir之外。assetsBase类型string默认值undefined生成的资源assetsDir下的所有内容所服务的 URL 前缀——典型场景是 CDN。必须是绝对 URL、协议相对 URL 或根绝对路径缺少结尾斜杠时会被自动补上。export default { base: /, assetsBase: https://cdn.example.com/ // scripts, styles, fonts and imported images resolve to // https://cdn.example.com/assets/* }发出的资源 URL 为assetsBase拼接输出相对路径因此 CDN 应镜像outDir的目录结构上传outDir/assets使其可通过assetsBase/assets/*访问。HTML 页面、Markdown 链接、public目录文件以及hashmap.json仍使用base。当assetsBase指向其他源时VitePress 会给发出的 script 与 preload 标签加上crossorigin属性——CDN 必须为你的站点源发送Access-Control-Allow-Origin响应头模块脚本始终以 CORS 模式请求。使用注意该选项只影响生产构建。vitepress preview对根绝对路径形式的assetsBase如/cdn/从本地 dist 提供外部 URL 则按真实地址请求。也可以通过命令行指定vitepress build --assetsBase https://cdn.example.com/。源码实现normalizeAssetsBaseconfig.ts会补全结尾斜杠并校验必须是绝对 URL、协议相对 URL 或根绝对路径否则抛错。归一化结果存入SiteConfig.assetsBase。assetsShards类型number默认值undefined将生成的资源分散到assetsDir下的这么多个子目录中assets/0/到assets/N-1/而不是一个扁平目录。适用于主机对每个目录的文件数量设限的场景——例如 Netlify 允许 54,000 个文件。每个页面会产出两个 JavaScript 文件因此一个 60,000 页的站点至少需要 3 个 shard并留出一定余量因为文件按名称哈希分布。export default { assetsShards: 4 }共享 chunk 保留在assets/chunks/中。一个文件属于哪个 shard 只取决于它的文件名因此未变化的文件在构建之间 URL 保持稳定。只影响生产构建。源码校验assetsShards必须是大于 1 的整数否则构建报错config.ts。客户端通过 hashmap 中带 shard 前缀的条目定位 chunk无需猜测目录布局见 pageChunkPath。icons类型{ include?: string[] }生成图标样式的选项。构建时会收集 SSR 期间渲染出的每一个 iconify 图标。名称以完全限定的collection:name形式书写并对照项目依赖中声明的iconify-json/*包解析。仅在客户端渲染的图标——例如在ClientOnly内部、或水合之后才渲染的图标——对 SSR 收集是不可见的。把它们列入include以强制加入样式表export default { icons: { include: [mdi:home, simple-icons:discord] } }cacheDir类型string默认值./.vitepress/cache缓存文件目录相对于项目根目录。参见 Vite 的 cacheDir 选项export default { cacheDir: ./.vitepress/.vite }ignoreDeadLinks类型boolean | localhostLinks | (string | RegExp | ((link: string, source: string) boolean))[]默认值false设为true时VitePress 不会因为死链而构建失败。设为localhostLinks时构建仍会因死链失败但不检查localhost链接。export default { ignoreDeadLinks: true }也可以是精确 URL 字符串、正则模式或自定义过滤函数的数组export default { ignoreDeadLinks: [ // ignore exact url /playground /playground, // ignore all localhost links /^https?:\/\/localhost/, // ignore all links include /repl/ /\/repl\//, // custom function, ignore all links include ignore (url) { return url.toLowerCase().includes(ignore) } ] }注意自定义过滤函数接收(link, source)两个参数source是链接所在页面的标识。mpa实验性类型boolean默认值false设为true时生产应用将以 MPA 模式 构建。MPA 模式默认提供 0kb JavaScript代价是禁用客户端导航交互能力需要显式选择启用。主题Themingappearance类型boolean | dark | force-dark | force-auto | import(vueuse/core).UseDarkOptions默认值true是否启用深色模式通过向html元素添加.dark类实现。设为true默认主题由用户偏好的色彩方案决定设为dark默认使用深色主题除非用户手动切换设为false用户无法切换主题设为force-dark始终深色用户无法切换设为force-auto始终跟随系统色彩偏好用户无法切换。该选项会注入一段内联脚本使用vitepress-theme-appearance这个 localStorage key 恢复用户设置。这确保.dark类在页面渲染之前就被应用避免闪烁。appearance.initialValue只能是dark | undefined不支持 ref 或 getter。源码实现APPEARANCE_KEY vitepress-theme-appearance定义在 src/shared/shared.ts。内联脚本由 resolveSiteDataHead 注入根据配置生成check-dark-mode脚本分别处理force-dark、force-auto与普通localStorage prefers-color-scheme三种分支同时在appearance未禁用时还会注入check-mac-os脚本用于平台类名。lastUpdated类型boolean默认值false是否使用 Git 获取每个页面的最后更新时间戳。该时间戳会包含在每个页面的 page data 中可通过useData访问。使用默认主题时启用该选项会在每个页面显示最后更新时间。可通过themeConfig.lastUpdated.text自定义显示文本。值得注意的是从 resolveConfig 的实现看lastUpdated默认值实际上是userConfig.lastUpdated ?? !!userConfig.themeConfig?.lastUpdated——即顶层未显式设置时会回退到themeConfig.lastUpdated的值。定制Customizationmarkdown 配置透传类型MarkdownOption配置 Markdown 解析器选项。VitePress 使用 Markdown-It 作为解析器并使用 Shiki 做语法高亮。在该选项中可传入各种 Markdown 相关选项export default { markdown: {...} }全部可用选项可查看类型声明与 JSDoc对应的实现文件为 src/node/markdown/markdown.ts。将markdown.headers设为true或传入mdit-vue/plugin-headers的选项可以收集标题到useData().page.headers。该选项默认禁用。vite 配置透传类型import(vite).UserConfig将原始 Vite Config 传给内部 Vite dev server / bundlerexport default { vite: { // Vite config options } }在mergeConfig中根层级的vite键会交给 Vite 的mergeConfig深度合并config.tsconfigFile还可以指向额外的 Vite 配置文件或设为false禁用加载。vue 配置透传类型import(vitejs/plugin-vue).Options将原始vitejs/plugin-vue选项传给内部插件实例export default { vue: { // vitejs/plugin-vue options } }构建钩子Build HooksVitePress 构建钩子允许你为网站添加新的功能与行为典型用途包括Sitemap 生成搜索索引PWATeleports传送门内容处理buildEnd类型(siteConfig: SiteConfig) AwaitablevoidbuildEnd是构建 CLI 钩子在构建SSG完成后、VitePress CLI 进程退出前运行export default { async buildEnd(siteConfig) { // ... } }典型用途如生成 RSS feed在UserConfig.buildEnd的 JSDoc 中明确举例见 siteConfig.ts。postRender类型(context: SSGContext) AwaitableSSGContext | voidpostRender是构建钩子在 SSG 渲染完成后调用。它允许你在 SSG 期间处理 teleports 内容export default { async postRender(context) { // ... } }interface SSGContext { content: string teleports?: Recordstring, string vpIcons: Setstring [key: string]: any }从类型定义看types/shared.d.tsSSGContext中的vpIcons是 SSR 期间通过useIcon注册的图标集合完全限定名为collection:name构建器据此只发出用到的图标样式。transformHead类型(context: TransformContext) AwaitableHeadConfig[]transformHead是为每个页面向head添加额外标签的构建钩子。它允许你添加无法静态写入 VitePress 配置的 head 条目。只需返回额外条目它们会被自动与现有条目合并。⚠️ 警告不要修改context内部的任何内容。export default { async transformHead(context) { // ... } }interface TransformContext { page: string // e.g. index.md (relative to srcDir) assets: string[] // all non-js/css assets as fully resolved public URL siteConfig: SiteConfig siteData: SiteData pageData: PageData title: string description: string head: HeadConfig[] content: string }该钩子只在构建时调用开发模式不会调用。额外标签会被加入构建生成的静态 HTML 文件客户端导航时不会更新。在很多情况下使用transformPageData钩子是更干净的选择——该钩子同时作用于客户端导航与开发模式。但如果生成 head 标签计算开销较大transformHead可以在开发阶段避免这一开销。示例添加og:imagemetaexport default { async transformHead(context) { if (context.page 404.md) { return } // The implementation details of generatePageImage would depend // on your requirements. Here we assume it generates a suitable // image for each page and returns the image URL. const imageUrl await generatePageImage(context) return [[ meta, { name: og:image, content: imageUrl } ]] } }这里假设图片 URL 是动态生成且耗时的使用transformHead可以在开发阶段避免该开销。对于更简单的场景可以使用 frontmatter 的head设置或transformPageData。transformHtml类型(code: string, id: string, context: TransformContext) Awaitablestring | voidtransformHtml是在每个页面内容写入磁盘之前对其进行转换的构建钩子⚠️ 警告不要修改context内部的任何内容。另外修改 HTML 内容可能在运行时引起水合问题。 注意此时图标样式表链接仍携带vp-icons.__VP_ICONS_HASH__.css占位符——内容哈希要等所有页面渲染完成才存在紧接着才会被替换。内联或对 head 资源做指纹化的钩子应跳过该标签。export default { async transformHtml(code, id, context) { // ... } }transformPageData类型(pageData: PageData, context: TransformPageContext) AwaitablePartialPageData | { [key: string]: any } | voidtransformPageData是转换每个页面pageData的钩子。你可以直接修改pageData或返回变更后的值会被合并进页面数据⚠️ 警告不要修改context内部的任何内容并注意这可能会影响 dev server 的性能尤其是钩子中有网络请求或重计算如生成图片时。可以通过process.env.NODE_ENV production做条件逻辑。export default { async transformPageData(pageData, { siteConfig }) { pageData.contributors await getPageContributors(pageData.relativePath) } // or return data to be merged async transformPageData(pageData, { siteConfig }) { return { contributors: await getPageContributors(pageData.relativePath) } } }interface TransformPageContext { siteConfig: SiteConfig }该钩子对 dev 与 build 都生效且返回值会合并进pageData两种写法等价。TransformPageContext只包含siteConfig一个字段见 siteConfig.ts。示例添加meta nameog:titleexport default { transformPageData(pageData) { const title pageData.frontmatter.layout home ? VitePress : ${pageData.title} | VitePress pageData.frontmatter.head ?? [] pageData.frontmatter.head.push([ meta, { name: og:title, content: title } ]) } }示例添加 canonical URLlinkexport default { transformPageData(pageData) { const canonicalUrl https://example.com/${pageData.relativePath} .replace(/index\.md$/, ) .replace(/\.md$/, .html) pageData.frontmatter.head ?? [] pageData.frontmatter.head.push([ link, { rel: canonical, href: canonicalUrl } ]) } }延伸阅读完整的配置类型定义与 JSDocUserConfig/SiteConfig/TransformContext见 src/node/siteConfig.tsHeadConfig/SSGContext/SiteData见 types/shared.d.ts配置加载、归一化与目录级配置收集的实现见 src/node/config.ts站点数据按路由解析与 head 合并逻辑见 src/shared/shared.ts页面级覆盖规则见 Frontmatter 配置参考多语言与 RTL 支持见 国际化指南路由与重写见 路由指南资源处理见 静态资源指南部署时的 base 与相对构建见 部署指南。【免费下载链接】vitepressVite Vue powered static site generator.项目地址: https://gitcode.com/gh_mirrors/vi/vitepress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考