import{_ as e,c as h,ag as t,j as i,a,G as l,B as p,o as k}from"./chunks/framework.C1C4sYC0.js";const m=JSON.parse('{"title":"站点配置","description":"","frontmatter":{"outline":"deep"},"headers":[],"relativePath":"zh/reference/site-config.md","filePath":"zh/reference/site-config.md","lastUpdated":1722674502000}'),r={name:"zh/reference/site-config.md"},d={id:"metachunk",tabindex:"-1"},E={id:"mpa",tabindex:"-1"};function g(o,s,c,y,F,u){const n=p("Badge");return k(),h("div",null,[s[6]||(s[6]=t(`

站点配置 ​

站点配置可以定义站点的全局设置。应用配置选项适用于每个 VitePress 站点，无论它使用什么主题。例如根目录或站点的标题。

概览 ​

配置解析 ​

配置文件总是从 <root>/.vitepress/config.[ext] 解析，其中 <root> 是 VitePress 项目根目录，[ext] 是支持的文件扩展名之一。开箱即用地支持 TypeScript。支持的扩展名包括 .js、.ts、.mjs 和 .mts。

建议在配置文件中使用 ES 模块语法。配置文件应该默认导出一个对象：

ts
export default {
  // 应用级配置选项
  lang: 'en-US',
  title: 'VitePress',
  description: 'Vite & Vue powered static site generator.',
  ...
}
异步的动态配置

如果需要动态生成配置，也可以默认导出一个函数，例如：

ts
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}\`
        }))
      ]
    }
  })
}

也可以在最外层使用 await。例如：

ts
import { 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}\`
      }))
    ]
  }
})

配置智能提示 ​

使用 defineConfig 辅助函数将为配置选项提供 TypeScript 支持的智能提示。假设 IDE 支持它，那么在 JavaScript 和 TypeScript 中都将触发智能提示。

js
import { defineConfig } from 'vitepress'

export default defineConfig({
  // ...
})

主题类型提示 ​

默认情况下，defineConfig 辅助函数期望默认主题的主题配置数据类型为：

ts
import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    // 类型为 \`DefaultTheme.Config\`
  }
})

如果使用自定义主题并希望对主题配置进行类型检查，则需要改用 defineConfigWithTheme，并通过通用参数传递自定义主题的配置类型：

ts
import { defineConfigWithTheme } from 'vitepress'
import type { ThemeConfig } from 'your-theme'

export default defineConfigWithTheme<ThemeConfig>({
  themeConfig: {
    // 类型为 \`ThemeConfig\`
  }
})

Vite、Vue 和 Markdown 配置 ​

站点元数据 ​

title ​

站点的标题。使用默认主题时，这将显示在导航栏中。

它还将用作所有单独页面标题的默认后缀，除非定义了 titleTemplate。单个页面的最终标题将是其第一个 <h1> 标题的文本内容加上的全局 title。例如使用以下配置和页面内容：

ts
export default {
  title: 'My Awesome Site'
}
md
# Hello

页面标题就是 Hello | My Awesome Site.

titleTemplate ​

允许自定义每个页面的标题后缀或整个标题。例如：

ts
export default {
  title: 'My Awesome Site',
  titleTemplate: 'Custom Suffix'
}
md
# Hello

页面标题就是 Hello | Custom Suffix.

要完全自定义标题的呈现方式，可以在 titleTemplate 中使用 :title 标识符：

ts
export default {
  titleTemplate: ':title - Custom Suffix'
}

这里的 :title 将替换为从页面的第一个 <h1> 标题推断出的文本。上一个示例页面的标题将是 Hello - Custom Suffix。

该选项可以设置为 false 以禁用标题后缀。

description ​

站点的描述。这将呈现为页面 HTML 中的 <meta> 标签。

ts
export default {
  description: 'A VitePress site'
}

要在页面 HTML 的 <head> 标签中呈现的其他元素。用户添加的标签在结束 head 标签之前呈现，在 VitePress 标签之后。

ts
type HeadConfig =
  | [string, Record<string, string>]
  | [string, Record<string, string>, string]

示例：添加一个图标 ​

ts
export default {
  head: [['link', { rel: 'icon', href: '/favicon.ico' }]]
} // 将 favicon.ico 放在公共目录中，如果设置了 base，则使用 /base/favicon.ico

/* 渲染成:
  <link rel="icon" href="/favicon.ico">
*/

示例：添加谷歌字体 ​

ts
export 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?family=Roboto&display=swap', rel: 'stylesheet' }
    ]
  ]
}

/* 渲染成:
  <link rel="preconnect" href="https://fonts.googleapis.com">
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
  <link href="https://fonts.googleapis.com/css2?family=Roboto&display=swap" rel="stylesheet">
*/

示例：添加一个 serviceWorker ​

ts
export default {
  head: [
    [
      'script',
      { id: 'register-sw' },
      \`;(() => {
        if ('serviceWorker' in navigator) {
          navigator.serviceWorker.register('/sw.js')
        }
      })()\`
    ]
  ]
}

/* 渲染成:
  <script id="register-sw">
    ;(() => {
      if ('serviceWorker' in navigator) {
        navigator.serviceWorker.register('/sw.js')
      }
    })()
  </script>
*/

示例：使用谷歌分析 ​

ts
export default {
  head: [
    [
      'script',
      { async: '', src: 'https://www.googletagmanager.com/gtag/js?id=TAG_ID' }
    ],
    [
      'script',
      {},
      \`window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'TAG_ID');\`
    ]
  ]
}

/* 渲染成:
  <script async src="https://www.googletagmanager.com/gtag/js?id=TAG_ID"></script>
  <script>
    window.dataLayer = window.dataLayer || [];
    function gtag(){dataLayer.push(arguments);}
    gtag('js', new Date());
    gtag('config', 'TAG_ID');
  </script>
*/

lang ​

站点的 lang 属性。这将呈现为页面 HTML 中的 <html lang="en-US"> 标签。

ts
export default {
  lang: 'en-US'
}

base ​

站点将部署到的 base URL。如果计划在子路径例如 GitHub 页面下部署站点，则需要设置此项。如果计划将站点部署到 https://foo.github.io/bar/，那么应该将 base 设置为 '/bar/'。它应该始终以 / 开头和结尾。

base 会自动添加到其他选项中以 / 开头的所有 URL 前面，因此只需指定一次。

ts
export default {
  base: '/base/'
}

路由 ​

cleanUrls ​

当设置为 true 时，VitePress 将从 URL 中删除 .html 后缀。另请参阅生成简洁的 URL。

需要服务器支持

要启用此功能，可能需要在托管平台上进行额外配置。要使其正常工作，服务器必须能够在不重定向的情况下访问 /foo 时提供 /foo.html。

rewrites ​

自定义目录 <-> URL 映射。详细信息请参阅路由：路由重写。

ts
export default {
  rewrites: {
    'source/:page': 'destination/:page'
  }
}

构建 ​

srcDir ​

相对于项目根目录的 markdown 文件所在的文件夹。另请参阅根目录和源目录。

ts
export default {
  srcDir: './src'
}

srcExclude ​

用于匹配应排除作为源内容输出的 markdown 文件，语法详见 glob pattern。

ts
export default {
  srcExclude: ['**/README.md', '**/TODO.md']
}

outDir ​

项目的构建输出位置，相对于项目根目录。

ts
export default {
  outDir: '../public'
}

assetsDir ​

指定放置生成的静态资源的目录。该路径应位于 outDir 内，并相对于它进行解析。

ts
export default {
  assetsDir: 'static'
}

cacheDir ​

缓存文件的目录，相对于项目根目录。另请参阅：cacheDir。

ts
export default {
  cacheDir: './.vitepress/.vite'
}

当设置为 true 时，VitePress 不会因为死链而导致构建失败。

当设置为 'localhostLinks' ，出现死链时构建将失败，但不会检查 localhost 链接。

ts
export default {
  ignoreDeadLinks: true
}

它也可以是一组精确的 url 字符串、正则表达式模式或自定义过滤函数。

ts
export default {
  ignoreDeadLinks: [
    // 忽略精确网址 "/playground"
    '/playground',
    // 忽略所有 localhost 链接
    /^https?:\\/\\/localhost/,
    // 忽略所有包含 "/repl/" 的链接
    /\\/repl\\//,
    // 自定义函数，忽略所有包含 "ignore "的链接
    (url) => {
      return url.toLowerCase().includes('ignore')
    }
  ]
}
`,98)),i("h3",d,[s[0]||(s[0]=a("metaChunk ")),l(n,{type:"warning",text:"experimental"}),s[1]||(s[1]=a()),s[2]||(s[2]=i("a",{class:"header-anchor",href:"#metachunk","aria-label":'Permalink to "metaChunk "'},"​",-1))]),s[7]||(s[7]=i("ul",null,[i("li",null,[a("类型："),i("code",null,"boolean")]),i("li",null,[a("默认值："),i("code",null,"false")])],-1)),s[8]||(s[8]=i("p",null,[a("当设置为 "),i("code",null,"true"),a(" 时，将页面元数据提取到单独的 JavaScript 块中，而不是内联在初始 HTML 中。这使每个页面的 HTML 负载更小，并使页面元数据可缓存，从而当站点中有很多页面时可以减少服务器带宽。")],-1)),i("h3",E,[s[3]||(s[3]=a("mpa ")),l(n,{type:"warning",text:"experimental"}),s[4]||(s[4]=a()),s[5]||(s[5]=i("a",{class:"header-anchor",href:"#mpa","aria-label":'Permalink to "mpa "'},"​",-1))]),s[9]||(s[9]=t(`

设置为 true 时，生产应用程序将在 MPA 模式下构建。MPA 模式默认提供 零 JavaScript 支持，代价是禁用客户端导航，并且需要明确选择加入才能进行交互。

主题 ​

appearance ​

是否启用深色模式 (通过将 .dark 类添加到 <html> 元素)。

此选项注入一个内联脚本，使用 vitepress-theme-appearance key 从本地存储恢复用户设置。这确保在呈现页面之前应用 .dark 类以避免闪烁。

appearance.initialValue 只能是 'dark' | undefined。 不支持 Refs 或 getters。

lastUpdated ​

是否使用 Git 获取每个页面的最后更新时间戳。时间戳将包含在每个页面的页面数据中，可通过 useData 访问。

使用默认主题时，启用此选项将显示每个页面的最后更新时间。可以通过 themeConfig.lastUpdatedText 选项自定义文本。

自定义 ​

markdown ​

配置 Markdown 解析器选项。VitePress 使用 Markdown-it 作为解析器，使用 Shiki 来高亮不同语言语法。在此选项中，可以传递各种 Markdown 相关选项以满足你的需要。

js
export default {
  markdown: {...}
}

查看类型声明和 jsdocs 以获得所有可配置的选项。

vite ​

将原始 Vite 配置传递给内部 Vite 开发服务器 / bundler。

js
export default {
  vite: {
    // Vite 配置选项
  }
}

vue ​

将原始的 @vitejs/plugin-vue 选项传递给内部插件实例。

js
export default {
  vue: {
    // @vitejs/plugin-vue 选项
  }
}

构建钩子 ​

VitePress 构建钩子允许向站点添加新功能和行为：

buildEnd ​

buildEnd 是一个构建 CLI 钩子，它将在构建 SSG 完成后但在 VitePress CLI 进程退出之前运行。

ts
export default {
  async buildEnd(siteConfig) {
    // ...
  }
}

postRender ​

postRender 是一个构建钩子，在 SSG 渲染完成时调用。它将允许在 SSG 期间处理传递的内容。

ts
export default {
  async postRender(context) {
    // ...
  }
}
ts
interface SSGContext {
  content: string
  teleports?: Record<string, string>
  [key: string]: any
}

transformHead ​

transformHead 是一个构建钩子，用于在生成每个页面之前转换 head。它将允许添加无法静态添加到 VitePress 配置中的 head entries。只需要返回额外的 entries，它们将自动与现有 entries 合并。

WARNING

不要改变 context 中的任何东西。

ts
export default {
  async transformHead(context) {
    // ...
  }
}
ts
interface TransformContext {
  page: string // 例如 index.md (相对于 srcDir)
  assets: string[] // 所有非 js/css 资源均作为完全解析的公共 URL
  siteConfig: SiteConfig
  siteData: SiteData
  pageData: PageData
  title: string
  description: string
  head: HeadConfig[]
  content: string
}

请注意，仅在静态生成站点时才会调用此钩子。在开发期间不会调用它。如果需要在开发期间添加动态 head 条目，可以使用 transformPageData 钩子来替代：

ts
export default {
  transformPageData(pageData) {
    pageData.frontmatter.head ??= []
    pageData.frontmatter.head.push([
      'meta',
      {
        name: 'og:title',
        content:
          pageData.frontmatter.layout === 'home'
            ? \`VitePress\`
            : \`\${pageData.title} | VitePress\`
      }
    ])
  }
}
ts
export 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 ​

transformHtml 是一个构建钩子，用于在保存到磁盘之前转换每个页面的内容。

WARNING

不要改变 context 中的任何东西。另外，修改 html 内容可能会导致运行时出现激活问题。

ts
export default {
  async transformHtml(code, id, context) {
    // ...
  }
}

transformPageData ​

transformPageData 是一个钩子，用于转换每个页面的 pageData。可以直接改变 pageData 或返回将合并到 PageData 中的更改值。

WARNING

不要改变 context 中的任何东西。请注意，这可能会影响开发服务器的性能，特别是当在钩子中有一些网络请求或大量计算 (例如生成图像) 时。可以通过判断 process.env.NODE_ENV === 'production' 匹配符合条件的情况。

ts
export default {
  async transformPageData(pageData, { siteConfig }) {
    pageData.contributors = await getPageContributors(pageData.relativePath)
  }

  // 或返回要合并的数据
  async transformPageData(pageData, { siteConfig }) {
    return {
      contributors: await getPageContributors(pageData.relativePath)
    }
  }
}
ts
interface TransformPageContext {
  siteConfig: SiteConfig
}
`,60))])}const D=e(r,[["render",g]]);export{m as __pageData,D as default};