VitePress 项目中的静态资源处理指南

VitePress 项目中的静态资源处理指南

vitepress Vite & Vue powered static site generator. 项目地址: https://gitcode.com/gh_mirrors/vi/vitepress

前言

在构建文档网站时，静态资源（如图片、字体、PDF等）的处理是一个重要环节。VitePress 作为基于 Vite 的静态站点生成器，提供了强大而灵活的静态资源处理能力。本文将详细介绍在 VitePress 项目中如何高效管理和引用各种静态资源。

静态资源引用方式

相对路径引用

在 Markdown 文件中，推荐使用相对路径来引用静态资源。这种方式直观且易于维护：

![示例图片](./assets/image.png)

[下载PDF文档](./files/document.pdf)

这种引用方式有以下几个特点：

1. 路径解析基于当前 Markdown 文件的位置
2. 适用于图片、PDF 等各类资源
3. 构建时会自动处理资源优化（如小图片的 base64 内联）

绝对路径引用

也可以使用基于项目根目录的绝对路径：

![示例图片](/images/logo.png)

绝对路径引用的特点：

1. 路径解析基于项目根目录
2. 适合在多个文件中引用同一资源
3. 构建时会自动处理路径转换

资源优化特性

VitePress 在构建过程中会对资源进行智能优化：

1. 自动哈希命名：所有引用的资源都会生成带有哈希值的文件名，便于缓存管理
2. 按需复制：只有实际被引用的资源才会被复制到输出目录
3. 小文件内联：小于 4KB 的图片会自动转为 base64 编码内联，减少 HTTP 请求
4. 路径自动转换：会根据项目配置自动处理路径前缀

这些优化行为可以通过 Vite 配置进行调整，满足不同项目的需求。

public 目录的特殊用途

对于需要直接复制到输出目录根部的资源，可以使用 public 目录。这个目录适合存放：

• 网站图标（favicon.ico）
• robots.txt 文件
• PWA 相关资源
• 需要保持原始文件名的资源

使用 public 目录的注意事项：

1. 资源必须通过根路径引用（如 /favicon.ico）
2. 不会被 Vite 处理或优化
3. 会原样复制到输出目录

部署路径配置

当项目部署在非根路径时（如 example.com/subpath/），需要在配置文件中设置 base 选项：

// .vitepress/config.js
export default {
  base: '/subpath/'
}

设置后，所有资源路径会自动适配这个基础路径。但在动态引用资源时，需要使用 withBase 辅助函数确保路径正确：

<script setup>
import { withBase } from 'vitepress'
</script>

<template>
  <img :src="withBase('/logo.png')" />
</template>

最佳实践建议

1. 优先使用相对路径：使资源引用更加直观和可维护
2. 合理使用 public 目录：仅用于必须保持原始文件名或位于根目录的资源
3. 大文件处理：对于大文件，考虑使用 CDN 或外部链接
4. 动态资源引用：使用 withBase 确保路径正确性
5. 资源组织：建议按类型组织资源目录（如 /images, /fonts 等）

通过合理利用 VitePress 的资源处理机制，可以构建出高效、可维护的文档网站。

vitepress Vite & Vue powered static site generator. 项目地址: https://gitcode.com/gh_mirrors/vi/vitepress