静态资源管理

本章节介绍如何在 VitePress 中管理和使用静态资源。

public 目录

public 目录用于存放不需要经过构建处理的静态资源。

目录结构

docs/
├── .vitepress/
├── public/
│   ├── images/
│   │   ├── logo.png
│   │   └── hero.jpg
│   ├── fonts/
│   │   └── custom.woff2
│   ├── favicon.ico
│   └── robots.txt
└── index.md

引用 public 资源

使用绝对路径引用：

![Logo](/images/logo.png)

<img src="/images/logo.png" alt="Logo">

background-image: url(/images/bg.png);

常见用途

• 网站图标：favicon.ico、apple-touch-icon.png
• Logo 和品牌图片
• SEO 文件：robots.txt、sitemap.xml
• 字体文件

assets 目录

存放在 src 或项目根目录的资源会被 Vite 处理。

引用 assets 资源

在 Markdown 中：

<img src="./images/screenshot.png" alt="截图">

在 Vue 组件中：

<script setup>
import logo from './assets/logo.png'
</script>

<template>
  <img :src="logo" alt="Logo">
</template>

在 CSS 中：

.bg {
  background-image: url('./assets/bg.png');
}

图片处理

支持的格式

• PNG、JPG、JPEG、GIF
• SVG
• WebP（推荐）
• AVIF

图片优化建议

1. 使用现代格式：WebP 或 AVIF
2. 压缩图片：使用工具如 TinyPNG
3. 响应式图片：提供多种尺寸

图片懒加载

<template>
  <img 
    src="/images/large.jpg" 
    loading="lazy"
    alt="懒加载图片"
  >
</template>

SVG 处理

内联 SVG

<svg viewBox="0 0 24 24" width="24" height="24">
  <path fill="currentColor" d="M13.5.67s.74 2.65.74 4.8c0 2.06-1.35 3.73-3.41 3.73-2.07 0-3.63-1.67-3.63-3.73l.03-.36C5.21 7.51 4 10.62 4 14c0 4.42 3.58 8 8 8s8-3.58 8-8C20 8.61 17.41 3.8 13.5.67zM11.71 19c-1.78 0-3.22-1.4-3.22-3.14 0-1.62 1.05-2.76 2.81-3.12 1.77-.36 3.6-1.21 4.62-2.58.39 1.29.59 2.65.59 4.04 0 2.65-2.15 4.8-4.8 4.8z"/>
</svg>

作为组件导入

<script setup>
import MyIcon from './icons/my-icon.svg?component'
</script>

<template>
  <MyIcon class="icon" />
</template>

作为 URL 导入

<script setup>
import iconUrl from './icons/my-icon.svg?url'
</script>

<template>
  <img :src="iconUrl" alt="图标">
</template>

字体处理

本地字体

将字体文件放在 public/fonts/ 目录：

@font-face {
  font-family: 'CustomFont';
  src: url('/fonts/custom.woff2') format('woff2');
  font-weight: normal;
  font-style: normal;
  font-display: swap;
}

body {
  font-family: 'CustomFont', sans-serif;
}

Google Fonts

在配置中添加：

export default defineConfig({
  head: [
    ['link', { 
      rel: 'preconnect', 
      href: 'https://fonts.googleapis.com' 
    }],
    ['link', { 
      rel: 'preconnect', 
      href: 'https://fonts.gstatic.com',
      crossorigin: ''
    }],
    ['link', { 
      rel: 'stylesheet', 
      href: 'https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap' 
    }]
  ]
})

其他资源

JSON 文件

import data from './data.json'

console.log(data)

文件下载

将文件放在 public 目录，提供下载链接：

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

视频和音频

<video controls>
  <source src="/videos/demo.mp4" type="video/mp4">
</video>

<audio controls>
  <source src="/audio/music.mp3" type="audio/mpeg">
</audio>

资源组织最佳实践

推荐目录结构

docs/
├── .vitepress/
├── public/
│   ├── images/          # 图片资源
│   │   ├── logo.svg
│   │   ├── hero/
│   │   └── icons/
│   ├── fonts/           # 字体文件
│   ├── files/           # 下载文件
│   └── favicon.ico
├── assets/              # 需要处理的资源
│   └── images/
└── index.md

命名规范

• 使用小写字母
• 用连字符分隔单词：hero-image.png
• 避免中文和特殊字符

优化建议

资源类型	建议
图片	使用 WebP，压缩后 < 100KB
SVG	优化路径，移除无用属性
字体	使用子集化，woff2 格式
视频	使用流媒体或外部托管

下一步

学习 路由详解 了解页面路由配置。