解决running_page项目二级域名代理导致页面白屏问题

在部署running_page项目时，使用二级域名代理GitHub Pages服务时可能会遇到页面白屏的问题。本文将深入分析该问题的成因及解决方案。

问题现象分析

当用户通过腾讯云配置了二级域名running.guoxin.space指向GitHub Pages服务时，访问页面出现白屏现象。通过开发者工具检查发现，页面尝试从错误的路径加载静态资源：

• 期望路径：running.guoxin.space/assets/index-xxx.css
• 实际路径：guoxinl.github.io/running/assets/index-xxx.css

这种路径错配导致浏览器无法正确加载CSS和JavaScript等静态资源，从而引发页面白屏。

根本原因

该问题的核心在于项目构建时没有正确配置基础路径(base path)。默认情况下，Vite等现代前端构建工具会假设应用部署在域名根路径下。当实际部署路径与构建时假设的路径不一致时，就会导致资源加载失败。

解决方案

要解决这个问题，需要在项目构建时明确指定PATH_PREFIX环境变量：

1. 修改GitHub Actions工作流文件(gh-pages.yml)
2. 在构建命令中设置PATH_PREFIX环境变量为"/"

具体修改如下：

run: PATH_PREFIX=/ pnpm build

这一修改确保了构建生成的资源路径会基于域名根路径，而不是相对路径。

深入理解

现代前端项目通常使用模块打包工具(如Webpack、Vite等)进行构建。这些工具在构建时会处理资源路径问题：

1. 绝对路径：以/开头的路径，会基于当前域名根路径解析
2. 相对路径：基于当前页面URL路径解析

当项目部署在二级域名下时，必须确保所有资源引用都使用绝对路径。通过设置PATH_PREFIX=/，我们强制构建工具生成基于根路径的资源引用，从而确保无论项目实际部署在哪个路径下，资源都能被正确加载。

最佳实践

对于类似的项目部署场景，建议：

1. 明确项目的部署环境要求
2. 在构建配置中考虑不同部署环境的路径差异
3. 使用环境变量灵活控制构建行为
4. 部署后第一时间验证静态资源加载情况

通过遵循这些实践，可以避免类似的白屏问题，确保项目在各种部署环境下都能正常工作。