VitePress 站点配置完全指南：site-config 全量选项解析与源码级原理

前端文档【免费下载链接】vitepressVite Vue powered static site generator.项目地址https://gitcode.com/gh_mirrors/vi/vitepress点击查看免费下载本指南以 VitePress 官方文档《サイト設定》为骨架系统梳理应用级App-Level站点配置的全部选项——从配置文件解析、站点元数据、路由与构建选项到主题外观、Markdown/Vite/Vue 集成与五大构建钩子Build Hooks。读完本文你将能够独立完成.vitepress/config.ts的编写、排查构建问题并借助源码理解每个配置项背后的真实行为将其用于多语言、子路径部署、SEO 与 PWA 等实战场景。概述配置文件的解析与加载配置文件解析Config Resolution配置文件固定从root/.vitepress/config.[ext]解析其中root为项目根目录即包含.vitepress的目录[ext]支持.js、.ts、.mjs、.mts四种扩展名TypeScript 开箱即用。这一点与源码src/node/config.ts中的supportedConfigExtensions [js, ts, mjs, mts]完全一致且解析顺序会同时尝试config/index.[ext]与config.[ext]两种形态。配置文件推荐使用 ES Modules 语法并以默认导出default export的形式输出配置对象export default { // 应用级设置 lang: en-US, title: VitePress, description: Vite Vue powered static site generator., ... }resolveConfig见 src/node/config.ts会完成以下解析流程归一化 root 为绝对路径 → 加载用户配置 → 解析站点数据resolveSiteData→ 解析srcDir/assetsDir/outDir/cacheDir等路径 → 决定主题目录存在.vitepress/theme时使用用户主题否则回退到默认主题DEFAULT_THEME_PATH→ 解析页面列表。解析后的SiteConfig会挂载到全局global.VITEPRESS_CONFIG供 content loader 等模块共享。动态异步配置当配置需要动态生成时可以默认导出一个异步函数import { defineConfig } from vitepress export default async () { const posts await (await fetch(https://my-cms.com/blog-posts)).json() return defineConfig({ // 应用级设置 lang: en-US, title: VitePress, description: Vite Vue powered static site generator., // 主题级设置 themeConfig: { sidebar: [ ...posts.map((post) ({ text: post.name, link: /posts/${post.name} })) ] } }) }也可以直接使用顶层awaitTop-Level Awaitimport { defineConfig } from vitepress const posts await (await fetch(https://my-cms.com/blog-posts)).json() export default defineConfig({ // 应用级设置 lang: en-US, title: VitePress, description: Vite Vue powered static site generator., // 主题级设置 themeConfig: { sidebar: [ ...posts.map((post) ({ text: post.name, link: /posts/${post.name} })) ] } })从源码看resolveUserConfig会通过resolveConfigExtends对函数型配置进行求值typeof config function ? config() : config且支持extends字段递归合并基础配置详见 src/node/config.ts。配置的智能提示Config Intellisense使用defineConfig辅助函数可以获得 TypeScript 类型补全在支持的语言服务中JavaScript 与 TypeScript 文件都能获得提示import { defineConfig } from vitepress export default defineConfig({ // ... })其实现位于 src/node/config.tsdefineConfigThemeConfig DefaultTheme.Config(config)本质上只是返回传入的配置对象借助泛型默认值将类型约束到默认主题的配置结构。带类型的主题配置Typed Theme Config默认情况下defineConfig假定主题配置的类型为DefaultTheme.Configimport { defineConfig } from vitepress export default defineConfig({ themeConfig: { // 类型为 DefaultTheme.Config } })使用自定义主题并希望对其themeConfig做类型检查时改用defineConfigWithTheme并通过泛型传入自定义主题的配置类型import { defineConfigWithTheme } from vitepress import type { ThemeConfig } from your-theme export default defineConfigWithThemeThemeConfig({ themeConfig: { // 类型为 ThemeConfig } })注意源码中defineConfigWithTheme已被标注为deprecated use defineConfig insteadsrc/node/config.ts但从当前文档与类型层面它依然可用推荐新代码直接使用defineConfigThemeConfig({ ... })的泛型写法。Vite・Vue・Markdown 的配置入口Vite无需单独的 Vite 配置文件直接在 VitePress 配置的 vite 选项中提供 Vite 配置。类型为import(vite).UserConfig。VueVitePress 内置了官方 Vue 插件vitejs/plugin-vue其选项通过 vue 传入。类型为import(vitejs/plugin-vue).Options。Markdown默认的 Markdown-It 实例可通过 markdown 选项自定义选项类型为MarkdownOption源码定义见 src/node/markdown/markdown.ts。站点元数据Site Metadatatitle类型string默认值VitePress页面级覆盖frontmatter 的 title站点的标题。默认主题会将其显示在导航栏中。若未定义titleTemplate它还会作为每个页面标题的默认后缀。各页面最终标题 该页首个h1标题文本 全局title后缀。例如export default { title: My Awesome Site }# Hello该页面的标题即为Hello | My Awesome Site。源码中默认值由 src/node/config.ts 的userConfig.title || VitePress提供。titleTemplate类型string | boolean页面级覆盖frontmatter 的 titleTemplate用于定制每个页面标题的后缀或整体标题。例如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 的 description站点的描述会以meta标签输出到页面 HTML 中export default { description: A VitePress site }对应源码默认值见 src/node/config.tsuserConfig.description || A VitePress site。head类型HeadConfig[]默认值[]页面级追加frontmatter 的 head向页面 HTML 的head中额外输出的元素。用户添加的标签会渲染在 VitePress 自带标签之后、/head之前。其类型定义为type HeadConfig | [string, Recordstring, string] | [string, Recordstring, string, string]即三元组形式[标签名, 属性对象, 可选的内联内容]实际类型声明见 types/shared.d.ts。需要注意resolveSiteDataHeadsrc/node/config.ts会自动在 head 中注入check-dark-mode与check-mac-os两个内联脚本MPA 模式下仅注入后者因此实际输出的head会比用户配置的多出这些由框架管理的元素。示例添加 faviconexport default { head: [[link, { rel: icon, href: /favicon.ico }]] } // favicon.ico 需放在 public 目录若设置了 base则使用 /base/favicon.ico /* 输出结果: 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 } ] ] } /* 输出结果: 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) } })() ] ] } /* 输出结果: 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); ] ] } /* 输出结果: 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站点的语言属性会输出为页面 HTML 的html langen-USexport default { lang: en-US }base类型string默认值/站点部署的基础 URL。当部署在子路径下如 GitHub Pages 的https://foo.github.io/bar/时需要将base设为/bar/且必须以/开头和结尾。base会自动添加到其他选项中以/开头的 URL 之前因此只需设置一次export default { base: /base/ }源码中的normalizeSiteBasesrc/node/config.ts会做归一化处理自动补末尾斜杠若 base 以.开头但并非精确的./相对形式isRelativeBase则直接抛错不是相对 base 且不是外部 URL、又不以/开头时自动补前导斜杠。因此除了/bar/这类绝对子路径还可以使用./相对 base 让产物可移动到任意子路径下部署。路由RoutingcleanUrls类型boolean默认值false设为true后URL 末尾的.html会被移除同时参见生成干净 URL一节。::: warning 需要服务器配置 某些托管环境需要额外配置访问/foo时能不经过重定向直接返回/foo.html。 :::源码层面cleanUrls的默认解析见 src/node/config.tscleanUrls: !!userConfig.cleanUrls。另外当base为相对路径且cleanUrls开启时构建阶段会输出警告cleanUrls with a relative base needs server-side rewrites and breaks file:// browsing见 src/node/config.ts提示相对 base 与 cleanUrls 组合需要服务端重写支持。rewrites类型Recordstring, string定义目录与 URL 之间的自定义映射详见路由路由重写export default { rewrites: { source/:page: destination/:page } }从类型定义看rewrites还支持函数形式((id: string) string)见 src/node/siteConfig.ts解析后会生成正反向两张映射表map/inv挂在SiteConfig.rewrites上。构建BuildsrcDir类型string默认值.存放 Markdown 页面源码的目录相对于项目根目录参见根目录与源码目录export default { srcDir: ./src }srcExclude类型string[]默认值undefined匹配要从源码中排除的 Markdown 文件的 glob 模式语法参考 fast-globexport default { srcExclude: [**/README.md, **/TODO.md] }outDir类型string默认值./.vitepress/dist构建输出目录相对于项目根目录export default { outDir: ../public }assetsDir类型string默认值assets生成资源构建产物存放的子目录名路径相对于outDir内部解析export default { assetsDir: static }源码 src/node/config.ts 会校验assetsDir解析后必须位于outDir之内否则抛出assetsDir cannot be set to a location outside of the outDir错误。cacheDir类型string默认值./.vitepress/cache缓存文件目录相对于项目根目录参考 Vite 的 cacheDirexport default { cacheDir: ./.vitepress/.vite }ignoreDeadLinks类型boolean | localhostLinks | (string | RegExp | ((link: string, source: string) boolean))[]默认值false设为true时存在死链也不会导致构建失败。设为localhostLinks时仅跳过对localhost链接的检查其他死链仍会使构建失败export default { ignoreDeadLinks: true }也可以指定为精确 URL 字符串、正则表达式、自定义过滤函数组成的数组export default { ignoreDeadLinks: [ // 精确忽略 /playground /playground, // 忽略所有 localhost 链接 /^https?:\/\/localhost/, // 忽略路径中包含 /repl/ 的链接 /\/repl\//, // 自定义函数: 忽略包含 ignore 的链接 (url) { return url.toLowerCase().includes(ignore) } ] }类型定义中该过滤函数签名为(link: string, source: string) boolean见 src/node/siteConfig.ts即第二个参数还能拿到链接所在源文件的信息便于做更精细的判定。mpa类型boolean默认值false设为true时生产构建将以 MPA 模式进行。MPA 模式默认以 0kb 客户端 JavaScript 交付页面代价是禁用客户端导航需要交互的页面必须显式选择接入opt-in。其类型定义标注为experimental默认解析见 src/node/config.tsmpa: !!userConfig.mpa。主题相关Themingappearance类型boolean | dark | force-dark | force-auto | import(vueuse/core).UseDarkOptions默认值true是否启用深色模式在html上添加.dark类true跟随用户的环境偏好。dark默认使用深色用户仍可切换。false用户无法切换主题。force-dark始终固定深色不可切换。force-auto始终跟随系统偏好不可切换。该选项会插入一个内联脚本从本地存储vitepress-theme-appearance常量APPEARANCE_KEY定义于 src/shared/shared.ts恢复外观设置从而在页面渲染前应用.dark类以防止闪烁FOUC。appearance.initialValue仅支持dark | undefined不能使用 Ref 或 getter。源码实现值得展开resolveSiteDataHeadsrc/node/config.ts在appearance非空时自动注入idcheck-dark-mode的内联脚本脚本内容根据 appearance 模式分为三种——force-dark直接加类force-auto通过matchMedia((prefers-color-scheme: dark))判定普通模式则优先读localStorage的vitepress-theme-appearance再回退到initialValue ?? auto。另外注意 MPA 模式下userConfig?.mpa为真该脚本不会被注入。lastUpdated类型boolean默认值false使用 Git 获取每个页面的最后更新时间戳。时间戳会包含在每页数据中可通过useData引用。使用默认主题时开启该选项会在页面底部显示最后更新时间文案可通过themeConfig.lastUpdated.text定制。源码中lastUpdated的解析为userConfig.lastUpdated ?? !!userConfig.themeConfig?.lastUpdatedsrc/node/config.ts即只要任一处开启即生效其底层时间戳获取逻辑位于 src/node/utils/getGitTimestamp.ts。自定义Customizationmarkdown类型MarkdownOptionMarkdown 解析器的配置。VitePress 使用 Markdown-it 作为解析器、Shiki 做语法高亮可按需指定各类 Markdown 相关选项export default { markdown: {...} }可用的选项可查看类型定义与 JSDoc。这里结合源码给出高频选项速查preConfig/config在应用内置插件之前/之后配置 markdown-it 实例的回调theme语法高亮主题支持{ light: github-light, dark: github-dark }双主题对象默认即为此双主题src/node/markdown/markdown.tslineNumbers代码块行号依赖preWrapper默认falsesnippet/include代码片段导入与!-- include: path --Markdown 包含emoji、tasklist、footnote、attrs、anchor、toc、math、container、gfmAlerts、image、component、frontmatter、sfc等开关externalLinks外部链接属性默认{ target: _blank, rel: noreferrer }src/node/markdown/markdown.ts。vite类型import(vite).UserConfig向内部的 Vite 开发服务器打包器传入原始的 Vite Configexport default { vite: { // Vite 配置 } }vue类型import(vitejs/plugin-vue).Options将选项原样传给内部的vitejs/plugin-vue实例export default { vue: { // vitejs/plugin-vue 选项 } }构建钩子Build HooksVitePress 的构建钩子可用于为站点添加功能或行为官方文档列出的典型用途包括站点地图Sitemap搜索索引Search indexPWATeleportSSG 期间传送内容的处理buildEnd类型(siteConfig: SiteConfig) AwaitablevoidbuildEnd是构建 CLI 钩子在构建SSG完成之后、VitePress CLI 进程退出之前执行export default { async buildEnd(siteConfig) { // ... } }适合在此生成 RSS feed 等一次性收尾任务类型注释见 src/node/siteConfig.ts。postRender类型(context: SSGContext) AwaitableSSGContext | voidpostRender是 SSG 渲染完成时调用的构建钩子可用于处理 SSG 期间的 teleport 内容export default { async postRender(context) { // ... } }interface SSGContext { content: string teleports?: Recordstring, string [key: string]: any }类型声明见 types/shared.d.ts其中还包含框架内部使用的vpIcons: SetstringSSR 期间通过useIcon注册的图标集合。transformHead类型(context: TransformContext) AwaitableHeadConfig[]transformHead是在生成每个页面之前转换 head 的构建钩子可添加无法在配置文件中静态声明的 head 元素。只需返回新增的部分框架会自动与既有 head 合并。::: warning 不要修改context内的值。 :::export default { async transformHead(context) { // ... } }interface TransformContext { page: string // 例如: index.md相对于 srcDir assets: string[] // 已解析的公开 URL非 js/css 资源 siteConfig: SiteConfig siteData: SiteData pageData: PageData title: string description: string head: HeadConfig[] content: string }该钩子只在静态站点生成build阶段调用开发模式下不会执行。若需在开发模式下动态添加 head 元素改用transformPageDataexport default { transformPageData(pageData) { pageData.frontmatter.head ?? [] pageData.frontmatter.head.push([ meta, { name: og:title, content: pageData.frontmatter.layout home ? VitePress : ${pageData.title} | VitePress } ]) } }示例添加规范 URL 的linkexport 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 } ]) } }transformHtml类型(code: string, id: string, context: TransformContext) Awaitablestring | voidtransformHtml是在每个页面的内容写入磁盘之前进行转换的构建钩子。::: warning 不要修改context内的值。此外修改 HTML 可能引发运行时水合hydration问题。 :::export default { async transformHtml(code, id, context) { // ... } }transformPageData类型(pageData: PageData, context: TransformPageContext) AwaitablePartialPageData | { [key: string]: any } | voidtransformPageData是转换每个页面pageData的钩子既可以就地修改pageData也可以返回变更值让其合并::: warning 不要修改context内的值。若在其中执行网络请求或重计算如图像生成会影响开发服务器的性能可考虑用process.env.NODE_ENV production做条件分支。 :::export default { async transformPageData(pageData, { siteConfig }) { pageData.contributors await getPageContributors(pageData.relativePath) } // 或者返回待合并的值 async transformPageData(pageData, { siteConfig }) { return { contributors: await getPageContributors(pageData.relativePath) } } }interface TransformPageContext { siteConfig: SiteConfig }从源码注释看src/node/siteConfig.ts该钩子在开发与构建两种模式下渲染 Markdown 到 Vue 时都会被调用返回的变更值会合并进页面数据——这正是它在开发模式下也能生效的原因。结语从配置到行为的关键路径回顾全文VitePress 的站点配置并非一份写了就完事的清单而是一条可追踪的代码路径defineConfig提供类型约束 →resolveUserConfig/resolveConfig完成文件加载、路径归一化与默认值填充 →resolveSiteData产出运行时站点数据 →createMarkdownRenderer按markdown选项装配解析器与插件 → 构建钩子buildEnd/postRender/transformHead/transformHtml/transformPageData在 SSG 流水线的各个节点介入。掌握这条链路之后无论是排查 base 路径问题、定制 head、注入动态元数据还是接入 PWA 与站点地图都能在 src/node/config.ts、src/node/siteConfig.ts 与 src/node/markdown/markdown.ts 中找到对应的实现依据从而让配置从照抄示例升级为可解释、可扩展。赞分享前端文档【免费下载链接】vitepressVite Vue powered static site generator.项目地址https://gitcode.com/gh_mirrors/vi/vitepress点击查看免费下载相关推荐Video2X 6.0.0终极指南如何利用C/C重构实现视频无损放大300%加速Video2X 6.0.0终极指南如何利用C/C重构实现视频无损放大300%加速 你是否曾为低分辨率视频的模糊画面而烦恼或者想将老旧的视频素材提升到4K前端文档Zola 站点配置完全指南zola.toml 全量参数详解与源码级原理Zola 站点配置完全指南zola.toml 全量参数详解与源码级原理 Zola 是一个把SSG静态站点生成器压缩进单个二进制的快速建站工具其哲学是静态站点CLI开发工具wagmi 中 createConfig 完全指南配置项详解、Config 状态模型与源码级原理wagmi 中 createConfig 完全指南配置项详解、Config 状态模型与源码级原理 createConfig 是 wagmi 的核心入口函数用区块链Web3前端上一篇RealSense SDK Windows 配置从插上相机到跑通深度图的 4 个关键动作下一篇ntfy内存管理Go语言垃圾回收与内存泄漏预防创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考