Skip to content

静态资源处理

引用静态资源

所有 Markdown 文件都会被编译成 Vue 组件,并由 Vite 处理。你可以并且应该使用相对 URL 引用任何资源:

md
![An image](./image.svg)

你可以在 Markdown 文件、主题中的 *.vue 组件、样式和纯 .css 文件中使用绝对公共路径(基于项目根目录)或相对路径(基于文件系统)引用静态资源。后者类似于你在 vue-cli 或 webpack 的 file-loader 中使用的行为。

常见的图像、媒体和字体文件类型会被自动检测并作为资源包含在内。

所有引用的资源,包括使用绝对路径的资源,都将在生产构建中复制到输出目录,并使用散列文件名。从未引用的资源将不会被复制。类似于 vue-cli,小于 4kb 的图像资源将被内联为 base64 数据 URL。

所有静态路径引用,包括绝对路径,都应该基于你的工作目录结构。

public 目录

有时你可能需要提供未在任何 Markdown 或主题组件中直接引用的静态资源,或者你可能希望使用原始文件名提供某些文件。此类文件的示例包括 robots.txt、favicons 和 PWA 图标。

你可以将这些文件放在源目录下的 public 目录中。例如,如果你的项目根目录是 ./docs 并且使用默认的源目录位置,那么你的 public 目录将是 ./docs/public

放置在 public 中的文件将会被复制到输出目录的根目录中。

请注意,你应该使用根绝对路径引用放置在 public 中的文件 - 例如,public/icon.svg 应该在源代码中始终引用为 /icon.svg

基础 URL

如果你的站点部署到非根 URL,你需要在 .vitepress/config.js 中设置 base 选项。例如,如果你计划将站点部署到 https://foo.github.io/bar/,那么 base 应该设置为 '/bar/'(它应该始终以斜杠开头和结尾)。

所有静态资源路径都会被自动处理以适应不同的 base 配置值。例如,如果你在 markdown 中有一个对 public 下资源的绝对引用:

md
![An image](../../image-inside-public.png)

当你更改 base 配置值时,你需要更新它。

但是,如果你正在编写一个主题组件,该组件动态链接到资源,例如其 src 基于主题配置值的图像:

vue
<img :src="theme.logoPath" alt="logo" />

在这种情况下,建议使用 VitePress 提供的 withBase helper 包装路径:

vue
<script setup>
import { withBase, useData } from 'vitepress'

const { theme } = useData()
</script>

<template>
  <img :src="withBase(theme.logoPath)" alt="logo" />
</template>

请注意,只有当你想要动态更改 base 时,才需要这样做。对于静态引用,只要它们以 / 开头,就会自动处理。

vitepress开发指南