VitePress Site Config 完全指南站點級配置項全解與源碼級原理剖析【免費下載鏈接】vitepressVite Vue powered static site generator.項目地址: https://gitcode.com/gh_mirrors/vi/vitepressSite Config 是 VitePress 站點全局配置的入口它定義了獨立于主題的通用設置——從站點標題、head標簽、多語言到構建產物路徑與 CDN 資源分發(fā)再到構建鉤子與頁面數據變換。本文以官方參考文檔為主體結合當前倉庫的 配置解析源碼 與 類型聲明逐項講解每個配置選項的類型、默認值、可覆蓋層級并給出可直接復制的實戰(zhàn)示例幫助你完全掌握 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]兩種形態(tài)都會被識別解析順序是先index目錄形態(tài)再頂層文件形態(tài)見 resolveUserConfig。配置解析發(fā)生在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因此以下兩種“動態(tài)配置”寫法都被支持可用于從 CMS、遠程接口等動態(tài)生成配置方式一默認導出 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 環(huán)境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 提供了三個“透傳”選項讓你無需創(chuàng)建獨立的 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。源碼實現細節(jié)目錄級配置的收集在 gatherAdditionalConfig 中完成——它通過 glob 模式**/config.{js,mjs,ts,mts}在srcDir下掃描所有config.*文件受srcExclude過濾逐個加載并按鍵目錄路徑聚合成additionalConfig字典。合并發(fā)生在resolveSiteDataByRoute見 shared.ts它會按“additionalConfig 棧 → locale 配置 → 根配置”的順序疊加目錄越深優(yōu)先級越高配置按目錄路徑排序深層目錄覆蓋淺層。該功能由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]即[標簽名, 屬性對象]或[標簽名, 屬性對象, 內聯內容]的元組。合并與去重規(guī)則來自站點配置、locale 配置、目錄級配置、frontmatter 和transformHead的 head 條目按此順序合并。后出現的條目會替換而非追加同 key 的先前條目帶有id屬性的元素以id為 key沒有id的meta元素以content之外的第一個屬性如name、property、http-equiv及其值為 key。其他元素永不參與去重。如果想渲染多個會共享 key 的meta標簽比如多個meta nameauthor請給每個標簽一個唯一的id。去重邏輯的具體實現見 mergeHead 與 getHeadKeygetHeadKey正是按上述規(guī)則提取 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指定生成的靜態(tài)資源所嵌套的目錄。該路徑應在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/* }發(fā)出的資源 URL 為assetsBase拼接輸出相對路徑因此 CDN 應鏡像outDir的目錄結構上傳outDir/assets使其可通過assetsBase/assets/*訪問。HTML 頁面、Markdown 鏈接、public目錄文件以及hashmap.json仍使用base。當assetsBase指向其他源時VitePress 會給發(fā)出的 script 與 preload 標簽加上crossorigin屬性——CDN 必須為你的站點源發(fā)送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 保持穩(wěn)定。只影響生產構建。源碼校驗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構建器據此只發(fā)出用到的圖標樣式。transformHead類型(context: TransformContext) AwaitableHeadConfig[]transformHead是為每個頁面向head添加額外標簽的構建鉤子。它允許你添加無法靜態(tài)寫入 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 }該鉤子只在構建時調用開發(fā)模式不會調用。額外標簽會被加入構建生成的靜態(tài) HTML 文件客戶端導航時不會更新。在很多情況下使用transformPageData鉤子是更干凈的選擇——該鉤子同時作用于客戶端導航與開發(fā)模式。但如果生成 head 標簽計算開銷較大transformHead可以在開發(fā)階段避免這一開銷。示例添加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 是動態(tài)生成且耗時的使用transformHead可以在開發(fā)階段避免該開銷。對于更簡單的場景可以使用 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頁面級覆蓋規(guī)則見 Frontmatter 配置參考多語言與 RTL 支持見 國際化指南路由與重寫見 路由指南資源處理見 靜態(tài)資源指南部署時的 base 與相對構建見 部署指南?！久赓M下載鏈接】vitepressVite Vue powered static site generator.項目地址: https://gitcode.com/gh_mirrors/vi/vitepress創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考 VitePress Site Config 完全指南：站點級配置項全解與源碼級原理剖析
VitePress Site Config 完全指南站點級配置項全解與源碼級原理剖析【免費下載鏈接】vitepressVite Vue powered static site generator.項目地址: https://gitcode.com/gh_mirrors/vi/vitepressSite Config 是 VitePress 站點全局配置的入口它定義了獨立于主題的通用設置——從站點標題、head標簽、多語言到構建產物路徑與 CDN 資源分發(fā)再到構建鉤子與頁面數據變換。本文以官方參考文檔為主體結合當前倉庫的 配置解析源碼 與 類型聲明逐項講解每個配置選項的類型、默認值、可覆蓋層級并給出可直接復制的實戰(zhàn)示例幫助你完全掌握 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]兩種形態(tài)都會被識別解析順序是先index目錄形態(tài)再頂層文件形態(tài)見 resolveUserConfig。配置解析發(fā)生在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因此以下兩種“動態(tài)配置”寫法都被支持可用于從 CMS、遠程接口等動態(tài)生成配置方式一默認導出 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 環(huán)境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 提供了三個“透傳”選項讓你無需創(chuàng)建獨立的 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。源碼實現細節(jié)目錄級配置的收集在 gatherAdditionalConfig 中完成——它通過 glob 模式**/config.{js,mjs,ts,mts}在srcDir下掃描所有config.*文件受srcExclude過濾逐個加載并按鍵目錄路徑聚合成additionalConfig字典。合并發(fā)生在resolveSiteDataByRoute見 shared.ts它會按“additionalConfig 棧 → locale 配置 → 根配置”的順序疊加目錄越深優(yōu)先級越高配置按目錄路徑排序深層目錄覆蓋淺層。該功能由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]即[標簽名, 屬性對象]或[標簽名, 屬性對象, 內聯內容]的元組。合并與去重規(guī)則來自站點配置、locale 配置、目錄級配置、frontmatter 和transformHead的 head 條目按此順序合并。后出現的條目會替換而非追加同 key 的先前條目帶有id屬性的元素以id為 key沒有id的meta元素以content之外的第一個屬性如name、property、http-equiv及其值為 key。其他元素永不參與去重。如果想渲染多個會共享 key 的meta標簽比如多個meta nameauthor請給每個標簽一個唯一的id。去重邏輯的具體實現見 mergeHead 與 getHeadKeygetHeadKey正是按上述規(guī)則提取 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指定生成的靜態(tài)資源所嵌套的目錄。該路徑應在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/* }發(fā)出的資源 URL 為assetsBase拼接輸出相對路徑因此 CDN 應鏡像outDir的目錄結構上傳outDir/assets使其可通過assetsBase/assets/*訪問。HTML 頁面、Markdown 鏈接、public目錄文件以及hashmap.json仍使用base。當assetsBase指向其他源時VitePress 會給發(fā)出的 script 與 preload 標簽加上crossorigin屬性——CDN 必須為你的站點源發(fā)送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 保持穩(wěn)定。只影響生產構建。源碼校驗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構建器據此只發(fā)出用到的圖標樣式。transformHead類型(context: TransformContext) AwaitableHeadConfig[]transformHead是為每個頁面向head添加額外標簽的構建鉤子。它允許你添加無法靜態(tài)寫入 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 }該鉤子只在構建時調用開發(fā)模式不會調用。額外標簽會被加入構建生成的靜態(tài) HTML 文件客戶端導航時不會更新。在很多情況下使用transformPageData鉤子是更干凈的選擇——該鉤子同時作用于客戶端導航與開發(fā)模式。但如果生成 head 標簽計算開銷較大transformHead可以在開發(fā)階段避免這一開銷。示例添加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 是動態(tài)生成且耗時的使用transformHead可以在開發(fā)階段避免該開銷。對于更簡單的場景可以使用 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頁面級覆蓋規(guī)則見 Frontmatter 配置參考多語言與 RTL 支持見 國際化指南路由與重寫見 路由指南資源處理見 靜態(tài)資源指南部署時的 base 與相對構建見 部署指南?！久赓M下載鏈接】vitepressVite Vue powered static site generator.項目地址: https://gitcode.com/gh_mirrors/vi/vitepress創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考