VitePress 资源处理完全指南:静态资源引用、public 目录、Base URL 与 CDN 部署
VitePress 资源处理完全指南:静态资源引用、public 目录、Base URL 与 CDN 部署
导读
本文围绕 VitePress 的资产处理(Asset Handling)机制展开,讲解如何在 Markdown、主题 *.vue 组件、样式与 .css 文件中正确引用图片、媒体与字体等静态资源,深入剖析 public 目录的用法、base 与 withBase 的运行时路径补全原理,以及通过 assetsBase 将构建产物托管到 CDN 的完整方案。读完本文,你将掌握一套可复制、可上线的资源引用与部署配置方法,并理解其背后的实现原理。本主题对应仓库文档为 docs/es/guide/asset-handling.md(英文版见 docs/en/guide/asset-handling.md)。
一、引用静态资源:相对路径与绝对路径
在 VitePress 中,所有 Markdown 文件都会被编译为 Vue 组件,并交由 Vite 处理。因此,你可以——而且应当——使用相对 URL 引用任何资源:
一张图片
除了 Markdown,你还可以在主题的 *.vue 组件、样式文件以及普通 .css 文件中引用静态资源。引用方式有两种:
- 绝对公开路径:以项目根目录为基准,例如
/assets/logo.png; - 相对路径:以当前文件所在的文件系统位置为基准,例如
./assets/logo.png。
其中相对路径的行为与你使用 Vite、Vue CLI 或 webpack 的 file-loader 时熟悉的体验一致:由打包器解析并重写最终 URL。
自动识别的资源类型
常见的图片(image)、媒体(media)和字体(font)文件类型会被自动检测并作为资源打包,无需任何额外配置。资源类型判定遵循 Vite 的 assetsInclude 规则,仓库在 src/node/plugins/assetsBasePlugin.ts 等构建插件中直接复用 Vite 的资产管线。
生产构建中的资源处理规则
所有被引用的资源——包括使用绝对路径引用的资源——在生产构建时都会被复制到输出目录,并以带哈希的文件名命名(如 logo-abc123.png),用于长缓存与内容指纹校验。以下三条规则需要特别注意:
- 从未被引用的资源不会被复制到输出目录,这避免了无用的产物膨胀;
- 小于 4KB 的图片资源会被内联为 Base64,直接嵌入打包产物,减少 HTTP 请求;该阈值可通过配置项
vite(见 site-config 参考文档)调整; - 所有静态路径引用(包括绝对路径)都应基于你的工作目录结构书写。
链接文件不会被当作资源处理
一个容易踩坑的细节:Markdown 中通过链接(<a>)引用的 PDF 或其他文档,不会被自动当作资源处理。要让这类链接文件可访问,必须手动将它们放入项目的 public 目录中(详见下一节)。这一点在 docs/en/guide/asset-handling.md 中以 tip 形式明确标注,部署时务必留意。
二、public 目录:存放不被引用或需保留原始文件名的资源
有时你需要提供一些没有被任何 Markdown 或主题组件直接引用的静态资源,或者希望某些文件以原始文件名对外提供。典型例子包括:
robots.txt- favicon 图标
- PWA 图标
放置位置与输出行为
将这些文件放入源目录(source directory)下的 public 目录即可。例如,若项目根目录是 ./docs 且使用默认的源目录位置,那么 public 目录就是 ./docs/public。关于源目录的概念,可参考 routing 指南。
public 中的资源会被原样复制到输出目录的根目录,不经过哈希重命名、不参与打包压缩。仓库中这一复制逻辑位于 src/node/build/bundle.ts:构建收尾阶段会将 config.publicDir 整个目录递归复制到 outDir,且会解析符号链接(dereference: true),避免复制已存在的符号链接文件时报 EEXIST 错误。
引用方式:必须使用根绝对路径
引用 public 中的文件时,必须使用根绝对路径。例如 public/icon.png 在源码中应始终写作 /icon.png,而不是相对路径或带 public/ 前缀的路径。
从源码实现看,这一约定贯穿整个链路:Markdown 图片插件在解析以 / 开头的 src 时,会直接基于 publicDir 拼接路径(见 src/node/markdown/plugins/image.ts 中 resolveLocalImage 对 src.startsWith('/') 的分支处理);该插件同时会自动为本地图片补充 width/height 属性以避免布局偏移(layout shift),并支持通过 lazyLoad 选项开启原生懒加载。
三、Base URL:非根路径部署的路径适配
如果你的站点部署在非根路径下,例如 GitHub Pages 的子路径 https://foo.github.io/bar/,就需要在 .vitepress/config.js 中设置 base 选项:
export default {
base: '/bar/' // 必须以斜杠开头和结尾
}
base 的默认值是 '/'。从 src/node/siteConfig.ts 的类型定义可以看出,base 通常以斜杠开头和结尾;你也可以使用 './' 让页面引用相对自身深度解析,从而实现在任意子路径下都能工作(即相对 base)。
静态引用自动适配 base
所有静态资源引用都会根据 base 的取值被自动处理。例如,当你在 Markdown 中通过绝对路径引用 public 中的资源:
一张图片
那么当你修改 base 配置时,完全不需要更新这行引用。因为静态路径在构建期会被统一重写。
动态路径:用 withBase 在运行时补全
然而,如果你在主题组件中动态构建资源路径——例如图片的 src 来自主题配置值——就需要额外处理。直接这样写是有问题的:
<img :src="theme.logoPath" />
此时推荐使用 VitePress 提供的 withBase 辅助函数,让 base 在运行时被前置拼接:
<script setup>
import { withBase, useData } from 'vitepress'
const { theme } = useData()
</script>
<template>
<img :src="withBase(theme.logoPath)" />
</template>
withBase 的运行时 API 说明见 runtime-api 参考文档。
withBase 的源码实现
withBase 的实现位于 src/client/app/utils.ts:
export function withBase(path: string) {
return EXTERNAL_URL_RE.test(path) || !path.startsWith('/')
? path
: joinPath(runtimeBase(), path)
}
它遵循三条规则:
- 外部 URL 不做处理:
EXTERNAL_URL_RE(定义于 src/shared/shared.ts,匹配https:、mailto:等协议前缀或//开头的协议相对地址)直接原样返回; - 非
/开头的路径不做处理:即相对路径不补 base; - 仅对
/开头的内部路径,通过joinPath(runtimeBase(), path)拼接运行时 base。joinPath会折叠多余的斜杠但保留协议后的//(如https://)。
runtimeBase() 则负责解析当前站点的运行时 base:对于常规 base 直接返回配置值;对于相对 base('./'),在 SSR 时使用占位符、开发环境使用 /、生产浏览器环境则从页面的 __VP_SITE_ROOT__ 中解析真实挂载路径。这就是为什么 withBase 能同时适配构建期与运行期、普通部署与相对 base 部署的原因。
四、assetsBase:将构建产物托管到 CDN
为了让生成产物——包括从 Markdown 或组件中导入的脚本、样式、字体和图片——与页面本身来自不同的源(origin),可以设置 assetsBase:
export default {
base: '/',
assetsBase: 'https://cdn.example.com/'
}
部署步骤
- 将构建输出中的
assets目录上传到 CDN,使其可通过https://cdn.example.com/assets/访问; - 将输出的其余部分按常规方式部署到你的站点;
public目录中的文件仍以base为基准引用,与页面保持同源。
CLI 传参
由于 assetsBase 的值通常随环境而变化(如 CI 中的 CDN 地址),也可以直接在命令行传入:
vitepress build docs --assetsBase "$CDN_URL"
配置约束与实现原理
从 src/node/siteConfig.ts 的类型定义看,assetsBase 必须是绝对 URL(或空字符串/base),且必须以斜杠结尾;它只作用于 assetsDir(默认 assets)下的构建产物。仍然使用 base 的包括:页面本身、withBase 链接以及 public/ 中的文件。
构建期实现位于 src/node/plugins/assetsBasePlugin.ts:该插件以 enforce: 'post' 注册,通过 Vite 的 experimental.renderBuiltUrl 钩子,在用户自定义的 renderBuiltUrl 之后链式处理——若用户钩子未返回结果且当前上下文类型为 asset,则返回 config.assetsBase + filename,从而把所有资产 URL 路由到 CDN 前缀。
警告:跨域需要 CORS
模块脚本(module scripts)始终以 CORS 模式获取,因此跨域 CDN 必须返回正确的 Access-Control-Allow-Origin 响应头,否则浏览器会拒绝加载脚本。这是从同源切换到 CDN 托管时最常见的故障点,部署后务必检查响应头。
五、配套:assetsDir 与资源哈希
与资源输出相关的还有一个配置项 assetsDir(默认 'assets',相对 outDir),它决定构建产物中资源目录的名称。assetsBase 的前缀规则必须与 outDir 的目录布局保持一致:每个资源的 URL = assetsBase 前缀 + 输出相对路径。理解了这三者的关系(base 管页面、assetsBase 管构建资产、public 走 base),就能在任意部署拓扑下正确配置资源路径。
总结
| 场景 | 推荐做法 | 关键配置/API |
|---|---|---|
| Markdown / 组件 / 样式中引用资源 | 使用相对路径或根绝对路径 | Vite 自动处理、4KB 以下 Base64 内联 |
| 未被引用或需保留原文件名的文件 | 放入 public 目录,用 /xxx.png 引用 |
publicDir(默认 srcDir/public) |
| 部署到子路径 | 设置 base: '/bar/',静态引用自动适配 |
base |
| 主题中动态拼接资源路径 | 用 withBase() 包裹 |
runtime-api |
| 构建产物走 CDN | 设置 assetsBase,上传 assets 目录,注意 CORS |
assetsBase、--assetsBase CLI 参数 |
实践要点:静态引用交给 VitePress 自动处理,动态路径用 withBase 兜底,非引用文件进 public,CDN 场景务必确认 CORS 头。相关配置项的完整定义可进一步查阅 site-config 参考文档。