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

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

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

前言

在构建文档网站时，静态资源（如图片、字体、PDF等）的管理是必不可少的一部分。Vitepress 基于 Vite 构建，提供了强大而灵活的静态资源处理能力。本文将详细介绍如何在 Vitepress 项目中高效管理和使用静态资源。

静态资源引用方式

相对路径引用

在 Markdown 文件中，你可以直接使用相对路径引用资源：

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

这种方式适用于：

• 图片
• 视频
• 字体文件
• 其他媒体资源

Vitepress 会自动处理这些资源，在生产环境中会生成带有哈希值的文件名，并优化小文件（小于4KB）为 base64 格式。

绝对路径引用

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

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

注意：绝对路径是基于项目文件结构，而不是基于服务器根目录。

特殊资源处理

非自动处理的资源

某些资源类型（如 PDF、Word 文档等）不会被自动视为静态资源。要使这些文件可用，你需要：

1. 将它们放置在 public 目录下
2. 使用绝对路径引用它们

公共资源目录

public 目录用于存放：

• 不需要被构建处理的资源
• 需要保持原文件名不变的资源
• 网站图标（favicon.ico）
• robots.txt 文件
• PWA 相关资源

使用规范：

1. 默认位置：./docs/public（假设项目根目录是 ./docs）
2. 引用时使用根绝对路径（如 /favicon.ico）
3. 文件会被原样复制到输出目录

基础 URL 配置

当你的网站部署在非根路径时（如 https://example.com/my-site/），需要在配置中设置 base 选项：

// .vitepress/config.js
export default {
  base: '/my-site/'
}

自动处理机制：

• 所有静态资源路径会自动适配 base 配置
• 你不需要手动修改资源引用路径

动态资源处理

在主题组件中动态引用资源时，需要使用 withBase 辅助函数：

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

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

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

为什么需要 withBase：

• 确保动态生成的路径正确适配 base 配置
• 避免硬编码路径导致的部署问题

最佳实践建议

1. 资源组织：

   • 图片等媒体资源建议放在 public 或专门的 assets 目录
   • 按功能或页面分类存放资源

2. 命名规范：

   • 使用小写字母和连字符（如 user-avatar.png）
   • 避免使用空格和特殊字符

3. 性能优化：

   • 大图片建议压缩后再使用
   • 考虑使用 WebP 等现代图片格式

4. 开发环境注意：

   • 修改 public 目录下的文件需要重启开发服务器
   • 其他资源修改会触发热更新

常见问题解答

Q：为什么我的 PDF 文件无法访问？ A：PDF 文件需要放在 public 目录下，并使用绝对路径引用。

Q：如何更改资源内联的大小阈值？ A：可以通过 Vite 配置修改 assetsInlineLimit 选项。

Q：部署后资源路径错误怎么办？ A：检查是否正确配置了 base 选项，确保与部署路径匹配。

通过本文的介绍，你应该已经掌握了 Vitepress 中静态资源处理的各项技巧。合理利用这些功能，可以让你更高效地构建文档网站。

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