git

@vuepress/plugin-git

该插件会收集页面的 Git 信息，包括创建时间、更新时间、贡献者列表以及变更日志等。

默认主题中的 lastUpdated 和 contributors 功能正是由该插件提供支持的。

该插件主要用于主题开发，在大多数情况下你不需要直接使用它，而是通过主题配置来开启相关功能。

使用方法

npm i -D @vuepress/plugin-git@next
.vuepress/config.ts
import { gitPlugin } from '@vuepress/plugin-git'

export default {
  plugins: [
    gitPlugin({
      // 配置项
    }),
  ],
}

Git 仓库

本插件要求你的项目必须在一个 Git 仓库中，以便它能从提交历史中收集信息。

你应该确保在构建站点时可以访问到完整的提交记录。例如，CI 工作流（如 GitHub Actions）通常会使用 --depth 1 来克隆仓库以减少下载量，这会导致无法获取历史记录。为了让本插件正常工作，你应该在 CI 配置中禁用这种浅克隆行为（通常是将 fetch-depth 设置为 0）。

注意

该插件会显著降低数据准备阶段的速度，特别是当你拥有大量页面时。你可以考虑在 dev 模式下禁用此插件，以获得更好的开发体验。

选项

createdTimeboolean
默认值true

是否收集页面的创建时间。

updatedTimeboolean
默认值true

是否收集页面的更新时间。

contributorsContributorsOptions | boolean
默认值true

是否收集页面的贡献者信息。你也可以传入一个对象进行配置。

contributors.infoContributorInfo[]

预定义的贡献者信息。

contributors.info[*].username必填string

贡献者在 git 托管服务上的用户名。

contributors.info[*].namestring

页面上显示的贡献者名称，默认为 username。

contributors.info[*].aliasstring[] | string

贡献者的别名。因为贡献者在本地 git 配置中保存的用户名可能与托管服务上的用户名不同，在这种情况下，可以使用别名映射到实际的用户名。

contributors.info[*].emailstring

贡献者的主要邮箱。

contributors.info[*].emailAliasstring[] | string

贡献者在 Git 托管服务上的备用邮箱，或者他们过去使用过的邮箱。

contributors.info[*].avatarstring

贡献者的头像 url。如果 git 托管服务是 github，可以忽略并留空，插件会自动填充它。

contributors.info[*].urlstring

贡献者的主页 url。如果 git 托管服务是 github，可以忽略并留空，插件会自动填充它。

contributors.avatarboolean
默认值false

是否在贡献者信息中添加头像。

contributors.avatarPatternstring

头像 url 模式。

  • :username - 贡献者的用户名
contributors.transform(contributors: GitContributorInfo[]) => GitContributorInfo[]

转换贡献者列表的函数，例如去重和排序。输入是插件收集到的贡献者列表，输出应该是转换后的贡献者列表。

changelogChangelogOptions | boolean
默认值false

是否收集页面的变更日志。你也可以传入一个对象进行配置。

changelog.maxCountnumber

变更日志的最大条目数。

changelog.repoUrlstring

git 仓库的 url，例如 https://github.com/vuepress/ecosystem。

changelog.commitUrlPatternstring
默认值':repo/commit/:hash'

提交记录 url 模式。

  • :repo - git 仓库的 url
  • :hash - 提交记录的哈希值
changelog.issueUrlPatternstring
默认值':repo/issues/:issue'

Issue url 模式。

  • :repo - git 仓库的 url
  • :issue - Issue 的 ID
changelog.tagUrlPatternstring
默认值':repo/releases/tag/:tag'

Tag url 模式。

  • :repo - git 仓库的 url
  • :tag - Tag 的名称
filter(page: Page) => boolean

页面过滤器。如果返回 true，则该页面将收集 git 信息。

localesRecord<string, GitLocaleData>

多语言配置，用于 Git 组件。

参考：多语言配置。

locales.<localePath>.contributorsstring

贡献者标题。

locales.<localePath>.changelogstring

变更日志标题。

locales.<localePath>.timeOnstring

用于表示提交时间 "在" 某时的词语。

locales.<localePath>.viewChangelogstring

查看变更日志按钮的文字。

locales.<localePath>.latestUpdateAtstring

最近更新的文字。

Frontmatter

gitIncludestring[]

一个包含相对路径的数组。在计算页面数据（如时间、贡献者）时，会将这些文件的 Git 历史也包含在内。

---
gitInclude:
  - relative/path/to/file1
  - relative/path/to/file2
---
contributorsboolean | string[]

是否收集当前页面的贡献者信息，此值将覆盖全局的 contributors 配置项。

  • true - 收集贡献者信息
  • false - 不收集贡献者信息
  • string[] - 额外的贡献者列表。有时页面会有额外的贡献者（例如不在 git 历史中），可以使用此配置项指定额外的贡献者列表以获取其详细信息。
changelogboolean

是否收集当前页面的变更历史，此值将覆盖全局的 changelog 配置项。

组合式 API

你可以从 @vuepress/plugin-git/client 导入以下组合式 API。

useChangelog

获取当前页面的变更日志。

export interface CoAuthorInfo {
  /**
   * 共同作者姓名
   */
  name: string
  /**
   * 共同作者邮箱
   */
  email: string
}

export interface GitChangelogItem extends GitChangelogInfo {
  /**
   * 提交哈希
   */
  hash: string
  /**
   * Unix 时间戳（毫秒）
   */
  time: number
  /**
   * 提交信息
   */
  message: string
  /**
   * 提交记录的 url
   */
  commitUrl?: string
  /**
   * 发布标签 (tag)
   */
  tag?: string
  /**
   * 发布标签的 url
   */
  tagUrl?: string
  /**
   * 提交作者姓名
   */
  author: string
  /**
   * 提交作者邮箱
   */
  email: string

  /**
   * 提交的共同作者
   */
  coAuthors?: CoAuthorInfo[]

  /**
   * 提交的日期文本
   */
  date: string
}

export const useChangelog: (
  enabled?: MaybeRefOrGetter<boolean>,
) => ComputedRef<GitChangelogItem[]>

useContributors

获取当前页面的贡献者列表。

export interface GitContributorInfo {
  /**
   * 贡献者显示名称
   */
  name: string
  /**
   * 贡献者邮箱
   */
  email: string

  /**
   * 贡献者在 git 托管服务上的用户名
   */
  username: string
  /**
   * 提交次数
   */
  commits: number
  /**
   * 贡献者头像
   */
  avatar?: string
  /**
   * 贡献者主页 url
   */
  url?: string
}

export const useContributors: (
  enabled?: MaybeRefOrGetter<boolean>,
) => ComputedRef<GitContributorInfo[]>

useLastUpdated

获取当前页面的最后更新时间。

export interface LastUpdated {
  /**
   * 最后更新时间的 Date 对象
   */
  date: Date
  /**
   * 最后更新时间的 ISO 字符串
   */
  iso: string
  /**
   * 最后更新时间的格式化文本
   */
  text: string
  /**
   * 最后更新时间的语言环境
   */
  locale: string
}

export const useLastUpdated: (
  enabled?: MaybeRefOrGetter<boolean>,
) => ComputedRef<LastUpdated | null>

页面数据

该插件会向页面数据（Page Data）中添加一个 git 字段。

使用该插件后，你可以通过以下方式在页面数据中获取收集到的 git 信息：

import type { GitPluginPageData } from '@vuepress/plugin-git'
import { usePage } from 'vuepress/client'

export default {
  setup(): void {
    const page = usePage<GitPluginPageData>()
    console.log(page.value.git)
  },
}

git.createdTime

  • 类型：number

  • 详情：

    页面第一次提交的 Unix 时间戳（毫秒）。

    该属性会取当前页面以及 gitInclude 中列出的文件的最早提交时间戳中的最小值。

git.updatedTime

  • 类型：number

  • 详情：

    页面最后一次提交的 Unix 时间戳（毫秒）。

    该属性会取当前页面以及 gitInclude 中列出的文件的最后提交时间戳中的最大值。

git.contributors

  • 类型：GitContributorInfo[]
interface GitContributorInfo {
  // 显示名称
  name: string
  email: string
  // git 托管服务上的用户名
  username: string
  commits: number
  avatar?: string
  url?: string
}

  • 详情：

    页面的贡献者信息。

    该属性也会包含 gitInclude 中列出的文件的贡献者。

git.changelog

  • 类型：GitChangelogInfo[]
interface CoAuthorInfo {
  /**
   * 共同作者姓名
   */
  name: string
  /**
   * 共同作者邮箱
   */
  email: string
}

interface GitChangelogInfo {
  /**
   * 提交哈希
   */
  hash: string
  /**
   * Unix 时间戳（毫秒）
   */
  time: number
  /**
   * 提交信息
   */
  message: string
  /**
   * 提交记录的 url
   */
  commitUrl?: string
  /**
   * 发布标签 (tag)
   */
  tag?: string
  /**
   * 发布标签的 url
   */
  tagUrl?: string
  /**
   * 提交作者姓名
   */
  author: string
  /**
   * 提交作者邮箱
   */
  email: string

  /**
   * 提交的共同作者
   */
  coAuthors?: CoAuthorInfo[]
}

  • 详情：

    页面的变更日志。

    该属性也会包含 gitInclude 中列出的文件的变更记录。

Git 组件

本插件提供了与 Git 信息相关的全局组件，可在主题中直接使用。

GitContributors

列出当前页面的贡献者信息。

<template>
  <div vp-content>
    <Content />
    <GitContributors />
  </div>
</template>

效果预览：

贡献者

Mister-Hopemeteorlxypengzhanbo

GitChangelog

列出当前页面的变更日志。

<template>
  <div vp-content>
    <Content />
    <GitChangelog />
  </div>
</template>

效果预览：

更新日志

2026/9/28 04:40
查看所有更新日志
  • d715a-docs: rebuild docs (#925)于
  • 2c88a-docs: improve git docs于
  • 81918-build: bump deps (#546)于
  • 0f128-refactor(plugin-git): add jsdoc and improve docs (#493)于
  • efbf4-docs: tweaks于
  • 8fc70-refactor: prefer useData and short api name (#448)于
  • a13d5-docs: improve code block title于
  • 7dd53-feat(plugin-git): add support to find git contributor by email (#412)于
  • d0d19-docs: use actual component for git preview于
  • 63eb8-feat(plugin-git): improve composables and add docs (#409)于
  • acd14-feat(plugin-git): export global component, close #389 (#391)于
  • 56cec-feat(plugin-git): add built-in component <Contributors/> <Changelog/>, close #375 (#384)于
  • ae96c-docs: add icons to docs (#332)于
  • a0241-feat(plugin-git): improve commits parsing and optimize plugins (#292)于
  • 51b79-feat(plugin-git): improve performance and tweaks options (#287)于
  • 448d8-feat(plugin-git): add collect of co-authors (#285)于
  • b526b-feat(plugin-git): support changelog and improve performance (#283)于
  • d431d-feat(plugin-git): add transformContributors options于
  • 29ccd-chore: use eslint v9 (#237)于
  • abd78-chore: update repo structure (#159)于
  • 082a9-feat(plugin-links-check): add links check plugin于
  • ceb04-docs: add ecosystem docs (close #36) (#38)于