VitePress Site Config 完全指南站點(diǎn)級配置項(xiàng)全解與源碼級原理剖析【免費(fèi)下載鏈接】vitepressVite Vue powered static site generator.項(xiàng)目地址: https://gitcode.com/gh_mirrors/vi/vitepressSite Config 是 VitePress 站點(diǎn)全局配置的入口它定義了獨(dú)立于主題的通用設(shè)置——從站點(diǎn)標(biāo)題、head標(biāo)簽、多語言到構(gòu)建產(chǎn)物路徑與 CDN 資源分發(fā)再到構(gòu)建鉤子與頁面數(shù)據(jù)變換。本文以官方參考文檔為主體結(jié)合當(dāng)前倉庫的 配置解析源碼 與 類型聲明逐項(xiàng)講解每個配置選項(xiàng)的類型、默認(rèn)值、可覆蓋層級并給出可直接復(fù)制的實(shí)戰(zhàn)示例幫助你完全掌握 VitePress 的站點(diǎn)級配置體系。配置解析機(jī)制配置文件從哪來VitePress 的配置文件始終從root/.vitepress/config.[ext]解析其中root是你的 VitePress 項(xiàng)目根目錄[ext]是受支持的擴(kuò)展名之一。在 src/node/config.ts 中可以看到受支持的配置文件擴(kuò)展名被硬編碼為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等路徑解析站點(diǎn)數(shù)據(jù)并最終構(gòu)建出完整的SiteConfig對象包含pages、rewrites、dynamicRoutes等派生信息同時把配置掛到全局VITEPRESS_CONFIG上供內(nèi)容加載器共享。推薦使用 ES Modules 語法配置文件的入口應(yīng)該默認(rèn)導(dǎo)出一個對象export default { // app level config options lang: en-US, title: VitePress, description: Vite Vue powered static site generator., ... }從源碼看resolveConfigExtends會先判斷配置是否為函數(shù)并調(diào)用它typeof config function ? config() : config因此以下兩種“動態(tài)配置”寫法都被支持可用于從 CMS、遠(yuǎn)程接口等動態(tài)生成配置方式一默認(rèn)導(dǎo)出 async 函數(shù)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選項(xiàng)見 siteConfig.ts用于繼承一份基礎(chǔ)配置其值會被遞歸合并并被當(dāng)前配置覆蓋。resolveConfigExtends會遞歸解析extends鏈并調(diào)用mergeConfig完成合并——數(shù)組會拼接對象會遞歸合并其中vite與markdown走專門的合并邏輯。這非常適合多個站點(diǎn)共享一份公共主題基座配置的場景。配置智能提示與類型化主題配置Config IntellisensedefineConfig使用defineConfig輔助函數(shù)即可獲得基于 TypeScript 的配置項(xiàng)智能提示。在 JavaScript 與 TypeScript 中均可用前提是 IDE 支持import { defineConfig } from vitepress export default defineConfig({ // ... })源碼層面的實(shí)現(xiàn)非常簡單config.tsexport function defineConfigThemeConfig DefaultTheme.Config( config: UserConfigNoInferThemeConfig ) { return config }它本身不改變運(yùn)行時行為純粹提供類型約束與提示。Typed Theme ConfigdefineConfigWithTheme默認(rèn)情況下defineConfig期望的themeConfig類型來自默認(rèn)主題DefaultTheme.Configimport { defineConfig } from vitepress export default defineConfig({ themeConfig: { // Type is DefaultTheme.Config } })如果你使用自定義主題并希望themeConfig獲得類型檢查需要使用defineConfigWithTheme并通過泛型參數(shù)傳入自定義主題的配置類型import { defineConfigWithTheme } from vitepress import type { ThemeConfig } from your-theme export default defineConfigWithThemeThemeConfig({ themeConfig: { // Type is ThemeConfig } })從源碼注釋可以看到該函數(shù)已被標(biāo)記為deprecatedconfig.ts官方推薦改用泛型化的defineConfig但該 API 仍被保留以兼容自定義主題場景。Vite、Vue 與 Markdown 的配置入口Site Config 提供了三個“透傳”選項(xiàng)讓你無需創(chuàng)建獨(dú)立的 Vite 配置文件Vite使用配置中的vite選項(xiàng)配置底層 Vite 實(shí)例無需單獨(dú)的 Vite 配置文件VueVitePress 已內(nèi)置官方 Vue 插件vitejs/plugin-vue可通過vue選項(xiàng)配置其參數(shù)Markdown可通過markdown選項(xiàng)配置底層的 Markdown-It 解析器實(shí)例。頁面級與目錄級覆蓋頁面級覆蓋Frontmatter部分設(shè)置可以通過頁面 frontmatter 覆蓋詳見 Frontmatter 配置。目錄級覆蓋additionalConfig部分配置可以在目錄層級覆蓋使該目錄下所有頁面共享設(shè)置而無需在每個頁面的 frontmatter 中重復(fù)聲明。實(shí)現(xiàn)方式是在相關(guān)目錄中添加一個名為config.ts或.js、.mjs、.mts的文件用export default導(dǎo)出配置對象與主配置文件類似。嵌套目錄會繼承父目錄的設(shè)置覆蓋項(xiàng)會被合并。defineAdditionalConfig輔助函數(shù)可為可用選項(xiàng)提供 TypeScript 智能提示與defineConfig一樣使用是可選的。例如對于一個多語言站點(diǎn)我們希望每種語言有各自的description可以在es/config.ts中寫入import { defineAdditionalConfig } from vitepress export default defineAdditionalConfig({ description: Generador de Sitios Estáticos desarrollado con Vite y Vue. })這樣es目錄下所有頁面都會使用該description。源碼實(shí)現(xiàn)細(xì)節(jié)目錄級配置的收集在 gatherAdditionalConfig 中完成——它通過 glob 模式**/config.{js,mjs,ts,mts}在srcDir下掃描所有config.*文件受srcExclude過濾逐個加載并按鍵目錄路徑聚合成additionalConfig字典。合并發(fā)生在resolveSiteDataByRoute見 shared.ts它會按“additionalConfig 棧 → locale 配置 → 根配置”的順序疊加目錄越深優(yōu)先級越高配置按目錄路徑排序深層目錄覆蓋淺層。該功能由UserConfig.additionalConfig選項(xiàng)控制可顯式設(shè)置為{}來關(guān)閉自動收集。另外使用內(nèi)置 i18n 功能時語言目錄的設(shè)置也可以通過主配置文件中的locales設(shè)置覆蓋詳見 國際化指南。站點(diǎn)元數(shù)據(jù)Site Metadatatitle類型string默認(rèn)值VitePress可通過 frontmatter 或目錄級配置覆蓋站點(diǎn)的標(biāo)題。使用默認(rèn)主題時它會顯示在導(dǎo)航欄中。同時它也是所有頁面標(biāo)題的默認(rèn)后綴除非定義了titleTemplate。頁面最終標(biāo)題由頁面第一個h1的文本內(nèi)容加上全局title后綴組成。例如export default { title: My Awesome Site }# Hello頁面標(biāo)題將是Hello | My Awesome Site。源碼實(shí)現(xiàn)默認(rèn)值在 resolveSiteData 中體現(xiàn)userConfig.title || VitePress標(biāo)題拼接邏輯在 createTitle 中實(shí)現(xiàn)true/undefined模板默認(rèn)拼| ${siteTitle}后綴。titleTemplate類型string | boolean可通過 frontmatter 或目錄級配置覆蓋用于自定義每個頁面的標(biāo)題后綴或整個標(biāo)題。例如export default { title: My Awesome Site, titleTemplate: Custom Suffix }# Hello頁面標(biāo)題將是Hello | Custom Suffix。要完全自定義標(biāo)題的渲染方式可以在titleTemplate中使用:title符號export default { titleTemplate: :title - Custom Suffix }:title會被替換為從頁面第一個h1推斷出的文本。上面的示例頁面標(biāo)題將是Hello - Custom Suffix。將該選項(xiàng)設(shè)為false可以禁用標(biāo)題后綴。description類型string默認(rèn)值A(chǔ) VitePress site可通過 frontmatter 或目錄級配置覆蓋站點(diǎn)的描述會渲染為頁面 HTML 中的meta標(biāo)簽export default { description: A VitePress site }head類型HeadConfig[]默認(rèn)值[]可通過 frontmatter 或目錄級配置追加額外的head標(biāo)簽元素。用戶添加的標(biāo)簽會渲染在 VitePress 自帶標(biāo)簽之后、/head閉合標(biāo)簽之前。類型定義為見 types/shared.d.tstype HeadConfig | [string, Recordstring, string] | [string, Recordstring, string, string]即[標(biāo)簽名, 屬性對象]或[標(biāo)簽名, 屬性對象, 內(nèi)聯(lián)內(nèi)容]的元組。合并與去重規(guī)則來自站點(diǎn)配置、locale 配置、目錄級配置、frontmatter 和transformHead的 head 條目按此順序合并。后出現(xiàn)的條目會替換而非追加同 key 的先前條目帶有id屬性的元素以id為 key沒有id的meta元素以content之外的第一個屬性如name、property、http-equiv及其值為 key。其他元素永不參與去重。如果想渲染多個會共享 key 的meta標(biāo)簽比如多個meta nameauthor請給每個標(biāo)簽一個唯一的id。去重邏輯的具體實(shí)現(xiàn)見 mergeHead 與 getHeadKeygetHeadKey正是按上述規(guī)則提取 keymergeHead通過Mapkey, index實(shí)現(xiàn)“同 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默認(rèn)值en-US可在目錄級配置覆蓋站點(diǎn)的lang屬性渲染為html langen-USexport default { lang: en-US }dir類型ltr | rtl | auto默認(rèn)值ltr可在目錄級配置覆蓋也可通過 frontmatter 按頁覆蓋站點(diǎn)的文本方向渲染為html dirrtl。默認(rèn)主題會為從右到左的語言鏡像其布局。參見 RTL 支持。export default { dir: rtl }base類型string默認(rèn)值/站點(diǎn)部署的基礎(chǔ) URL。如果你的站點(diǎn)部署在子路徑下例如 GitHub Pages需要設(shè)置此項(xiàng)。若部署到https://foo.github.io/bar/則應(yīng)設(shè)置base為/bar/。它應(yīng)該始終以斜杠開頭和結(jié)尾。唯一的例外是./它會產(chǎn)生可搬遷構(gòu)建relative base頁面以自身位置為基準(zhǔn)引用所有資源因此同一份構(gòu)建產(chǎn)物可以從任意子路徑IPFS 網(wǎng)關(guān)、歸檔等直接使用無需重新構(gòu)建也能在從文件系統(tǒng)直接打開時正常瀏覽。base會自動前置到其他選項(xiàng)中所有以/開頭的 URL 上所以只需指定一次export default { base: /base/ }也可以通過命令行按構(gòu)建指定vitepress build --base /base/。源碼實(shí)現(xiàn)歸一化邏輯在 normalizeSiteBase 中——自動補(bǔ)全結(jié)尾斜杠、非/開頭時補(bǔ)前綴同時校驗(yàn)相對 base 必須是精確的./否則拋錯。另外相對 base 與cleanUrls同時開啟時構(gòu)建會給出警告因?yàn)閒ile://瀏覽與干凈 URL 不兼容見 config.ts。路由RoutingcleanUrls類型boolean默認(rèn)值false設(shè)為true時VitePress 會從 URL 中移除.html后綴。參見 生成干凈 URL。?? 需要服務(wù)器支持啟用此功能可能需要宿主平臺做額外配置服務(wù)器必須能在訪問/foo時不經(jīng)過重定向直接返回/foo.html的內(nèi)容。rewrites類型Recordstring, string定義自定義的目錄 ? URL 映射。參見 路由重寫export default { rewrites: { source/:page: destination/:page } }從類型定義看siteConfig.tsrewrites也支持函數(shù)形式(id: string) string用于以編程方式計(jì)算目標(biāo)路徑。解析后SiteConfig會同時維護(hù)map源路徑 → 重寫路徑與inv反向兩張表siteConfig.ts。構(gòu)建BuildsrcDir類型string默認(rèn)值.存放 Markdown 頁面的目錄相對于項(xiàng)目根目錄。參見 根目錄與源目錄export default { srcDir: ./src }srcExclude類型string[]默認(rèn)值undefined用于匹配應(yīng)從源內(nèi)容中排除的 Markdown 文件的 glob 模式export default { srcExclude: [**/README.md, **/TODO.md] }outDir類型string默認(rèn)值./.vitepress/dist站點(diǎn)構(gòu)建輸出位置相對于項(xiàng)目根目錄export default { outDir: ../public }assetsDir類型string默認(rèn)值assets指定生成的靜態(tài)資源所嵌套的目錄。該路徑應(yīng)在outDir內(nèi)部并相對于它解析export default { assetsDir: static }源碼校驗(yàn)resolveConfig會計(jì)算resolvedAssetsDir outDir/assetsDir若該路徑不在outDir之內(nèi)會直接拋錯見 config.ts確保assetsDir不能指向outDir之外。assetsBase類型string默認(rèn)值undefined生成的資源assetsDir下的所有內(nèi)容所服務(wù)的 URL 前綴——典型場景是 CDN。必須是絕對 URL、協(xié)議相對 URL 或根絕對路徑缺少結(jié)尾斜杠時會被自動補(bǔ)上。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 應(yīng)鏡像outDir的目錄結(jié)構(gòu)上傳outDir/assets使其可通過assetsBase/assets/*訪問。HTML 頁面、Markdown 鏈接、public目錄文件以及hashmap.json仍使用base。當(dāng)assetsBase指向其他源時VitePress 會給發(fā)出的 script 與 preload 標(biāo)簽加上crossorigin屬性——CDN 必須為你的站點(diǎn)源發(fā)送Access-Control-Allow-Origin響應(yīng)頭模塊腳本始終以 CORS 模式請求。使用注意該選項(xiàng)只影響生產(chǎn)構(gòu)建。vitepress preview對根絕對路徑形式的assetsBase如/cdn/從本地 dist 提供外部 URL 則按真實(shí)地址請求。也可以通過命令行指定vitepress build --assetsBase https://cdn.example.com/。源碼實(shí)現(xiàn)normalizeAssetsBaseconfig.ts會補(bǔ)全結(jié)尾斜杠并校驗(yàn)必須是絕對 URL、協(xié)議相對 URL 或根絕對路徑否則拋錯。歸一化結(jié)果存入SiteConfig.assetsBase。assetsShards類型number默認(rèn)值undefined將生成的資源分散到assetsDir下的這么多個子目錄中assets/0/到assets/N-1/而不是一個扁平目錄。適用于主機(jī)對每個目錄的文件數(shù)量設(shè)限的場景——例如 Netlify 允許 54,000 個文件。每個頁面會產(chǎn)出兩個 JavaScript 文件因此一個 60,000 頁的站點(diǎn)至少需要 3 個 shard并留出一定余量因?yàn)槲募疵Q哈希分布。export default { assetsShards: 4 }共享 chunk 保留在assets/chunks/中。一個文件屬于哪個 shard 只取決于它的文件名因此未變化的文件在構(gòu)建之間 URL 保持穩(wěn)定。只影響生產(chǎn)構(gòu)建。源碼校驗(yàn)assetsShards必須是大于 1 的整數(shù)否則構(gòu)建報錯config.ts?？蛻舳送ㄟ^ hashmap 中帶 shard 前綴的條目定位 chunk無需猜測目錄布局見 pageChunkPath。icons類型{ include?: string[] }生成圖標(biāo)樣式的選項(xiàng)。構(gòu)建時會收集 SSR 期間渲染出的每一個 iconify 圖標(biāo)。名稱以完全限定的collection:name形式書寫并對照項(xiàng)目依賴中聲明的iconify-json/*包解析。僅在客戶端渲染的圖標(biāo)——例如在ClientOnly內(nèi)部、或水合之后才渲染的圖標(biāo)——對 SSR 收集是不可見的。把它們列入include以強(qiáng)制加入樣式表export default { icons: { include: [mdi:home, simple-icons:discord] } }cacheDir類型string默認(rèn)值./.vitepress/cache緩存文件目錄相對于項(xiàng)目根目錄。參見 Vite 的 cacheDir 選項(xiàng)export default { cacheDir: ./.vitepress/.vite }ignoreDeadLinks類型boolean | localhostLinks | (string | RegExp | ((link: string, source: string) boolean))[]默認(rèn)值false設(shè)為true時VitePress 不會因?yàn)樗梨湺鴺?gòu)建失敗。設(shè)為localhostLinks時構(gòu)建仍會因死鏈?zhǔn)〉粰z查localhost鏈接。export default { ignoreDeadLinks: true }也可以是精確 URL 字符串、正則模式或自定義過濾函數(shù)的數(shù)組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) } ] }注意自定義過濾函數(shù)接收(link, source)兩個參數(shù)source是鏈接所在頁面的標(biāo)識。mpa實(shí)驗(yàn)性類型boolean默認(rèn)值false設(shè)為true時生產(chǎn)應(yīng)用將以 MPA 模式 構(gòu)建。MPA 模式默認(rèn)提供 0kb JavaScript代價是禁用客戶端導(dǎo)航交互能力需要顯式選擇啟用。主題Themingappearance類型boolean | dark | force-dark | force-auto | import(vueuse/core).UseDarkOptions默認(rèn)值true是否啟用深色模式通過向html元素添加.dark類實(shí)現(xiàn)。設(shè)為true默認(rèn)主題由用戶偏好的色彩方案決定設(shè)為dark默認(rèn)使用深色主題除非用戶手動切換設(shè)為false用戶無法切換主題設(shè)為force-dark始終深色用戶無法切換設(shè)為force-auto始終跟隨系統(tǒng)色彩偏好用戶無法切換。該選項(xiàng)會注入一段內(nèi)聯(lián)腳本使用vitepress-theme-appearance這個 localStorage key 恢復(fù)用戶設(shè)置。這確保.dark類在頁面渲染之前就被應(yīng)用避免閃爍。appearance.initialValue只能是dark | undefined不支持 ref 或 getter。源碼實(shí)現(xiàn)APPEARANCE_KEY vitepress-theme-appearance定義在 src/shared/shared.ts。內(nèi)聯(lián)腳本由 resolveSiteDataHead 注入根據(jù)配置生成check-dark-mode腳本分別處理force-dark、force-auto與普通localStorage prefers-color-scheme三種分支同時在appearance未禁用時還會注入check-mac-os腳本用于平臺類名。lastUpdated類型boolean默認(rèn)值false是否使用 Git 獲取每個頁面的最后更新時間戳。該時間戳?xí)诿總€頁面的 page data 中可通過useData訪問。使用默認(rèn)主題時啟用該選項(xiàng)會在每個頁面顯示最后更新時間?？赏ㄟ^themeConfig.lastUpdated.text自定義顯示文本。值得注意的是從 resolveConfig 的實(shí)現(xiàn)看lastUpdated默認(rèn)值實(shí)際上是userConfig.lastUpdated ?? !!userConfig.themeConfig?.lastUpdated——即頂層未顯式設(shè)置時會回退到themeConfig.lastUpdated的值。定制Customizationmarkdown 配置透傳類型MarkdownOption配置 Markdown 解析器選項(xiàng)。VitePress 使用 Markdown-It 作為解析器并使用 Shiki 做語法高亮。在該選項(xiàng)中可傳入各種 Markdown 相關(guān)選項(xiàng)export default { markdown: {...} }全部可用選項(xiàng)可查看類型聲明與 JSDoc對應(yīng)的實(shí)現(xiàn)文件為 src/node/markdown/markdown.ts。將markdown.headers設(shè)為true或傳入mdit-vue/plugin-headers的選項(xiàng)可以收集標(biāo)題到useData().page.headers。該選項(xiàng)默認(rèn)禁用。vite 配置透傳類型import(vite).UserConfig將原始 Vite Config 傳給內(nèi)部 Vite dev server / bundlerexport default { vite: { // Vite config options } }在mergeConfig中根層級的vite鍵會交給 Vite 的mergeConfig深度合并config.tsconfigFile還可以指向額外的 Vite 配置文件或設(shè)為false禁用加載。vue 配置透傳類型import(vitejs/plugin-vue).Options將原始vitejs/plugin-vue選項(xiàng)傳給內(nèi)部插件實(shí)例export default { vue: { // vitejs/plugin-vue options } }構(gòu)建鉤子Build HooksVitePress 構(gòu)建鉤子允許你為網(wǎng)站添加新的功能與行為典型用途包括Sitemap 生成搜索索引PWATeleports傳送門內(nèi)容處理buildEnd類型(siteConfig: SiteConfig) AwaitablevoidbuildEnd是構(gòu)建 CLI 鉤子在構(gòu)建SSG完成后、VitePress CLI 進(jìn)程退出前運(yùn)行export default { async buildEnd(siteConfig) { // ... } }典型用途如生成 RSS feed在UserConfig.buildEnd的 JSDoc 中明確舉例見 siteConfig.ts。postRender類型(context: SSGContext) AwaitableSSGContext | voidpostRender是構(gòu)建鉤子在 SSG 渲染完成后調(diào)用。它允許你在 SSG 期間處理 teleports 內(nèi)容export default { async postRender(context) { // ... } }interface SSGContext { content: string teleports?: Recordstring, string vpIcons: Setstring [key: string]: any }從類型定義看types/shared.d.tsSSGContext中的vpIcons是 SSR 期間通過useIcon注冊的圖標(biāo)集合完全限定名為collection:name構(gòu)建器據(jù)此只發(fā)出用到的圖標(biāo)樣式。transformHead類型(context: TransformContext) AwaitableHeadConfig[]transformHead是為每個頁面向head添加額外標(biāo)簽的構(gòu)建鉤子。它允許你添加無法靜態(tài)寫入 VitePress 配置的 head 條目。只需返回額外條目它們會被自動與現(xiàn)有條目合并。?? 警告不要修改context內(nèi)部的任何內(nèi)容。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 }該鉤子只在構(gòu)建時調(diào)用開發(fā)模式不會調(diào)用。額外標(biāo)簽會被加入構(gòu)建生成的靜態(tài) HTML 文件客戶端導(dǎo)航時不會更新。在很多情況下使用transformPageData鉤子是更干凈的選擇——該鉤子同時作用于客戶端導(dǎo)航與開發(fā)模式。但如果生成 head 標(biāo)簽計(jì)算開銷較大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 } ]] } }這里假設(shè)圖片 URL 是動態(tài)生成且耗時的使用transformHead可以在開發(fā)階段避免該開銷。對于更簡單的場景可以使用 frontmatter 的head設(shè)置或transformPageData。transformHtml類型(code: string, id: string, context: TransformContext) Awaitablestring | voidtransformHtml是在每個頁面內(nèi)容寫入磁盤之前對其進(jìn)行轉(zhuǎn)換的構(gòu)建鉤子?? 警告不要修改context內(nèi)部的任何內(nèi)容。另外修改 HTML 內(nèi)容可能在運(yùn)行時引起水合問題。 注意此時圖標(biāo)樣式表鏈接仍攜帶vp-icons.__VP_ICONS_HASH__.css占位符——內(nèi)容哈希要等所有頁面渲染完成才存在緊接著才會被替換。內(nèi)聯(lián)或?qū)?head 資源做指紋化的鉤子應(yīng)跳過該標(biāo)簽。export default { async transformHtml(code, id, context) { // ... } }transformPageData類型(pageData: PageData, context: TransformPageContext) AwaitablePartialPageData | { [key: string]: any } | voidtransformPageData是轉(zhuǎn)換每個頁面pageData的鉤子。你可以直接修改pageData或返回變更后的值會被合并進(jìn)頁面數(shù)據(jù)?? 警告不要修改context內(nèi)部的任何內(nèi)容并注意這可能會影響 dev server 的性能尤其是鉤子中有網(wǎng)絡(luò)請求或重計(jì)算如生成圖片時?？梢酝ㄟ^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 都生效且返回值會合并進(jìn)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配置加載、歸一化與目錄級配置收集的實(shí)現(xiàn)見 src/node/config.ts站點(diǎn)數(shù)據(jù)按路由解析與 head 合并邏輯見 src/shared/shared.ts頁面級覆蓋規(guī)則見 Frontmatter 配置參考多語言與 RTL 支持見 國際化指南路由與重寫見 路由指南資源處理見 靜態(tài)資源指南部署時的 base 與相對構(gòu)建見 部署指南?！久赓M(fèi)下載鏈接】vitepressVite Vue powered static site generator.項(xiàng)目地址: https://gitcode.com/gh_mirrors/vi/vitepress創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考