Skip to content
CONSTRUCTING

配置 Vite 插件

字数
1121 字
阅读时间
5 分钟

安装

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

shell
ni @nolebase/vitepress-plugin-thumbnail-hash -D
shell
pnpm add @nolebase/vitepress-plugin-thumbnail-hash -D
shell
npm install @nolebase/vitepress-plugin-thumbnail-hash -D
shell
yarn add @nolebase/vitepress-plugin-thumbnail-hash -D

使用

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

配置 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 用户吗?

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

jsonc
{
  "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

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

jsonc
{
  "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"
  ]
}
typescript
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 项目的目录结构如下所示:

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

在这种情况下,根目录是 docs

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

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

shell
touch vite.config.ts
vite.config.ts 中配置插件

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

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

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

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

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

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

是 TypeScript 用户吗?

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

jsonc
{
  "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

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

jsonc
{
  "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"
  ]
}
typescript
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 用户吗?

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

jsonc
{
  "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

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

jsonc
{
  "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"
  ]
}
typescript
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 选项:

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

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

贡献者

页面历史