Vitepress项目部署Github Pages时自定义域名的样式问题解析

问题背景

在使用Vitepress构建文档网站并部署到Github Pages时，开发者可能会遇到一个常见问题：当配置自定义域名后，网站样式会丢失。这种情况通常发生在从Github提供的默认域名切换到自定义域名时。

问题原因分析

这个问题的根本原因在于Vitepress配置中的base参数设置不当。base参数决定了静态资源的基础路径，当它与实际访问路径不匹配时，就会导致CSS、JS等资源加载失败。

解决方案

情况一：使用Github默认域名

当使用Github提供的默认域名（如username.github.io/repo/）访问时，需要在Vitepress配置中明确设置base参数：

// .vitepress/config.js
export default {
  base: '/repo/', // 仓库名称
  // 其他配置...
}

情况二：使用自定义域名

当配置了自定义域名（如docs.example.com）后，应该将base参数恢复为默认值：

// .vitepress/config.js
export default {
  base: '/', // 默认值
  // 其他配置...
}

特殊情况说明

1. 个人主页仓库：如果仓库命名为username.github.io，它会被自动部署到username.github.io，这种情况下不需要设置base参数。

2. 子路径自定义域名：如果自定义域名包含子路径（如example.com/docs），则需要相应地设置base: '/docs/'。

最佳实践建议

1. 在部署前仔细检查域名配置与base参数的匹配关系
2. 清除浏览器缓存后再测试样式加载情况
3. 使用开发者工具检查资源加载路径是否正确
4. 考虑使用环境变量来动态设置base参数，以适应不同部署环境

总结

Vitepress项目在Github Pages上的部署问题大多源于路径配置不当。理解Github Pages的部署规则和Vitepress的base参数作用，就能有效避免这类样式丢失问题。对于需要同时支持多种访问方式的场景，可以考虑通过构建脚本自动调整配置参数。