Vitepress项目在二级目录部署时的静态资源加载问题解析

问题背景

在基于Vitepress构建的文档站点部署过程中，当项目需要部署到域名的二级目录时（例如https://example.com/subdir/），开发者可能会遇到静态资源加载异常的问题。这类问题通常表现为：首页可以正常访问，但直接打开子页面时出现样式丢失、脚本加载失败等情况。

问题现象分析

从实际案例来看，当Vitepress项目部署在二级目录时，会出现以下两种不同的表现：

1. 访问二级目录首页（如/tcq/）时，所有功能正常，页面渲染完整
2. 直接访问子页面（如/tcq/basic/download.html）时，静态资源（CSS、JS等）加载失败，返回404错误

这种差异表明Vitepress在构建时对资源路径的处理存在特殊情况，特别是在非根目录部署场景下。

问题根源

经过技术分析，该问题的核心原因在于：

1. Vitepress默认假设项目部署在域名根目录下，生成的资源引用路径都是绝对路径
2. 当部署到二级目录时，这些绝对路径无法正确解析到实际资源位置
3. 首页能正常工作的原因是Vitepress对首页做了特殊处理，而子页面则没有这种处理

解决方案

针对这一问题，Viteppress提供了标准的解决方案：

1. 使用public目录存放静态资源：将需要保持原始路径的静态文件放置在项目根目录的public文件夹下。在构建过程中，public目录中的内容会被原样复制到输出目录，保持相对路径不变。

2. 配置base选项：在Vitepress配置中正确设置base参数，指定项目部署的二级目录路径。这能确保生成的资源引用路径包含正确的二级目录前缀。

3. 资源引用方式：对于需要在Markdown或Vue组件中引用的静态资源，使用相对路径或经过base处理后的路径。

实施建议

对于遇到类似问题的开发者，建议按照以下步骤操作：

1. 检查项目结构，确认所有静态资源是否放置在正确的位置
2. 在vitepress配置文件中明确设置base选项，值为二级目录路径
3. 对于需要保持路径不变的资源，移动到public目录
4. 重新构建并测试各个页面的资源加载情况

总结

Vitepress作为现代化的文档工具，虽然提供了便捷的静态站点生成能力，但在特殊部署场景下仍需开发者注意资源配置。通过合理使用public目录和正确配置base参数，可以完美解决二级目录部署时的资源加载问题，确保文档站点在各种访问路径下都能正常工作。