配置 Vite 插件

字数

1121 字

阅读时间

5 分钟

安装

通过运行以下命令将 @nolebase/vitepress-plugin-thumbnail-hash 安装到您的项目依赖项中：

@antfu/ni

ni @nolebase/vitepress-plugin-thumbnail-hash -D

pnpm

pnpm add @nolebase/vitepress-plugin-thumbnail-hash -D

npm

npm install @nolebase/vitepress-plugin-thumbnail-hash -D

yarn

yarn add @nolebase/vitepress-plugin-thumbnail-hash -D

使用

将缩略图模糊哈希生成插件集成到您的 VitePress 项目中包括两个主要步骤：

• 配置 Vite 插件（数据获取、日志聚合）
• 与 VitePress 集成（UI 和组件）

配置 Vite 插件

有两种将缩略图模糊哈希生成 Vite 插件集成到您的 VitePress 项目中的方法：

1. 推荐：在 VitePress 的主要配置文件中使用 vite 选项（通常位于 docs/.vitepress/config.ts，文件路径和扩展名可能会有所不同）
2. 在 VitePress 项目的根目录中创建一个单独的 Vite 配置文件（例如 vite.config.ts）

在 VitePress 的配置文件中配置 Vite 插件

请在你的 VitePress 核心配置文件 中（注意不是主题配置文件，通常为 docs/.vitepress/config.ts，文件路径和拓展名也许会有区别）的根字段中添加 Vite 选项，并导入并配置 ThumbnailHashImages 插件：

如果你未曾见过这种红色绿色的标记

这是一种用于在用户界面（UI）上展示差异对比的标记规则。

红色的部分是你需要删除的，通常也以「减号 -」来表示，或者你可以理解为：这行文本原本的模样；

绿色的部分是你需要添加的，通常也以「加号 +」来表示，或者你可以理解为：这行文本将会被修改为的模样。

如果你想要了解更多有关「差异对比」的知识，你可以查看这篇有关 diffutils 历史的英文回答和 Git 的文档

是 TypeScript 用户吗？

至少需要配置下面的几个选项：

{
  "compilerOptions": {
    "module": "ESNext", 
    "moduleResolution": "Bundler", 
  },
  "include": [
    "**/.vitepress/**/*.ts",
    "**/.vitepress/**/*.mts",
    "**/.vitepress/**/*.vue"
  ],
  "exclude": [
    "node_modules"
  ]
}

其中的

• module 选项指定了 JavaScript/TypeScript 的模块格式，Nolebase Integrations 默认使用与 ESNext 相兼容的模块格式。
• moduleResolution 选项指定了模块解析策略，因为所有的 Nolebase Integrations 插件都遵循最新的 ECMAScript 规范与导出声明，如果你遇到了 Cannot find module ... or its corresponding type declarations 的错误，你可能需要将 moduleResolution 设置为 Bundler。

如果你想要更多的配置，可以参考下面的示例：

{
  "compilerOptions": {
    "jsx": "preserve",
    "lib": [
      "DOM",
      "ESNext"
    ],
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "resolveJsonModule": true,
    "strict": true,
    "strictNullChecks": true,
    "noFallthroughCasesInSwitch": true,
    "noImplicitAny": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noEmit": true,
    "removeComments": false,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "isolatedModules": true,
    "verbatimModuleSyntax": true,
    "skipLibCheck": true
  },
  "include": [
    "**/.vitepress/**/*.ts",
    "**/.vitepress/**/*.mts",
    "**/.vitepress/**/*.vue"
  ],
  "exclude": [
    "node_modules"
  ]
}

import { defineConfig } from 'vitepress'
import { 
  ThumbnailHashImages, 
} from '@nolebase/vitepress-plugin-thumbnail-hash/vite'

// https://vitepress.dev/reference/site-config
export default defineConfig({
  vite: { 
    plugins: [ 
      ThumbnailHashImages(), 
    ],
  }, 
  lang: 'en',
  title: 'Site Name',
  themeConfig: {
    // rest of the options...
  }
  // rest of the options...
})

在单独的 Vite 配置文件中配置 Vite 插件

确保已创建 vite.config.ts

如果您已经了解 vite.config.ts 是什么并且已经创建了它，您可以跳过此准备步骤，直接跳转到下一步在 vite.config.ts 中配置插件。

首次接触 vite.config.ts？

首先，vite.config.ts 是一个为 Vite 构建工具的配置文件。VitePress 是基于 Vite 构建的，它允许开发人员构建和转换项目中的资产、内容和数据。

VitePress 本身包含了整套 Vite 选项的配置在其主要配置文件中（这不是一个主题配置文件，通常位于 docs/.vitepress/config.ts，文件路径和扩展名可能会有所不同），这些选项与 vite.config.ts 在配置方面是相同的。

因此，请在您的 VitePress 项目的根目录中创建一个单独的 vite.config.ts 文件：

哪里是 VitePress 项目的根目录？

VitePress 项目的根目录是 .vitepress 目录的父目录。

例如，如果您的 VitePress 项目的目录结构如下所示：

.
├── docs
│   ├── .vitepress
│   │   ├── config.ts
│   │   └── theme
│   │       └── index.ts
│   └── README.md

在这种情况下，根目录是 docs。

.
├── .vitepress
│   ├── config.ts
│   └── theme
│       └── index.ts
└── README.md

在这种情况下，根目录是 ./。

touch vite.config.ts

在 vite.config.ts 中配置插件

在位于项目根目录的独立的 Vite 配置文件（也就是 vite.config.ts 中），我们需要导入 ThumbnailHashImages 插件并进行正确配置：

如果你未曾见过这种红色绿色的标记

这是一种用于在用户界面（UI）上展示差异对比的标记规则。

红色的部分是你需要删除的，通常也以「减号 -」来表示，或者你可以理解为：这行文本原本的模样；

绿色的部分是你需要添加的，通常也以「加号 +」来表示，或者你可以理解为：这行文本将会被修改为的模样。

如果你想要了解更多有关「差异对比」的知识，你可以查看这篇有关 diffutils 历史的英文回答和 Git 的文档

是 TypeScript 用户吗？

至少需要配置下面的几个选项：

{
  "compilerOptions": {
    "module": "ESNext", 
    "moduleResolution": "Bundler", 
  },
  "include": [
    "**/.vitepress/**/*.ts",
    "**/.vitepress/**/*.mts",
    "**/.vitepress/**/*.vue"
  ],
  "exclude": [
    "node_modules"
  ]
}

其中的

• module 选项指定了 JavaScript/TypeScript 的模块格式，Nolebase Integrations 默认使用与 ESNext 相兼容的模块格式。
• moduleResolution 选项指定了模块解析策略，因为所有的 Nolebase Integrations 插件都遵循最新的 ECMAScript 规范与导出声明，如果你遇到了 Cannot find module ... or its corresponding type declarations 的错误，你可能需要将 moduleResolution 设置为 Bundler。

如果你想要更多的配置，可以参考下面的示例：

{
  "compilerOptions": {
    "jsx": "preserve",
    "lib": [
      "DOM",
      "ESNext"
    ],
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "resolveJsonModule": true,
    "strict": true,
    "strictNullChecks": true,
    "noFallthroughCasesInSwitch": true,
    "noImplicitAny": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noEmit": true,
    "removeComments": false,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "isolatedModules": true,
    "verbatimModuleSyntax": true,
    "skipLibCheck": true
  },
  "include": [
    "**/.vitepress/**/*.ts",
    "**/.vitepress/**/*.mts",
    "**/.vitepress/**/*.vue"
  ],
  "exclude": [
    "node_modules"
  ]
}

import { join } from 'node:path'
import { defineConfig } from 'vite'
import { 
  ThumbnailHashImages, 
} from '@nolebase/vitepress-plugin-thumbnail-hash/vite'

export default defineConfig(() => {
  return {
    plugins: [ 
      ThumbnailHashImages(), 
    ]
    // other vite configurations...
  }
})

与 VitePress 主题集成

现在，让我们将缩略图模糊哈希生成插件集成到您的 VitePress 项目中。

在 VitePress 的主题配置文件（请注意，这与上面提及的配置文件并非是一个文件，主题配置文件通常位于 docs/.vitepress/theme/index.ts，文件路径和扩展名可能会有所不同），安装 Vue 插件并使用组件：

是 TypeScript 用户吗？

至少需要配置下面的几个选项：

{
  "compilerOptions": {
    "module": "ESNext", 
    "moduleResolution": "Bundler", 
  },
  "include": [
    "**/.vitepress/**/*.ts",
    "**/.vitepress/**/*.mts",
    "**/.vitepress/**/*.vue"
  ],
  "exclude": [
    "node_modules"
  ]
}

其中的

• module 选项指定了 JavaScript/TypeScript 的模块格式，Nolebase Integrations 默认使用与 ESNext 相兼容的模块格式。
• moduleResolution 选项指定了模块解析策略，因为所有的 Nolebase Integrations 插件都遵循最新的 ECMAScript 规范与导出声明，如果你遇到了 Cannot find module ... or its corresponding type declarations 的错误，你可能需要将 moduleResolution 设置为 Bundler。

如果你想要更多的配置，可以参考下面的示例：

{
  "compilerOptions": {
    "jsx": "preserve",
    "lib": [
      "DOM",
      "ESNext"
    ],
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "resolveJsonModule": true,
    "strict": true,
    "strictNullChecks": true,
    "noFallthroughCasesInSwitch": true,
    "noImplicitAny": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noEmit": true,
    "removeComments": false,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "isolatedModules": true,
    "verbatimModuleSyntax": true,
    "skipLibCheck": true
  },
  "include": [
    "**/.vitepress/**/*.ts",
    "**/.vitepress/**/*.mts",
    "**/.vitepress/**/*.vue"
  ],
  "exclude": [
    "node_modules"
  ]
}

docs/.vitepress/theme/index.ts

import { h } from 'vue'
import DefaultTheme from 'vitepress/theme'
import type { Theme as ThemeConfig } from 'vitepress'
import { 
  NolebaseUnlazyImg, 
} from '@nolebase/vitepress-plugin-thumbnail-hash/client'

import '@nolebase/vitepress-plugin-thumbnail-hash/client/style.css'

export const Theme: ThemeConfig = {
  extends: DefaultTheme,
  Layout: () => {
    // other configurations...
  },
  enhanceApp({ app }) {
    app.component('NolebaseUnlazyImg', NolebaseUnlazyImg)  
  },
}

export default Theme

接下来？

为了显示和使用 VitePress 页面所需的缩略图模糊哈希。请查看另一个我们提供的名为 markdown-it-unlazy-img 的插件。

错误排查

遭遇了 Cannot find module ... or its corresponding type declarations 错误？

如果有任何的 Nolebase Integrations 插件在 .ts 或 .vue 文件中出现此错误，你可能需要在 tsconfig.json 文件中配置 moduleResolution 选项：

{
  "compilerOptions": {
    "module": "ESNext", 
    "moduleResolution": "Bundler", 
  },
  "include": [
    "**/.vitepress/**/*.ts",
    "**/.vitepress/**/*.mts",
    "**/.vitepress/**/*.vue"
  ],
  "exclude": [
    "node_modules"
  ]
}

如果错误仍然存在，请提交 GitHub issue 以获得进一步帮助并排除故障。

贡献者

Neko

页面历史

最后编辑于 大约 1 个月前

查看完整历史

a77cb30-feat(index): new plugin vitepress-plugin-index (#328)

b5df2cf-docs: added new documentations for thumbnail hasing and unlazy img (#304)